{ "openapi": "3.0.3", "info": { "description": "Welcome to Cloudflare's API documentation site. We are experimenting with an updated version of our API documentation - check out [developers.cloudflare.com/api-next/](https://developers.cloudflare.com/api-next/) to test out the new experience.\n\nTo get started using Cloudflare's products and services via the API, refer to [how to interact with Cloudflare](https://developers.cloudflare.com/fundamentals/basic-tasks/interact-with-cloudflare/), which covers using tools like [Terraform](https://developers.cloudflare.com/terraform/#cloudflare-terraform) and the [official SDKs](https://developers.cloudflare.com/fundamentals/api/reference/sdks/) to maintain your Cloudflare resources.\n\nUsing the Cloudflare API requires authentication so that Cloudflare knows who is making requests and what permissions you have. Create an API token to grant access to the API to perform actions. You can also authenticate with [API keys](https://developers.cloudflare.com/fundamentals/api/get-started/keys/), but these keys have [several limitations](https://developers.cloudflare.com/fundamentals/api/get-started/keys/#limitations) that make them less secure than API tokens. Whenever possible, use API tokens to interact with the Cloudflare API.\n\nTo create an API token, from the Cloudflare dashboard, go to My Profile > API Tokens and select Create Token. For more information on how to create and troubleshoot API tokens, refer to\nour [API fundamentals](https://developers.cloudflare.com/fundamentals/api/).\n\nFor information regarding rate limits, refer to our [API Rate Limits](https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/platform/limits/#api-rate-limits).\n\nTotally new to Cloudflare? [Start here](https://developers.cloudflare.com/fundamentals/get-started/).", "license": { "name": "BSD-3-Clause", "url": "https://opensource.org/licenses/BSD-3-Clause" }, "title": "Cloudflare API", "version": "4.0.0" }, "servers": [ { "description": "Client API", "url": "https://api.cloudflare.com/client/v4" } ], "paths": { "/accounts": { "get": { "operationId": "accounts-list-accounts", "summary": "List Accounts", "description": "List all accounts you have ownership or verified access to.", "parameters": [ { "name": "name", "in": "query", "schema": { "description": "Name of the account.", "type": "string", "example": "example.com", "readOnly": true } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Maximum number of results per page.", "type": "number", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "direction", "in": "query", "schema": { "description": "Direction to order results.", "type": "string", "example": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "List Accounts response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_response_collection_accounts" } } } }, "4XX": { "description": "List Accounts response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Accounts" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "account-creation", "summary": "Create an account", "description": "Create an account (only available for tenant admins at this time)", "requestBody": { "description": "Parameters for account creation", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_create-account" } } } }, "responses": { "200": { "description": "Account Creation Success Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_response_single_account" } } } }, "4XX": { "description": "Account Creation Failure Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Accounts" ], "x-cfPlanAvailability": { "business": false, "enterprise": false, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/move": { "post": { "operationId": "Accounts_batchMoveAccounts", "summary": "Batch move accounts", "description": "Batch move a collection of accounts to a specific organization. ⚠️ Not implemented.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_ids": { "description": "Move these accounts to the destination organization.", "type": "array", "items": { "type": "string" } }, "destination_organization_id": { "description": "Move accounts to this organization ID.", "type": "string" } }, "required": [ "account_ids", "destination_organization_id" ] } } } }, "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "$ref": "#/components/schemas/organizations-api_BatchAccountMoveResponse" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Accounts" ], "x-fern-availability": "alpha", "x-fern-sdk-group-name": "account.batch", "x-fern-sdk-method-name": "move" } }, "/accounts/{accountId}/v1/images": { "get": { "operationId": "get_ImageList", "summary": "Get a list of images", "description": "List images for an account.", "parameters": [ { "name": "accountId", "in": "path", "description": "Account identifier.", "required": true, "schema": { "description": "Account identifier.", "type": "string" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "schema": { "description": "Number of items per page", "type": "integer", "default": 1000, "maximum": 10000, "minimum": 10 } }, { "name": "continuation_token", "in": "query", "description": "Continuation token for a next page. List images V2 returns continuation_token", "schema": { "description": "Continuation token for a next page. List images V2 returns continuation_token", "type": "string" } }, { "name": "creator", "in": "query", "description": "Internal user ID set within the creator field. Setting to empty string will return images where creator field is not set", "schema": { "description": "Internal user ID set within the creator field. Setting to empty string will return images where creator field is not set", "type": "string" } }, { "name": "sort_order", "in": "query", "description": "Sorting order by upload time", "schema": { "description": "Sorting order by upload time", "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Upload an image response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "continuation_token": { "description": "Continuation token for a next page. List images V2 returns continuation_token", "type": "string", "nullable": true }, "images": { "type": "array", "items": { "properties": { "creator": { "type": "string" }, "filename": { "type": "string" }, "id": { "type": "string" }, "meta": { "type": "object" }, "requireSignedURLs": { "type": "boolean" }, "uploaded": { "type": "string", "format": "date-time" }, "variants": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "uploaded", "filename", "meta", "requireSignedURLs", "variants" ], "type": "object" } } }, "required": [ "images", "continuation_token" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "4XX": { "description": "Upload an image response failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Images" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "images.v1", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "post_ImageUpload", "summary": "Upload a new Image", "description": "Upload a new image.", "parameters": [ { "name": "accountId", "in": "path", "description": "Account identifier.", "required": true, "schema": { "description": "Account identifier.", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "creator": { "description": "Can set the creator field with an internal user ID.", "type": "string" }, "file": { "description": "An image binary data. Only needed when type is uploading a file.", "type": "string", "format": "binary" }, "id": { "description": "Optional Image Custom ID. Up to 1024 chars. Can include any number of subpaths, and utf8 characters. Cannot start nor end with a / (forward slash). Cannot be a UUID.", "type": "string" }, "metadata": { "description": "User modifiable key-value store. Can use used for keeping references to another system of record for managing images.", "type": "object" }, "requireSignedURLs": { "description": "Indicates whether the image requires a signature token for the access.", "type": "boolean", "default": false }, "url": { "description": "A URL to fetch an image from origin. Only needed when type is uploading from a URL.", "type": "string" } } } } } }, "responses": { "200": { "description": "Upload an image response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "creator": { "type": "string" }, "filename": { "type": "string" }, "id": { "type": "string" }, "meta": { "type": "object" }, "requireSignedURLs": { "type": "boolean" }, "uploaded": { "type": "string", "format": "date-time" }, "variants": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "uploaded", "filename", "meta", "requireSignedURLs", "variants" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "4XX": { "description": "Upload an image response failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Images" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "images", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{accountId}/v1/images/{imageId}": { "delete": { "operationId": "delete_ImageDelete", "summary": "Delete an image", "description": "Delete an image.", "parameters": [ { "name": "accountId", "in": "path", "description": "Account identifier.", "required": true, "schema": { "description": "Account identifier.", "type": "string" } }, { "name": "imageId", "in": "path", "description": "Image identifier.", "required": true, "schema": { "description": "Image identifier.", "type": "string" } } ], "responses": { "200": { "description": "Delete image response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "4XX": { "description": "Delete an image response failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Images" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "images", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "get_ImageGet", "summary": "Get an image data", "description": "Get image metadata.", "parameters": [ { "name": "accountId", "in": "path", "description": "Account identifier.", "required": true, "schema": { "description": "Account identifier.", "type": "string" } }, { "name": "imageId", "in": "path", "description": "Image identifier.", "required": true, "schema": { "description": "Image identifier.", "type": "string" } } ], "responses": { "200": { "description": "Image details response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "creator": { "type": "string" }, "filename": { "type": "string" }, "id": { "type": "string" }, "meta": { "type": "object" }, "requireSignedURLs": { "type": "boolean" }, "uploaded": { "type": "string", "format": "date-time" }, "variants": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "uploaded", "filename", "meta", "requireSignedURLs", "variants" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "4XX": { "description": "Image details response failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Images" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "images", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "patch_ImageEdit", "summary": "Update an image", "description": "Update an image's metadata.", "parameters": [ { "name": "accountId", "in": "path", "description": "Account identifier.", "required": true, "schema": { "description": "Account identifier.", "type": "string" } }, { "name": "imageId", "in": "path", "description": "Image identifier.", "required": true, "schema": { "description": "Image identifier.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "creator": { "description": "Image creator", "type": "string" }, "metadata": { "description": "Image metadata", "nullable": true }, "requireSignedURLs": { "description": "Required signed url", "type": "boolean" } } } } } }, "responses": { "200": { "description": "Edit image response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "4XX": { "description": "Edit image response failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Images" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "images", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "put_ImageDirectUpload", "summary": "Direct upload a new Image", "description": "Upload an image to a specific image ID.", "parameters": [ { "name": "accountId", "in": "path", "description": "Account identifier.", "required": true, "schema": { "description": "Account identifier.", "type": "string" } }, { "name": "imageId", "in": "path", "description": "Image identifier.", "required": true, "schema": { "description": "Image identifier.", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "description": "An image binary data. Only needed when type is uploading a file.", "type": "string", "format": "binary" }, "url": { "description": "A URL to fetch an image from origin. Only needed when type is uploading from a URL.", "type": "string" } } } } } }, "responses": { "200": { "description": "Upload an image response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "creator": { "type": "string" }, "filename": { "type": "string" }, "id": { "type": "string" }, "meta": { "type": "object" }, "requireSignedURLs": { "type": "boolean" }, "uploaded": { "type": "string", "format": "date-time" }, "variants": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "uploaded", "filename", "meta", "requireSignedURLs", "variants" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "4XX": { "description": "Upload an image response failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Images" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "images.v1.direct-uploads", "x-fern-sdk-method-name": "upload", "x-forge-hidden": true } }, "/accounts/{accountId}/v1/images/{imageId}/blob": { "get": { "operationId": "get_ImageGetBlob", "summary": "Get an image", "description": "Get image as a blob.", "parameters": [ { "name": "accountId", "in": "path", "description": "Account identifier.", "required": true, "schema": { "description": "Account identifier.", "type": "string" } }, { "name": "imageId", "in": "path", "description": "Image identifier.", "required": true, "schema": { "description": "Image identifier.", "type": "string" } } ], "responses": { "200": { "description": "Get image response", "content": { "image/*": { "schema": { "format": "binary" } } } }, "4XX": { "description": "Get image response failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Images" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "images", "x-fern-sdk-method-name": "get-blob", "x-forge-hidden": true } }, "/accounts/{accountId}/v2/images": { "get": { "operationId": "get__accounts_accountId_v2_images", "summary": "Get a list of images", "description": "List images for an account.", "parameters": [ { "name": "accountId", "in": "path", "description": "Account identifier.", "required": true, "schema": { "description": "Account identifier.", "type": "string" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "schema": { "description": "Number of items per page", "type": "integer", "default": 1000, "maximum": 10000, "minimum": 10 } }, { "name": "continuation_token", "in": "query", "description": "Continuation token for a next page. List images V2 returns continuation_token", "schema": { "description": "Continuation token for a next page. List images V2 returns continuation_token", "type": "string" } }, { "name": "creator", "in": "query", "description": "Internal user ID set within the creator field. Setting to empty string will return images where creator field is not set", "schema": { "description": "Internal user ID set within the creator field. Setting to empty string will return images where creator field is not set", "type": "string" } }, { "name": "sort_order", "in": "query", "description": "Sorting order by upload time", "schema": { "description": "Sorting order by upload time", "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Upload an image response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "continuation_token": { "description": "Continuation token for a next page. List images V2 returns continuation_token", "type": "string", "nullable": true }, "images": { "type": "array", "items": { "properties": { "creator": { "type": "string" }, "filename": { "type": "string" }, "id": { "type": "string" }, "meta": { "type": "object" }, "requireSignedURLs": { "type": "boolean" }, "uploaded": { "type": "string", "format": "date-time" }, "variants": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "uploaded", "filename", "meta", "requireSignedURLs", "variants" ], "type": "object" } } }, "required": [ "images", "continuation_token" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "4XX": { "description": "Upload an image response failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Images" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "images", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{accountId}/v2/images/direct_upload": { "post": { "operationId": "post_DirectUploadLink", "summary": "Create authenticated direct upload URL", "description": "Create an authenticated direct upload URL for an image.", "parameters": [ { "name": "accountId", "in": "path", "description": "Account identifier.", "required": true, "schema": { "description": "Account identifier.", "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "expiry": { "description": "The date after which the upload will not be accepted. Minimum: Now + 2 minutes.", "type": "string" }, "id": { "description": "Optional Image Custom ID. Up to 1024 chars. Can include any number of subpaths, and utf8 characters. Cannot start nor end with a / (forward slash). Cannot be a UUID.", "type": "string" }, "metadata": { "description": "User modifiable key-value store. Can use used for keeping references to another system of record for managing images.", "type": "object" }, "requireSignedURLs": { "description": "Indicates whether the image requires a signature token for the access.", "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Create an authenticated direct upload url response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "id": { "description": "Image id", "type": "string" }, "uploadURL": { "description": "Url a future image should be uploaded to", "type": "string" } }, "required": [ "id", "uploadURL" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "4XX": { "description": "Create an authenticated direct upload url response failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Images" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "images", "x-fern-sdk-method-name": "direct-upload", "x-forge-hidden": true } }, "/accounts/{accountId}/zones/{zoneId}/v1/images/flows": { "get": { "operationId": "get_FlowsGet", "summary": "Get transformation flows", "description": "Get the current transformation flows configuration for a zone.", "parameters": [ { "name": "accountId", "in": "path", "description": "Account identifier.", "required": true, "schema": { "description": "Account identifier.", "type": "string" } }, { "name": "zoneId", "in": "path", "description": "Zone identifier.", "required": true, "schema": { "description": "Zone identifier.", "type": "string", "x-auditable": true } } ], "responses": { "200": { "description": "Get flows config", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "etag": { "type": "string" }, "flows": { "type": "array", "items": { "oneOf": [ { "properties": { "enabled": { "type": "boolean", "x-auditable": true }, "provider": { "type": "string", "enum": [ "fastly" ], "x-auditable": true }, "type": { "type": "string", "enum": [ "provider" ] }, "version": { "type": "number" } }, "required": [ "enabled", "type", "provider", "version" ], "type": "object" }, { "properties": { "enabled": { "type": "boolean", "x-auditable": true }, "name": { "type": "string", "x-auditable": true }, "transformations": { "type": "array", "items": { "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ], "type": "object" } }, "trigger": { "oneOf": [ { "properties": { "triggers": { "type": "array", "items": { "nullable": true }, "minItems": 1 }, "type": { "type": "string", "enum": [ "and" ] } }, "required": [ "type", "triggers" ], "type": "object" }, { "properties": { "triggers": { "type": "array", "items": { "nullable": true }, "minItems": 1 }, "type": { "type": "string", "enum": [ "or" ] } }, "required": [ "type", "triggers" ], "type": "object" }, { "properties": { "paths": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "path" ] } }, "required": [ "type", "paths" ], "type": "object" }, { "properties": { "extensions": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "extension" ] } }, "required": [ "type", "extensions" ], "type": "object" }, { "properties": { "params": { "type": "array", "items": { "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ], "type": "object" } }, "type": { "type": "string", "enum": [ "query-param" ] } }, "required": [ "type", "params" ], "type": "object" } ] }, "type": { "type": "string", "enum": [ "custom" ] } }, "required": [ "enabled", "type", "name", "trigger", "transformations" ], "type": "object" } ] }, "maxItems": 10 }, "version": { "type": "number", "enum": [ 2 ] } }, "required": [ "version", "flows" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "4XX": { "description": "Get flows config failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Images" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "images.flows", "x-fern-sdk-method-name": "get", "x-stability": "stable" }, "put": { "operationId": "put_FlowsUpdate", "summary": "Update transformation flows", "description": "Replace the entire transformation flows configuration for a zone.", "parameters": [ { "name": "accountId", "in": "path", "description": "Account identifier.", "required": true, "schema": { "description": "Account identifier.", "type": "string" } }, { "name": "zoneId", "in": "path", "description": "Zone identifier.", "required": true, "schema": { "description": "Zone identifier.", "type": "string", "x-auditable": true } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "etag": { "type": "string" }, "flows": { "type": "array", "items": { "oneOf": [ { "properties": { "enabled": { "type": "boolean", "x-auditable": true }, "provider": { "type": "string", "enum": [ "fastly" ], "x-auditable": true }, "type": { "type": "string", "enum": [ "provider" ] }, "version": { "type": "number" } }, "required": [ "enabled", "type", "provider", "version" ], "type": "object" }, { "properties": { "enabled": { "type": "boolean", "x-auditable": true }, "name": { "type": "string", "x-auditable": true }, "transformations": { "type": "array", "items": { "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ], "type": "object" } }, "trigger": { "oneOf": [ { "properties": { "triggers": { "type": "array", "items": { "nullable": true }, "minItems": 1 }, "type": { "type": "string", "enum": [ "and" ] } }, "required": [ "type", "triggers" ], "type": "object" }, { "properties": { "triggers": { "type": "array", "items": { "nullable": true }, "minItems": 1 }, "type": { "type": "string", "enum": [ "or" ] } }, "required": [ "type", "triggers" ], "type": "object" }, { "properties": { "paths": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "path" ] } }, "required": [ "type", "paths" ], "type": "object" }, { "properties": { "extensions": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "extension" ] } }, "required": [ "type", "extensions" ], "type": "object" }, { "properties": { "params": { "type": "array", "items": { "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ], "type": "object" } }, "type": { "type": "string", "enum": [ "query-param" ] } }, "required": [ "type", "params" ], "type": "object" } ] }, "type": { "type": "string", "enum": [ "custom" ] } }, "required": [ "enabled", "type", "name", "trigger", "transformations" ], "type": "object" } ] }, "maxItems": 10 }, "version": { "type": "number", "enum": [ 2 ] } }, "required": [ "version", "flows" ] } } } }, "responses": { "200": { "description": "Update flows config", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "etag": { "type": "string" }, "flows": { "type": "array", "items": { "oneOf": [ { "properties": { "enabled": { "type": "boolean", "x-auditable": true }, "provider": { "type": "string", "enum": [ "fastly" ], "x-auditable": true }, "type": { "type": "string", "enum": [ "provider" ] }, "version": { "type": "number" } }, "required": [ "enabled", "type", "provider", "version" ], "type": "object" }, { "properties": { "enabled": { "type": "boolean", "x-auditable": true }, "name": { "type": "string", "x-auditable": true }, "transformations": { "type": "array", "items": { "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ], "type": "object" } }, "trigger": { "oneOf": [ { "properties": { "triggers": { "type": "array", "items": { "nullable": true }, "minItems": 1 }, "type": { "type": "string", "enum": [ "and" ] } }, "required": [ "type", "triggers" ], "type": "object" }, { "properties": { "triggers": { "type": "array", "items": { "nullable": true }, "minItems": 1 }, "type": { "type": "string", "enum": [ "or" ] } }, "required": [ "type", "triggers" ], "type": "object" }, { "properties": { "paths": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "path" ] } }, "required": [ "type", "paths" ], "type": "object" }, { "properties": { "extensions": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "extension" ] } }, "required": [ "type", "extensions" ], "type": "object" }, { "properties": { "params": { "type": "array", "items": { "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ], "type": "object" } }, "type": { "type": "string", "enum": [ "query-param" ] } }, "required": [ "type", "params" ], "type": "object" } ] }, "type": { "type": "string", "enum": [ "custom" ] } }, "required": [ "enabled", "type", "name", "trigger", "transformations" ], "type": "object" } ] }, "maxItems": 10 }, "version": { "type": "number", "enum": [ 2 ] } }, "required": [ "version", "flows" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "4XX": { "description": "Update flows config failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Images" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "images.flows", "x-fern-sdk-method-name": "update", "x-stability": "stable" } }, "/accounts/{account_identifier}/custom_pages": { "get": { "operationId": "custom-pages-for-an-account-list-custom-pages", "summary": "List custom pages", "description": "Fetches all the custom pages at the account level.", "parameters": [ { "name": "account_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } } ], "responses": { "200": { "description": "List custom pages response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_custom_page_result_list" } } } }, "4XX": { "description": "List custom pages response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_custom_page_result_list" }, { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom pages for an account" ], "x-api-token-group": [ "Zero Trust: PII Read", "Account Custom Pages Write", "Account Custom Pages Read", "Account Settings Write", "Account Settings Read" ], "x-cfPermissionsRequired": { "enum": [ "#organization:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_identifier}/custom_pages/assets": { "get": { "operationId": "custom-assets-for-an-account-list-custom-assets", "summary": "List custom assets", "description": "Fetches all the custom assets at the account level.", "parameters": [ { "name": "account_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "List custom assets response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_custom_asset_result_list" } } } }, "4XX": { "description": "List custom assets response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_custom_asset_result_list" }, { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom assets for an account" ], "x-api-token-group": null, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages.assets.list.custom", "x-fern-sdk-method-name": "assets", "x-forge-hidden": true }, "post": { "operationId": "custom-assets-for-an-account-create-a-custom-asset", "summary": "Create a custom asset", "description": "Creates a new custom asset at the account level.", "parameters": [ { "name": "account_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "description": { "$ref": "#/components/schemas/custom-pages_asset_description" }, "name": { "$ref": "#/components/schemas/custom-pages_asset_name" }, "url": { "$ref": "#/components/schemas/custom-pages_asset_url" } }, "required": [ "name", "description", "url" ] } } } }, "responses": { "200": { "description": "Create custom asset response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_custom_asset_result" } } } }, "4XX": { "description": "Create custom asset response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_custom_asset_result" }, { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom assets for an account" ], "x-api-token-group": null, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages.assets.create.custom", "x-fern-sdk-method-name": "asset", "x-forge-hidden": true } }, "/accounts/{account_identifier}/custom_pages/assets/{asset_name}": { "delete": { "operationId": "custom-assets-for-an-account-delete-a-custom-asset", "summary": "Delete a custom asset", "description": "Deletes an existing custom asset.", "parameters": [ { "name": "asset_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_asset_name" } }, { "name": "account_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } } ], "responses": { "204": { "description": "Delete a custom asset response" }, "4XX": { "description": "Delete a custom asset response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom assets for an account" ], "x-api-token-group": null, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages.assets.delete.custom", "x-fern-sdk-method-name": "asset", "x-forge-hidden": true }, "get": { "operationId": "custom-assets-for-an-account-get-a-custom-asset", "summary": "Get a custom asset", "description": "Fetches the details of a custom asset.", "parameters": [ { "name": "asset_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_asset_name" } }, { "name": "account_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } } ], "responses": { "200": { "description": "Get a custom asset response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_custom_asset_result" } } } }, "4XX": { "description": "Get a custom asset response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_custom_asset_result" }, { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom assets for an account" ], "x-api-token-group": null, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages.assets.get.custom", "x-fern-sdk-method-name": "asset", "x-forge-hidden": true }, "put": { "operationId": "custom-assets-for-an-account-update-a-custom-asset", "summary": "Update a custom asset", "description": "Updates the configuration of an existing custom asset.", "parameters": [ { "name": "asset_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_asset_name" } }, { "name": "account_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "description": { "$ref": "#/components/schemas/custom-pages_asset_description" }, "url": { "$ref": "#/components/schemas/custom-pages_asset_url" } }, "required": [ "description", "url" ] } } } }, "responses": { "200": { "description": "Update a custom asset response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_custom_asset_result" } } } }, "4XX": { "description": "Update a custom asset response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_custom_asset_result" }, { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom assets for an account" ], "x-api-token-group": null, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages.assets.update.custom", "x-fern-sdk-method-name": "asset", "x-forge-hidden": true } }, "/accounts/{account_identifier}/custom_pages/preview_tokens": { "post": { "operationId": "custom-pages-for-an-account-create-preview-token", "summary": "Create a preview token", "description": "Creates a signed JWT token used to preview custom pages before they are published.", "parameters": [ { "name": "account_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_preview_request" } } } }, "responses": { "200": { "description": "Create preview token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_preview_token_result" } } } }, "4XX": { "description": "Create preview token response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_preview_token_result" }, { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom pages for an account" ], "x-api-token-group": [ "Zero Trust: PII Read", "Account Custom Pages Write", "Account Custom Pages Read", "Account Settings Write", "Account Settings Read" ], "x-cfPermissionsRequired": { "enum": [ "#organization:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages.account-custom-pages.preview-tokens", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_identifier}/custom_pages/{identifier}": { "get": { "operationId": "custom-pages-for-an-account-get-a-custom-page", "summary": "Get a custom page", "description": "Fetches the details of a custom page.", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_error_page_type" } }, { "name": "account_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } } ], "responses": { "200": { "description": "Get a custom page response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_custom_page_result" } } } }, "4XX": { "description": "Get a custom page response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_custom_page_result" }, { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom pages for an account" ], "x-api-token-group": [ "Zero Trust: PII Read", "Account Custom Pages Write", "Account Custom Pages Read", "Account Settings Write", "Account Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "custom-pages-for-an-account-update-a-custom-page", "summary": "Update a custom page", "description": "Updates the configuration of an existing custom page.", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_error_page_type" } }, { "name": "account_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "state": { "$ref": "#/components/schemas/custom-pages_state" }, "url": { "$ref": "#/components/schemas/custom-pages_url" } }, "required": [ "url", "state" ] } } } }, "responses": { "200": { "description": "Update a custom page response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_custom_page_result" } } } }, "4XX": { "description": "Update a custom page response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_custom_page_result" }, { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom pages for an account" ], "x-api-token-group": [ "Account Custom Pages Write", "Account Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages.account-custom-pages", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}": { "delete": { "operationId": "account-deletion", "summary": "Delete a specific account", "description": "Delete a specific account (only available for tenant admins at this time). This is a permanent operation that will delete any zones or other resources under the account", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "description": "The account ID of the account to be deleted", "type": "string" } } ], "responses": { "200": { "description": "Account Deletion Success Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-single-id" } } } }, "4XX": { "description": "Account Deletion Failure Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Accounts" ], "x-api-token-group": [ "Account Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "#organization:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": false, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "Are you sure? This action cannot be undone." }, "get": { "operationId": "accounts-account-details", "summary": "Account Details", "description": "Get information about a specific account that you are a member of.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_account_identifier" } } ], "responses": { "200": { "description": "Account Details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_response_single_account" } } } }, "4XX": { "description": "Account Details response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Accounts" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read", "DNS View Write", "DNS View Read", "SCIM Provisioning", "Load Balancers Account Write", "Load Balancers Account Read", "Zero Trust: PII Read", "DDoS Botnet Feed Write", "DDoS Botnet Feed Read", "Workers R2 Storage Write", "Workers R2 Storage Read", "DDoS Protection Write", "DDoS Protection Read", "Workers Tail Read", "Workers KV Storage Write", "Workers KV Storage Read", "Workers Scripts Write", "Workers Scripts Read", "Load Balancing: Monitors and Pools Write", "Load Balancing: Monitors and Pools Read", "Account Firewall Access Rules Write", "Account Firewall Access Rules Read", "DNS Firewall Write", "DNS Firewall Read", "Billing Write", "Billing Read", "Account Settings Write", "Account Settings Read" ], "x-cfPermissionsRequired": { "enum": [ "#organization:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "accounts-update-account", "summary": "Update Account", "description": "Update an existing account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_account_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_components-schemas-account" } } } }, "responses": { "200": { "description": "Update Account response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_response_single_account" } } } }, "4XX": { "description": "Update Account response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Accounts" ], "x-api-token-group": [ "Account Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "#organization:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/abuse-reports": { "get": { "operationId": "ListAbuseReports", "summary": "List abuse reports", "description": "List the abuse reports for a given account", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 } }, { "name": "page", "in": "query", "description": "Where in pagination to start listing abuse reports", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "How many abuse reports per page to list", "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "A property to sort by, followed by the order (id, cdate, domain, type, status)", "schema": { "type": "string" }, "example": "cdate,desc" }, { "name": "domain", "in": "query", "description": "Filter by domain name related to the abuse report", "schema": { "type": "string" }, "example": "example.com" }, { "name": "created_before", "in": "query", "description": "Returns reports created before the specified date", "schema": { "description": "Time in RFC 3339 format (https://www.rfc-editor.org/rfc/rfc3339.html)", "type": "string", "example": "2009-11-10T23:00:00Z" }, "example": "2009-11-10T23:00:00Z" }, { "name": "created_after", "in": "query", "description": "Returns reports created after the specified date", "schema": { "description": "Time in RFC 3339 format (https://www.rfc-editor.org/rfc/rfc3339.html)", "type": "string", "example": "2009-11-10T23:00:00Z" }, "example": "2009-11-10T23:00:00Z" }, { "name": "status", "in": "query", "description": "Filter by the status of the report.", "schema": { "$ref": "#/components/schemas/abuse-reports_ReportStatus" }, "example": "denied" }, { "name": "type", "in": "query", "description": "Filter by the type of the report.", "schema": { "$ref": "#/components/schemas/abuse-reports_ReportType" }, "example": "denied" }, { "name": "mitigation_status", "in": "query", "description": "Filter reports that have any mitigations in the given status.", "schema": { "$ref": "#/components/schemas/abuse-reports_MitigationStatus" }, "example": "active" } ], "responses": { "200": { "description": "Abuse report list successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "result": { "type": "object", "properties": { "reports": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_AbuseReport" } } }, "required": [ "reports" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "page", "per_page", "count", "total_count", "total_pages" ] }, "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "401": { "description": "The request is not authorized. Missing or invalid credentials may be\nrejected with the standard Cloudflare API authentication error. If\ncredentials are valid, the API token does not have the Abuse Reports\nread permission required for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "500": { "description": "Failed to retrieve abuse reports", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "success": { "type": "boolean" } }, "required": [ "success" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "tseng-abuse-complaint-processor_other" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "abuse-reports", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/abuse-reports/submitted": { "get": { "operationId": "ListSubmittedAbuseReports", "summary": "List submitted abuse reports", "description": "List abuse reports submitted by the account.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 } }, { "name": "page", "in": "query", "description": "Page of submitted reports to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Number of submitted reports per page.", "schema": { "type": "integer", "default": 100, "maximum": 200, "minimum": 1 } }, { "name": "sort", "in": "query", "description": "A property and direction to sort by (id, cdate, domain, type, status).", "schema": { "type": "string" }, "example": "cdate,desc" }, { "name": "id", "in": "query", "description": "Filter by report code.", "schema": { "type": "string" } }, { "name": "domain", "in": "query", "description": "Filter by reported domain. This parameter can be specified multiple times.", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true, "style": "form" }, { "name": "created_before", "in": "query", "description": "Return reports submitted before this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_after", "in": "query", "description": "Return reports submitted after this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "status", "in": "query", "description": "Filter by submitter-facing status. This parameter can be specified multiple times.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_SubmittedAbuseReportStatus" } }, "explode": true, "style": "form" }, { "name": "type", "in": "query", "description": "Filter by report type. This parameter can be specified multiple times.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_ReportType" } }, "explode": true, "style": "form" } ], "responses": { "200": { "description": "Submitted abuse reports listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_SubmittedAbuseReportListResponse" } } } }, "400": { "description": "Invalid account or query parameters." }, "401": { "description": "The request is not authorized to read abuse reports for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "500": { "description": "Failed to retrieve submitted abuse reports." } }, "security": [ { "api_token": [] } ], "tags": [ "tseng-abuse-complaint-processor_other" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "abuse-reports", "x-fern-sdk-method-name": "list-submitted", "x-forge-hidden": true } }, "/accounts/{account_id}/abuse-reports/submitted/{report_id}": { "get": { "operationId": "GetSubmittedAbuseReport", "summary": "Get a submitted abuse report", "description": "Retrieve a report submitted by the account.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 } }, { "name": "report_id", "in": "path", "description": "Public report code.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Submitted abuse report found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_SubmittedAbuseReportDetailResponse" } } } }, "400": { "description": "Invalid account or report code." }, "401": { "description": "The request is not authorized to read abuse reports for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "404": { "description": "No matching submitted report was found for the account." }, "500": { "description": "Failed to retrieve the submitted abuse report." } }, "security": [ { "api_token": [] } ], "tags": [ "tseng-abuse-complaint-processor_other" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "abuse-reports", "x-fern-sdk-method-name": "get-submitted", "x-forge-hidden": true } }, "/accounts/{account_id}/abuse-reports/submitted/{report_id}/emails": { "get": { "operationId": "ListSubmittedAbuseReportEmails", "summary": "List emails sent to an abuse report submitter", "description": "List successful emails sent to the submitter of a report submitted by the account. Does not include emails sent to customers or hosts.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 } }, { "name": "report_id", "in": "path", "description": "Public report code.", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number to retrieve (default 1).", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of emails per page (default 20, max 100).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Submitted abuse report emails listed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_EmailListResponse" } } } }, "400": { "description": "Invalid account, report, or query parameters." }, "401": { "description": "The request is not authorized to read abuse reports for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "404": { "description": "Submitted abuse report not found for the selected account." }, "500": { "description": "Failed to retrieve submitted abuse report emails." } }, "security": [ { "api_token": [] } ], "tags": [ "tseng-abuse-complaint-processor_other" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "abuse-reports.emails", "x-fern-sdk-method-name": "list-submitted", "x-forge-hidden": true } }, "/accounts/{account_id}/abuse-reports/{report_id}/appeals/eligibility": { "get": { "operationId": "CheckAppealEligibility", "summary": "Check whether a report can be appealed", "description": "Returns whether the report is currently appealable, along with the signals behind that decision: whether it already has an open appeal, how many appeals have been submitted against it, and whether it has at least one mitigation that an appeal could reverse.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 } }, { "name": "report_id", "in": "path", "description": "Abuse Report ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Appeal eligibility for the report", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "result": { "$ref": "#/components/schemas/abuse-reports_AppealEligibility" }, "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "401": { "description": "The request is not authorized. Missing or invalid credentials may be\nrejected with the standard Cloudflare API authentication error. If\ncredentials are valid, the API token does not have the Abuse Reports\nread permission required for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "404": { "description": "The report was not found, or does not support appeals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "500": { "description": "Failed to check appeal eligibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "success": { "type": "boolean" } }, "required": [ "success" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "tseng-abuse-complaint-processor_other" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "abuse-reports.appeals", "x-fern-sdk-method-name": "eligibility", "x-forge-hidden": true } }, "/accounts/{account_id}/abuse-reports/{report_id}/emails": { "get": { "operationId": "ListEmails", "summary": "List abuse report emails", "description": "List emails sent to the customer for an abuse report. Returns all successful customer emails sent for the specified abuse report. Does not include emails sent to hosts or submitters.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 } }, { "name": "report_id", "in": "path", "description": "Abuse Report ID", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number to retrieve (default 1)", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of emails per page (default 20, max 100)", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List abuse report emails successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "result": { "type": "object", "properties": { "emails": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_EmailListItem" } } }, "required": [ "emails" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "page", "per_page", "count", "total_count", "total_pages" ] }, "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "400": { "description": "Bad request - invalid parameters or report not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "401": { "description": "The request is not authorized. Missing or invalid credentials may be\nrejected with the standard Cloudflare API authentication error. If\ncredentials are valid, the API token does not have the Abuse Reports\nread permission required for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "500": { "description": "Failed to list abuse report emails", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "success": { "type": "boolean" } }, "required": [ "success" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "tseng-abuse-complaint-processor_other" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "abuse-reports.emails", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/abuse-reports/{report_id}/mitigations": { "get": { "operationId": "ListMitigations", "summary": "List abuse report mitigations", "description": "List mitigations done to remediate the abuse report.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 } }, { "name": "report_id", "in": "path", "description": "Abuse Report ID", "required": true, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Where in pagination to start listing abuse reports", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "How many abuse reports per page to list", "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "A property to sort by, followed by the order", "schema": { "type": "string", "enum": [ "type,asc", "type,desc", "effective_date,asc", "effective_date,desc", "status,asc", "status,desc", "entity_type,asc", "entity_type,desc" ] }, "example": "type,desc" }, { "name": "type", "in": "query", "description": "Filter by the type of mitigation. This filter parameter can be specified multiple times to include multiple types of mitigations in the result set.", "schema": { "$ref": "#/components/schemas/abuse-reports_MitigationType" } }, { "name": "effective_before", "in": "query", "description": "Returns mitigations that were dispatched before the given date", "schema": { "description": "Time in RFC 3339 format (https://www.rfc-editor.org/rfc/rfc3339.html)", "type": "string", "example": "2009-11-10T23:00:00Z" }, "example": "2009-11-10T23:00:00Z" }, { "name": "effective_after", "in": "query", "description": "Returns mitigation that were dispatched after the given date", "schema": { "description": "Time in RFC 3339 format (https://www.rfc-editor.org/rfc/rfc3339.html)", "type": "string", "example": "2009-11-10T23:00:00Z" }, "example": "2009-11-10T23:00:00Z" }, { "name": "status", "in": "query", "description": "Filter by the status of the mitigation.", "schema": { "$ref": "#/components/schemas/abuse-reports_MitigationStatus" } }, { "name": "entity_type", "in": "query", "description": "Filter by the type of entity the mitigation impacts.", "schema": { "$ref": "#/components/schemas/abuse-reports_MitigatedEntityType" } } ], "responses": { "200": { "description": "List abuse report mitigations successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "result": { "type": "object", "properties": { "mitigations": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_MitigationListItem" } } }, "required": [ "mitigations" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "page", "per_page", "count", "total_count", "total_pages" ] }, "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "401": { "description": "The request is not authorized. Missing or invalid credentials may be\nrejected with the standard Cloudflare API authentication error. If\ncredentials are valid, the API token does not have the Abuse Reports\nread permission required for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "500": { "description": "Failed to list abuse report mitigations", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "success": { "type": "boolean" } }, "required": [ "success" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "tseng-abuse-complaint-processor_other" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "abuse-reports.mitigations", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/abuse-reports/{report_id}/mitigations/appeal": { "post": { "operationId": "RequestReview", "summary": "Request review on mitigations", "description": "Request a review for mitigations on an account. Repeating a request for a mitigation with an unresolved appeal is idempotent and returns that mitigation in the in-review state.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 } }, { "name": "report_id", "in": "path", "description": "Abuse Report ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_MitigationAppealRequest" } } } }, "responses": { "200": { "description": "Mitigation appeals received, including idempotent replays of unresolved appeals.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_MitigationAppealResult" } } } }, "207": { "description": "Some mitigation appeals were accepted while others were invalid or cannot be appealed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_MitigationAppealResult" } } } }, "401": { "description": "The request is not authorized. Missing or invalid credentials may be\nrejected with the standard Cloudflare API authentication error. If\ncredentials are valid, the API token does not have the Abuse Reports\nedit permission required for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "500": { "description": "Failed to request review on delayed action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "success": { "type": "boolean" } }, "required": [ "success" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "tseng-abuse-complaint-processor_other" ], "x-api-token-group": [ "Trust and Safety Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "abuse-reports.mitigations", "x-fern-sdk-method-name": "review", "x-forge-hidden": true } }, "/accounts/{account_id}/abuse-reports/{report_param}": { "get": { "operationId": "GetAbuseReport", "summary": "Abuse Report Details", "description": "Retrieve the details of an abuse report.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 } }, { "name": "report_param", "in": "path", "description": "Identifier of the abuse report", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Report submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_ErrorMessage" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "result": { "$ref": "#/components/schemas/abuse-reports_AbuseReport" }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Report submitted with an error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_ErrorMessage" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "result": { "$ref": "#/components/schemas/abuse-reports_AbuseReport" }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } }, "401": { "description": "The request is not authorized. Missing or invalid credentials may be\nrejected with the standard Cloudflare API authentication error. If\ncredentials are valid, the API token does not have the Abuse Reports\nread permission required for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "500": { "description": "Report submitted with an error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_ErrorMessage" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "result": { "$ref": "#/components/schemas/abuse-reports_AbuseReport" }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "tseng-abuse-complaint-processor_other" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "abuse-reports", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "SubmitAbuseReport", "summary": "Submit an abuse report", "description": "Submit an abuse report of a particular type.\n\nRequires the abuse-reports entitlement on the account (Enterprise\naccounts have it by default; other accounts must request access) and an\nAPI token with the `Account > Abuse Reports > Edit` permission. If the\naccount is not entitled, the request is rejected with an HTTP `401`\nresponse (see below).", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 } }, { "name": "report_param", "in": "path", "description": "The report type to be submitted. Example: abuse_general", "required": true, "schema": { "$ref": "#/components/schemas/abuse-reports_SubmissionReportType" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_SubmitReportRequest" } } } }, "responses": { "200": { "description": "Report submitted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_SubmitReportResponse" } } } }, "400": { "description": "Report submitted with an error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_SubmitErrorResponse" } } } }, "401": { "description": "The request is not authorized to submit abuse reports. Missing or\ninvalid credentials may be rejected with the standard Cloudflare API\nauthentication error. If credentials are valid, this is most commonly\nbecause the account does not have the abuse-reports entitlement\n(Enterprise accounts have it by default; other accounts must request\naccess), or because the API token is missing the\n`Account > Abuse Reports > Edit` permission. Entitlement failures\nreturn the message `Not entitled to use feature: Abuse Report API`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_UnauthorizedErrorResponse" } } } }, "500": { "description": "Report submitted with an error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/abuse-reports_SubmitErrorResponse" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "tseng-abuse-complaint-processor_other" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "abuse-reports", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/access/ai-controls/mcp/analytics/portals/{portal_id}/tool-calls/timeseries": { "get": { "operationId": "mcp-portals-api-portal-tool-call-timeseries", "summary": "Per-portal MCP tool-call timeseries", "description": "Returns daily or monthly tool-call counts for a portal.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "a86a8f5c339544d7bdc89926de14fb8c" } }, { "name": "portal_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "granularity", "in": "query", "schema": { "type": "string", "default": "daily", "enum": [ "daily", "monthly" ] } }, { "name": "aggregate", "in": "query", "schema": { "type": "string", "default": "false", "enum": [ "true", "false" ] } }, { "name": "tz", "in": "query", "schema": { "type": "string", "default": "utc", "pattern": "^(utc|Z|\\+(?:(?:0\\d|1[0-3]):[0-5]\\d|14:00)|-(?:(?:0\\d|1[01]):[0-5]\\d|12:00))$" } }, { "name": "days", "in": "query", "description": "Daily trailing-window size; defaults to 7 and is ignored for monthly", "schema": { "description": "Daily trailing-window size; defaults to 7 and is ignored for monthly", "type": "integer", "maximum": 179, "minimum": 1 } } ], "responses": { "200": { "description": "Per-day tool/call counts across all servers in a portal over the selected window", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "aggregate": { "type": "boolean" }, "end": { "type": "integer" }, "granularity": { "type": "string", "enum": [ "daily", "monthly" ] }, "series": { "type": "array", "items": { "properties": { "count": { "type": "integer" }, "day": { "type": "string" } }, "required": [ "day", "count" ], "type": "object" } }, "start": { "type": "integer" }, "total": { "type": "integer" }, "tz": { "type": "string", "pattern": "^(utc|Z|\\+(?:(?:0\\d|1[0-3]):[0-5]\\d|14:00)|-(?:(?:0\\d|1[01]):[0-5]\\d|12:00))$" } }, "required": [ "granularity", "aggregate", "tz", "start", "end", "series", "total" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "MCP Portal Analytics" ], "x-api-token-group": [ "MCP Portals Write", "MCP Portals Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.mcp_portals" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "mcp.portals", "x-fern-sdk-method-name": "portal-tool-call-timeseries", "x-forge-hidden": true } }, "/accounts/{account_id}/access/ai-controls/mcp/analytics/servers/{server_id}/tool-calls/timeseries": { "get": { "operationId": "mcp-portals-api-server-tool-call-timeseries", "summary": "Per-server MCP tool-call timeseries", "description": "Returns daily or monthly tool-call counts for a server.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "a86a8f5c339544d7bdc89926de14fb8c" } }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "granularity", "in": "query", "schema": { "type": "string", "default": "daily", "enum": [ "daily", "monthly" ] } }, { "name": "aggregate", "in": "query", "schema": { "type": "string", "default": "false", "enum": [ "true", "false" ] } }, { "name": "tz", "in": "query", "schema": { "type": "string", "default": "utc", "pattern": "^(utc|Z|\\+(?:(?:0\\d|1[0-3]):[0-5]\\d|14:00)|-(?:(?:0\\d|1[01]):[0-5]\\d|12:00))$" } }, { "name": "days", "in": "query", "description": "Daily trailing-window size; defaults to 7 and is ignored for monthly", "schema": { "description": "Daily trailing-window size; defaults to 7 and is ignored for monthly", "type": "integer", "maximum": 179, "minimum": 1 } } ], "responses": { "200": { "description": "Per-day tool/call counts for a single server over the selected window", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "aggregate": { "type": "boolean" }, "end": { "type": "integer" }, "granularity": { "type": "string", "enum": [ "daily", "monthly" ] }, "series": { "type": "array", "items": { "properties": { "count": { "type": "integer" }, "day": { "type": "string" } }, "required": [ "day", "count" ], "type": "object" } }, "start": { "type": "integer" }, "total": { "type": "integer" }, "tz": { "type": "string", "pattern": "^(utc|Z|\\+(?:(?:0\\d|1[0-3]):[0-5]\\d|14:00)|-(?:(?:0\\d|1[01]):[0-5]\\d|12:00))$" } }, "required": [ "granularity", "aggregate", "tz", "start", "end", "series", "total" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "MCP Portal Analytics" ], "x-api-token-group": [ "MCP Portals Write", "MCP Portals Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.mcp_portals" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "mcp.servers", "x-fern-sdk-method-name": "server-tool-call-timeseries", "x-forge-hidden": true } }, "/accounts/{account_id}/access/ai-controls/mcp/analytics/tool-calls/timeseries": { "get": { "operationId": "mcp-portals-api-account-tool-call-timeseries", "summary": "Account-global MCP tool-call timeseries", "description": "Returns daily or monthly tool-call counts across the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "a86a8f5c339544d7bdc89926de14fb8c" } }, { "name": "granularity", "in": "query", "schema": { "type": "string", "default": "daily", "enum": [ "daily", "monthly" ] } }, { "name": "aggregate", "in": "query", "schema": { "type": "string", "default": "false", "enum": [ "true", "false" ] } }, { "name": "tz", "in": "query", "schema": { "type": "string", "default": "utc", "pattern": "^(utc|Z|\\+(?:(?:0\\d|1[0-3]):[0-5]\\d|14:00)|-(?:(?:0\\d|1[01]):[0-5]\\d|12:00))$" } }, { "name": "days", "in": "query", "description": "Daily trailing-window size; defaults to 7 and is ignored for monthly", "schema": { "description": "Daily trailing-window size; defaults to 7 and is ignored for monthly", "type": "integer", "maximum": 179, "minimum": 1 } } ], "responses": { "200": { "description": "Per-day tool/call counts across the whole account over the selected window", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "aggregate": { "type": "boolean" }, "end": { "type": "integer" }, "granularity": { "type": "string", "enum": [ "daily", "monthly" ] }, "series": { "type": "array", "items": { "properties": { "count": { "type": "integer" }, "day": { "type": "string" } }, "required": [ "day", "count" ], "type": "object" } }, "start": { "type": "integer" }, "total": { "type": "integer" }, "tz": { "type": "string", "pattern": "^(utc|Z|\\+(?:(?:0\\d|1[0-3]):[0-5]\\d|14:00)|-(?:(?:0\\d|1[01]):[0-5]\\d|12:00))$" } }, "required": [ "granularity", "aggregate", "tz", "start", "end", "series", "total" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "MCP Portal Analytics" ], "x-api-token-group": [ "MCP Portals Write", "MCP Portals Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.mcp_portals" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "mcp.portals", "x-fern-sdk-method-name": "account-tool-call-timeseries", "x-forge-hidden": true } }, "/accounts/{account_id}/access/ai-controls/mcp/portals": { "get": { "operationId": "mcp-portals-api-list-portals", "summary": "List MCP Portals", "description": "Lists all MCP portals configured for the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "a86a8f5c339544d7bdc89926de14fb8c" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "schema": { "description": "Search by id, name, hostname", "type": "string" } } ], "responses": { "200": { "description": "List objects", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "allow_code_mode": { "description": "Deprecated: use `code_mode` for new integrations. `true` maps to any non-off Code Mode policy; `false` maps to `code_mode: off`. If both fields are sent, they must be consistent or the request returns a 400.", "type": "boolean", "example": true, "deprecated": true }, "code_mode": { "description": "Code Mode policy for this portal. `off`: Code Mode is unavailable; query parameters are ignored. `opt_in`: Code Mode is off by default; clients turn it on with `?codemode=search_and_execute`. `default_on`: Code Mode is on by default; clients can opt out with `?codemode=off`. `enforced`: Code Mode is always on; query parameters are ignored. Defaults to `opt_in` when omitted on create. If both `code_mode` and `allow_code_mode` are sent, they must be consistent or the request returns a 400.", "type": "string", "example": "opt_in", "enum": [ "off", "opt_in", "default_on", "enforced" ] }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "readOnly": true }, "description": { "description": "Optional description of the MCP portal.", "type": "string", "example": "This is my custom MCP Portal", "maxLength": 512 }, "hostname": { "description": "Hostname where the MCP portal is available.", "type": "string", "example": "example.com", "pattern": "^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$" }, "id": { "description": "Unique identifier for the MCP portal.", "type": "string", "example": "my-mcp-portal", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "readOnly": true }, "name": { "description": "Display name for the MCP portal.", "type": "string", "example": "My MCP Portal", "maxLength": 350 }, "secure_web_gateway": { "description": "Route outbound MCP traffic through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "servers": { "type": "array", "items": { "properties": { "auth_config_summary": { "description": "Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value.", "type": "object", "properties": { "auth_mode": { "type": "string", "enum": [ "dcr", "manual" ] }, "client_secret_version": { "type": "number" }, "config": { "type": "object", "properties": { "authorization_endpoint": { "type": "string" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "revocation_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" } } }, "has_client_secret": { "type": "boolean" }, "registration_info": { "type": "object", "properties": { "client_id": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string" }, "token_endpoint_auth_method": { "type": "string" } } } }, "readOnly": true }, "auth_type": { "description": "Authentication method used to connect to the upstream MCP server.", "type": "string", "example": "unauthenticated", "enum": [ "oauth", "bearer", "unauthenticated" ] }, "authentication_status": { "description": "Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow.", "type": "string", "enum": [ "not_required", "required", "connected", "stale", "manual" ], "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "readOnly": true }, "default_disabled": { "type": "boolean" }, "description": { "description": "Optional description of the MCP server.", "type": "string", "example": "This is one remote MCP server", "maxLength": 512, "nullable": true }, "error": { "type": "string", "readOnly": true }, "error_details": { "type": "object", "properties": { "cause": { "description": "Underlying error message", "type": "string" }, "is_upstream": { "description": "True = MCP server returned an error. False = couldn't reach the server", "type": "boolean" }, "mcp_code": { "description": "MCP protocol error code", "type": "number" }, "retryable": { "description": "Whether the error is transient and worth retrying", "type": "boolean" }, "status_code": { "description": "HTTP status code from the server", "type": "number" } }, "readOnly": true }, "hostname": { "description": "URL of the upstream MCP endpoint.", "type": "string", "format": "uri", "example": "https://example.com/mcp" }, "id": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "is_shared_oauth_callback_enabled": { "description": "When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true.", "type": "boolean", "default": false }, "last_successful_sync": { "type": "string", "format": "date-time", "readOnly": true }, "last_synced": { "type": "string", "format": "date-time", "readOnly": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "readOnly": true }, "name": { "description": "Display name for the MCP server.", "type": "string", "example": "My MCP Server", "maxLength": 350 }, "on_behalf": { "type": "boolean" }, "prompts": { "type": "array", "items": { "additionalProperties": true, "description": "Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "secure_web_gateway": { "description": "Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "server_id": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "status": { "description": "Current sync state of the server", "type": "string", "example": "ready", "default": "waiting", "enum": [ "waiting", "ready", "stale", "error" ], "readOnly": true }, "tools": { "type": "array", "items": { "additionalProperties": true, "description": "Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "updated_prompts": { "type": "array", "items": { "properties": { "enabled": { "type": "boolean" }, "name": { "type": "string" }, "portal_alias": { "type": "string", "example": "portal-tool-alias" }, "portal_description": { "type": "string", "example": "portal-level description" }, "server_alias": { "type": "string", "example": "server-tool-alias" }, "server_description": { "type": "string", "example": "server-level description" } }, "required": [ "name" ], "type": "object" } }, "updated_tools": { "type": "array", "items": { "properties": { "enabled": { "type": "boolean" }, "name": { "type": "string" }, "portal_alias": { "type": "string", "example": "portal-tool-alias" }, "portal_description": { "type": "string", "example": "portal-level description" }, "server_alias": { "type": "string", "example": "server-tool-alias" }, "server_description": { "type": "string", "example": "server-level description" } }, "required": [ "name" ], "type": "object" } } }, "required": [ "id", "name", "hostname", "auth_type", "tools", "prompts", "server_id" ], "type": "object" }, "x-stainless-collection-type": "set" } }, "required": [ "id", "name", "hostname", "servers" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "MCP Portal" ], "x-api-token-group": [ "MCP Portals Write", "MCP Portals Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.mcp_portals" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "mcp.portals", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "mcp-portals-api-create-portals", "summary": "Create a new MCP Portal", "description": "Creates a new MCP portal for managing AI tool access through Cloudflare Access.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "a86a8f5c339544d7bdc89926de14fb8c" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "allow_code_mode": { "description": "Deprecated: use `code_mode` for new integrations. `true` maps to any non-off Code Mode policy; `false` maps to `code_mode: off`. If both fields are sent, they must be consistent or the request returns a 400.", "type": "boolean", "example": true, "deprecated": true }, "code_mode": { "description": "Code Mode policy for this portal. `off`: Code Mode is unavailable; query parameters are ignored. `opt_in`: Code Mode is off by default; clients turn it on with `?codemode=search_and_execute`. `default_on`: Code Mode is on by default; clients can opt out with `?codemode=off`. `enforced`: Code Mode is always on; query parameters are ignored. Defaults to `opt_in` when omitted on create. If both `code_mode` and `allow_code_mode` are sent, they must be consistent or the request returns a 400.", "type": "string", "example": "opt_in", "enum": [ "off", "opt_in", "default_on", "enforced" ] }, "description": { "description": "Optional description of the MCP portal.", "type": "string", "example": "This is my custom MCP Portal", "maxLength": 512 }, "hostname": { "description": "Hostname where the MCP portal is available.", "type": "string", "example": "example.com", "pattern": "^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$" }, "id": { "description": "Unique identifier for the MCP portal.", "type": "string", "example": "my-mcp-portal", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "name": { "description": "Display name for the MCP portal.", "type": "string", "example": "My MCP Portal", "maxLength": 350 }, "secure_web_gateway": { "description": "Route outbound MCP traffic through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "servers": { "description": "MCP servers attached to the portal and their portal-specific settings.", "type": "array", "items": { "properties": { "default_disabled": { "description": "Disable this server by default for clients connecting through the portal.", "type": "boolean" }, "on_behalf": { "description": "Use end-user OAuth credentials when connecting this server to the portal.", "type": "boolean" }, "server_id": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "updated_prompts": { "description": "Portal-specific prompt overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } }, "updated_tools": { "description": "Portal-specific tool overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": [ "server_id" ], "type": "object" }, "maxItems": 80, "x-stainless-collection-type": "set" } }, "required": [ "id", "name", "hostname" ] } } } }, "responses": { "201": { "description": "Returns the created Object", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "allow_code_mode": { "description": "Deprecated: use `code_mode` for new integrations. `true` maps to any non-off Code Mode policy; `false` maps to `code_mode: off`. If both fields are sent, they must be consistent or the request returns a 400.", "type": "boolean", "example": true, "deprecated": true }, "code_mode": { "description": "Code Mode policy for this portal. `off`: Code Mode is unavailable; query parameters are ignored. `opt_in`: Code Mode is off by default; clients turn it on with `?codemode=search_and_execute`. `default_on`: Code Mode is on by default; clients can opt out with `?codemode=off`. `enforced`: Code Mode is always on; query parameters are ignored. Defaults to `opt_in` when omitted on create. If both `code_mode` and `allow_code_mode` are sent, they must be consistent or the request returns a 400.", "type": "string", "example": "opt_in", "enum": [ "off", "opt_in", "default_on", "enforced" ] }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "readOnly": true }, "description": { "description": "Optional description of the MCP portal.", "type": "string", "example": "This is my custom MCP Portal", "maxLength": 512 }, "hostname": { "description": "Hostname where the MCP portal is available.", "type": "string", "example": "example.com", "pattern": "^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$" }, "id": { "description": "Unique identifier for the MCP portal.", "type": "string", "example": "my-mcp-portal", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "readOnly": true }, "name": { "description": "Display name for the MCP portal.", "type": "string", "example": "My MCP Portal", "maxLength": 350 }, "secure_web_gateway": { "description": "Route outbound MCP traffic through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "servers": { "type": "array", "items": { "properties": { "auth_config_summary": { "description": "Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value.", "type": "object", "properties": { "auth_mode": { "type": "string", "enum": [ "dcr", "manual" ] }, "client_secret_version": { "type": "number" }, "config": { "type": "object", "properties": { "authorization_endpoint": { "type": "string" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "revocation_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" } } }, "has_client_secret": { "type": "boolean" }, "registration_info": { "type": "object", "properties": { "client_id": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string" }, "token_endpoint_auth_method": { "type": "string" } } } }, "readOnly": true }, "auth_type": { "description": "Authentication method used to connect to the upstream MCP server.", "type": "string", "example": "unauthenticated", "enum": [ "oauth", "bearer", "unauthenticated" ] }, "authentication_status": { "description": "Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow.", "type": "string", "enum": [ "not_required", "required", "connected", "stale", "manual" ], "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "readOnly": true }, "default_disabled": { "type": "boolean" }, "description": { "description": "Optional description of the MCP server.", "type": "string", "example": "This is one remote MCP server", "maxLength": 512, "nullable": true }, "error": { "type": "string", "readOnly": true }, "error_details": { "type": "object", "properties": { "cause": { "description": "Underlying error message", "type": "string" }, "is_upstream": { "description": "True = MCP server returned an error. False = couldn't reach the server", "type": "boolean" }, "mcp_code": { "description": "MCP protocol error code", "type": "number" }, "retryable": { "description": "Whether the error is transient and worth retrying", "type": "boolean" }, "status_code": { "description": "HTTP status code from the server", "type": "number" } }, "readOnly": true }, "hostname": { "description": "URL of the upstream MCP endpoint.", "type": "string", "format": "uri", "example": "https://example.com/mcp" }, "id": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "is_shared_oauth_callback_enabled": { "description": "When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true.", "type": "boolean", "default": false }, "last_successful_sync": { "type": "string", "format": "date-time", "readOnly": true }, "last_synced": { "type": "string", "format": "date-time", "readOnly": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "readOnly": true }, "name": { "description": "Display name for the MCP server.", "type": "string", "example": "My MCP Server", "maxLength": 350 }, "on_behalf": { "type": "boolean" }, "prompts": { "type": "array", "items": { "additionalProperties": true, "description": "Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "secure_web_gateway": { "description": "Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "server_id": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "status": { "description": "Current sync state of the server", "type": "string", "example": "ready", "default": "waiting", "enum": [ "waiting", "ready", "stale", "error" ], "readOnly": true }, "tools": { "type": "array", "items": { "additionalProperties": true, "description": "Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "updated_prompts": { "type": "array", "items": { "properties": { "enabled": { "type": "boolean" }, "name": { "type": "string" }, "portal_alias": { "type": "string", "example": "portal-tool-alias" }, "portal_description": { "type": "string", "example": "portal-level description" }, "server_alias": { "type": "string", "example": "server-tool-alias" }, "server_description": { "type": "string", "example": "server-level description" } }, "required": [ "name" ], "type": "object" } }, "updated_tools": { "type": "array", "items": { "properties": { "enabled": { "type": "boolean" }, "name": { "type": "string" }, "portal_alias": { "type": "string", "example": "portal-tool-alias" }, "portal_description": { "type": "string", "example": "portal-level description" }, "server_alias": { "type": "string", "example": "server-tool-alias" }, "server_description": { "type": "string", "example": "server-level description" } }, "required": [ "name" ], "type": "object" } } }, "required": [ "id", "name", "hostname", "auth_type", "tools", "prompts", "server_id" ], "type": "object" }, "x-stainless-collection-type": "set" } }, "required": [ "id", "name", "hostname", "servers" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7001 }, "message": { "type": "string", "example": "Input Validation Error" }, "path": { "type": "array", "items": { "example": "body", "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "MCP Portal" ], "x-api-token-group": [ "MCP Portals Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.mcp_portals" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "mcp.portals", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/access/ai-controls/mcp/portals/{id}": { "delete": { "operationId": "mcp-portals-api-delete-portals", "summary": "Delete an MCP Portal", "description": "Deletes an MCP portal from the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "a86a8f5c339544d7bdc89926de14fb8c" } }, { "name": "id", "in": "path", "required": true, "schema": { "description": "Unique identifier for the MCP portal.", "type": "string", "example": "my-mcp-portal", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } } ], "responses": { "200": { "description": "Returns the Object if it was successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "allow_code_mode": { "description": "Deprecated: use `code_mode` for new integrations. `true` maps to any non-off Code Mode policy; `false` maps to `code_mode: off`. If both fields are sent, they must be consistent or the request returns a 400.", "type": "boolean", "example": true, "deprecated": true }, "code_mode": { "description": "Code Mode policy for this portal. `off`: Code Mode is unavailable; query parameters are ignored. `opt_in`: Code Mode is off by default; clients turn it on with `?codemode=search_and_execute`. `default_on`: Code Mode is on by default; clients can opt out with `?codemode=off`. `enforced`: Code Mode is always on; query parameters are ignored. Defaults to `opt_in` when omitted on create. If both `code_mode` and `allow_code_mode` are sent, they must be consistent or the request returns a 400.", "type": "string", "example": "opt_in", "enum": [ "off", "opt_in", "default_on", "enforced" ] }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "readOnly": true }, "description": { "description": "Optional description of the MCP portal.", "type": "string", "example": "This is my custom MCP Portal", "maxLength": 512 }, "hostname": { "description": "Hostname where the MCP portal is available.", "type": "string", "example": "example.com", "pattern": "^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$" }, "id": { "description": "Unique identifier for the MCP portal.", "type": "string", "example": "my-mcp-portal", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "readOnly": true }, "name": { "description": "Display name for the MCP portal.", "type": "string", "example": "My MCP Portal", "maxLength": 350 }, "secure_web_gateway": { "description": "Route outbound MCP traffic through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false } }, "required": [ "id", "name", "hostname" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "MCP Portal" ], "x-api-token-group": [ "MCP Portals Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.mcp_portals" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "mcp.portals", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation permanently deletes the MCP portal." }, "get": { "operationId": "mcp-portals-api-fetch-gateways", "summary": "Read details of an MCP Portal", "description": "Read the details of a single MCP Portal, including its configured servers.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "description": "Unique identifier for the MCP portal.", "type": "string", "example": "my-mcp-portal", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "a86a8f5c339544d7bdc89926de14fb8c" } } ], "responses": { "200": { "description": "Returns a single object if found", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "allow_code_mode": { "description": "Deprecated: use `code_mode` for new integrations. `true` maps to any non-off Code Mode policy; `false` maps to `code_mode: off`. If both fields are sent, they must be consistent or the request returns a 400.", "type": "boolean", "example": true, "deprecated": true }, "code_mode": { "description": "Code Mode policy for this portal. `off`: Code Mode is unavailable; query parameters are ignored. `opt_in`: Code Mode is off by default; clients turn it on with `?codemode=search_and_execute`. `default_on`: Code Mode is on by default; clients can opt out with `?codemode=off`. `enforced`: Code Mode is always on; query parameters are ignored. Defaults to `opt_in` when omitted on create. If both `code_mode` and `allow_code_mode` are sent, they must be consistent or the request returns a 400.", "type": "string", "example": "opt_in", "enum": [ "off", "opt_in", "default_on", "enforced" ] }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "readOnly": true }, "description": { "description": "Optional description of the MCP portal.", "type": "string", "example": "This is my custom MCP Portal", "maxLength": 512 }, "hostname": { "description": "Hostname where the MCP portal is available.", "type": "string", "example": "example.com", "pattern": "^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$" }, "id": { "description": "Unique identifier for the MCP portal.", "type": "string", "example": "my-mcp-portal", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "readOnly": true }, "name": { "description": "Display name for the MCP portal.", "type": "string", "example": "My MCP Portal", "maxLength": 350 }, "secure_web_gateway": { "description": "Route outbound MCP traffic through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "servers": { "type": "array", "items": { "properties": { "auth_config_summary": { "description": "Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value.", "type": "object", "properties": { "auth_mode": { "type": "string", "enum": [ "dcr", "manual" ] }, "client_secret_version": { "type": "number" }, "config": { "type": "object", "properties": { "authorization_endpoint": { "type": "string" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "revocation_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" } } }, "has_client_secret": { "type": "boolean" }, "registration_info": { "type": "object", "properties": { "client_id": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string" }, "token_endpoint_auth_method": { "type": "string" } } } }, "readOnly": true }, "auth_type": { "description": "Authentication method used to connect to the upstream MCP server.", "type": "string", "example": "unauthenticated", "enum": [ "oauth", "bearer", "unauthenticated" ] }, "authentication_status": { "description": "Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow.", "type": "string", "enum": [ "not_required", "required", "connected", "stale", "manual" ], "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "readOnly": true }, "default_disabled": { "type": "boolean" }, "description": { "description": "Optional description of the MCP server.", "type": "string", "example": "This is one remote MCP server", "maxLength": 512, "nullable": true }, "error": { "type": "string", "readOnly": true }, "error_details": { "type": "object", "properties": { "cause": { "description": "Underlying error message", "type": "string" }, "is_upstream": { "description": "True = MCP server returned an error. False = couldn't reach the server", "type": "boolean" }, "mcp_code": { "description": "MCP protocol error code", "type": "number" }, "retryable": { "description": "Whether the error is transient and worth retrying", "type": "boolean" }, "status_code": { "description": "HTTP status code from the server", "type": "number" } }, "readOnly": true }, "hostname": { "description": "URL of the upstream MCP endpoint.", "type": "string", "format": "uri", "example": "https://example.com/mcp" }, "id": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "is_shared_oauth_callback_enabled": { "description": "When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true.", "type": "boolean", "default": false }, "last_successful_sync": { "type": "string", "format": "date-time", "readOnly": true }, "last_synced": { "type": "string", "format": "date-time", "readOnly": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "readOnly": true }, "name": { "description": "Display name for the MCP server.", "type": "string", "example": "My MCP Server", "maxLength": 350 }, "on_behalf": { "type": "boolean" }, "prompts": { "type": "array", "items": { "additionalProperties": true, "description": "Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "secure_web_gateway": { "description": "Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "server_id": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "status": { "description": "Current sync state of the server", "type": "string", "example": "ready", "default": "waiting", "enum": [ "waiting", "ready", "stale", "error" ], "readOnly": true }, "tools": { "type": "array", "items": { "additionalProperties": true, "description": "Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "updated_prompts": { "type": "array", "items": { "properties": { "enabled": { "type": "boolean" }, "name": { "type": "string" }, "portal_alias": { "type": "string", "example": "portal-tool-alias" }, "portal_description": { "type": "string", "example": "portal-level description" }, "server_alias": { "type": "string", "example": "server-tool-alias" }, "server_description": { "type": "string", "example": "server-level description" } }, "required": [ "name" ], "type": "object" } }, "updated_tools": { "type": "array", "items": { "properties": { "enabled": { "type": "boolean" }, "name": { "type": "string" }, "portal_alias": { "type": "string", "example": "portal-tool-alias" }, "portal_description": { "type": "string", "example": "portal-level description" }, "server_alias": { "type": "string", "example": "server-tool-alias" }, "server_description": { "type": "string", "example": "server-level description" } }, "required": [ "name" ], "type": "object" } } }, "required": [ "id", "name", "hostname", "auth_type", "tools", "prompts", "server_id" ], "type": "object" }, "x-stainless-collection-type": "set" } }, "required": [ "id", "name", "hostname", "servers" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "MCP Portal" ], "x-api-token-group": [ "MCP Portals Write", "MCP Portals Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.mcp_portals" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "mcp.portals", "x-fern-sdk-method-name": "read", "x-forge-hidden": true }, "put": { "operationId": "mcp-portals-api-update-portals", "summary": "Update an MCP Portal", "description": "Updates an MCP portal configuration.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "description": "Unique identifier for the MCP portal.", "type": "string", "example": "my-mcp-portal", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "a86a8f5c339544d7bdc89926de14fb8c" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "allow_code_mode": { "description": "Deprecated: use `code_mode` for new integrations. `true` maps to any non-off Code Mode policy; `false` maps to `code_mode: off`. If both fields are sent, they must be consistent or the request returns a 400.", "type": "boolean", "example": true, "deprecated": true }, "code_mode": { "description": "Code Mode policy for this portal. `off`: Code Mode is unavailable; query parameters are ignored. `opt_in`: Code Mode is off by default; clients turn it on with `?codemode=search_and_execute`. `default_on`: Code Mode is on by default; clients can opt out with `?codemode=off`. `enforced`: Code Mode is always on; query parameters are ignored. Defaults to `opt_in` when omitted on create. If both `code_mode` and `allow_code_mode` are sent, they must be consistent or the request returns a 400.", "type": "string", "example": "opt_in", "enum": [ "off", "opt_in", "default_on", "enforced" ] }, "description": { "description": "Optional description of the MCP portal.", "type": "string", "example": "This is my custom MCP Portal", "maxLength": 512 }, "hostname": { "description": "Hostname where the MCP portal is available.", "type": "string", "example": "example.com", "pattern": "^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$" }, "name": { "description": "Display name for the MCP portal.", "type": "string", "example": "My MCP Portal", "maxLength": 350 }, "secure_web_gateway": { "description": "Route outbound MCP traffic through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "servers": { "description": "MCP servers attached to the portal and their portal-specific settings.", "type": "array", "items": { "properties": { "default_disabled": { "description": "Disable this server by default for clients connecting through the portal.", "type": "boolean" }, "on_behalf": { "description": "Use end-user OAuth credentials when connecting this server to the portal.", "type": "boolean" }, "server_id": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "updated_prompts": { "description": "Portal-specific prompt overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } }, "updated_tools": { "description": "Portal-specific tool overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": [ "server_id" ], "type": "object" }, "maxItems": 80, "x-stainless-collection-type": "set" } } } } } }, "responses": { "200": { "description": "Returns the updated Object", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "allow_code_mode": { "description": "Deprecated: use `code_mode` for new integrations. `true` maps to any non-off Code Mode policy; `false` maps to `code_mode: off`. If both fields are sent, they must be consistent or the request returns a 400.", "type": "boolean", "example": true, "deprecated": true }, "code_mode": { "description": "Code Mode policy for this portal. `off`: Code Mode is unavailable; query parameters are ignored. `opt_in`: Code Mode is off by default; clients turn it on with `?codemode=search_and_execute`. `default_on`: Code Mode is on by default; clients can opt out with `?codemode=off`. `enforced`: Code Mode is always on; query parameters are ignored. Defaults to `opt_in` when omitted on create. If both `code_mode` and `allow_code_mode` are sent, they must be consistent or the request returns a 400.", "type": "string", "example": "opt_in", "enum": [ "off", "opt_in", "default_on", "enforced" ] }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "readOnly": true }, "description": { "description": "Optional description of the MCP portal.", "type": "string", "example": "This is my custom MCP Portal", "maxLength": 512 }, "hostname": { "description": "Hostname where the MCP portal is available.", "type": "string", "example": "example.com", "pattern": "^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$" }, "id": { "description": "Unique identifier for the MCP portal.", "type": "string", "example": "my-mcp-portal", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "readOnly": true }, "name": { "description": "Display name for the MCP portal.", "type": "string", "example": "My MCP Portal", "maxLength": 350 }, "secure_web_gateway": { "description": "Route outbound MCP traffic through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "servers": { "type": "array", "items": { "properties": { "auth_config_summary": { "description": "Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value.", "type": "object", "properties": { "auth_mode": { "type": "string", "enum": [ "dcr", "manual" ] }, "client_secret_version": { "type": "number" }, "config": { "type": "object", "properties": { "authorization_endpoint": { "type": "string" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "revocation_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" } } }, "has_client_secret": { "type": "boolean" }, "registration_info": { "type": "object", "properties": { "client_id": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string" }, "token_endpoint_auth_method": { "type": "string" } } } }, "readOnly": true }, "auth_type": { "description": "Authentication method used to connect to the upstream MCP server.", "type": "string", "example": "unauthenticated", "enum": [ "oauth", "bearer", "unauthenticated" ] }, "authentication_status": { "description": "Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow.", "type": "string", "enum": [ "not_required", "required", "connected", "stale", "manual" ], "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "readOnly": true }, "default_disabled": { "type": "boolean" }, "description": { "description": "Optional description of the MCP server.", "type": "string", "example": "This is one remote MCP server", "maxLength": 512, "nullable": true }, "error": { "type": "string", "readOnly": true }, "error_details": { "type": "object", "properties": { "cause": { "description": "Underlying error message", "type": "string" }, "is_upstream": { "description": "True = MCP server returned an error. False = couldn't reach the server", "type": "boolean" }, "mcp_code": { "description": "MCP protocol error code", "type": "number" }, "retryable": { "description": "Whether the error is transient and worth retrying", "type": "boolean" }, "status_code": { "description": "HTTP status code from the server", "type": "number" } }, "readOnly": true }, "hostname": { "description": "URL of the upstream MCP endpoint.", "type": "string", "format": "uri", "example": "https://example.com/mcp" }, "id": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "is_shared_oauth_callback_enabled": { "description": "When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true.", "type": "boolean", "default": false }, "last_successful_sync": { "type": "string", "format": "date-time", "readOnly": true }, "last_synced": { "type": "string", "format": "date-time", "readOnly": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "readOnly": true }, "name": { "description": "Display name for the MCP server.", "type": "string", "example": "My MCP Server", "maxLength": 350 }, "on_behalf": { "type": "boolean" }, "prompts": { "type": "array", "items": { "additionalProperties": true, "description": "Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "secure_web_gateway": { "description": "Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "server_id": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "status": { "description": "Current sync state of the server", "type": "string", "example": "ready", "default": "waiting", "enum": [ "waiting", "ready", "stale", "error" ], "readOnly": true }, "tools": { "type": "array", "items": { "additionalProperties": true, "description": "Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "updated_prompts": { "type": "array", "items": { "properties": { "enabled": { "type": "boolean" }, "name": { "type": "string" }, "portal_alias": { "type": "string", "example": "portal-tool-alias" }, "portal_description": { "type": "string", "example": "portal-level description" }, "server_alias": { "type": "string", "example": "server-tool-alias" }, "server_description": { "type": "string", "example": "server-level description" } }, "required": [ "name" ], "type": "object" } }, "updated_tools": { "type": "array", "items": { "properties": { "enabled": { "type": "boolean" }, "name": { "type": "string" }, "portal_alias": { "type": "string", "example": "portal-tool-alias" }, "portal_description": { "type": "string", "example": "portal-level description" }, "server_alias": { "type": "string", "example": "server-tool-alias" }, "server_description": { "type": "string", "example": "server-level description" } }, "required": [ "name" ], "type": "object" } } }, "required": [ "id", "name", "hostname", "auth_type", "tools", "prompts", "server_id" ], "type": "object" }, "x-stainless-collection-type": "set" } }, "required": [ "id", "name", "hostname", "servers" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7001 }, "message": { "type": "string", "example": "Input Validation Error" }, "path": { "type": "array", "items": { "example": "body", "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "MCP Portal" ], "x-api-token-group": [ "MCP Portals Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.mcp_portals" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "mcp.portals", "x-fern-sdk-method-name": "update", "x-forge-hidden": true, "x-forge-params": { "allow_code_mode": { "default": null }, "secure_web_gateway": { "default": null } } } }, "/accounts/{account_id}/access/ai-controls/mcp/portals/{portal_id}/servers/{server_id}/effective-redirect-uri": { "get": { "operationId": "mcp-portals-api-effective-redirect-uri", "summary": "Resolve an MCP server OAuth redirect URI", "description": "Resolves the OAuth redirect URI to register for a portal and server based on the server's current shared callback setting. Use the returned value when setting up a new manual OAuth registration. This value is for display only: existing manual OAuth registrations continue using their stored redirect URI, so changing callback settings can make this result differ from the URI used at runtime.", "parameters": [ { "name": "portal_id", "in": "path", "required": true, "schema": { "description": "Unique identifier for the MCP portal.", "type": "string", "example": "my-mcp-portal", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "server_id", "in": "path", "required": true, "schema": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "a86a8f5c339544d7bdc89926de14fb8c" } } ], "responses": { "200": { "description": "Returns the effective redirect URI and its source.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "redirect_uri": { "type": "string", "format": "uri" }, "source": { "type": "string", "enum": [ "per_portal", "shared_mcp22" ] } }, "required": [ "redirect_uri", "source" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "MCP Portal" ], "x-api-token-group": [ "MCP Portals Write", "MCP Portals Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.mcp_portals" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-ignore": true, "x-fern-sdk-group-name": "mcp.portals", "x-fern-sdk-method-name": "resolve-oauth-redirect-uri" } }, "/accounts/{account_id}/access/ai-controls/mcp/servers": { "get": { "operationId": "mcp-portals-api-list-servers", "summary": "List MCP Servers", "description": "Lists all MCP servers configured for the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "a86a8f5c339544d7bdc89926de14fb8c" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "schema": { "description": "Search by id, name", "type": "string" } } ], "responses": { "200": { "description": "List objects", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "auth_config_summary": { "description": "Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value.", "type": "object", "properties": { "auth_mode": { "type": "string", "enum": [ "dcr", "manual" ] }, "client_secret_version": { "type": "number" }, "config": { "type": "object", "properties": { "authorization_endpoint": { "type": "string" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "revocation_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" } } }, "has_client_secret": { "type": "boolean" }, "registration_info": { "type": "object", "properties": { "client_id": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string" }, "token_endpoint_auth_method": { "type": "string" } } } }, "readOnly": true }, "auth_type": { "description": "Authentication method used to connect to the upstream MCP server.", "type": "string", "example": "unauthenticated", "enum": [ "oauth", "bearer", "unauthenticated" ] }, "authentication_status": { "description": "Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow.", "type": "string", "enum": [ "not_required", "required", "connected", "stale", "manual" ], "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "readOnly": true }, "description": { "description": "Optional description of the MCP server.", "type": "string", "example": "This is one remote MCP server", "maxLength": 512, "nullable": true }, "error": { "type": "string", "readOnly": true }, "error_details": { "type": "object", "properties": { "cause": { "description": "Underlying error message", "type": "string" }, "is_upstream": { "description": "True = MCP server returned an error. False = couldn't reach the server", "type": "boolean" }, "mcp_code": { "description": "MCP protocol error code", "type": "number" }, "retryable": { "description": "Whether the error is transient and worth retrying", "type": "boolean" }, "status_code": { "description": "HTTP status code from the server", "type": "number" } }, "readOnly": true }, "hostname": { "description": "URL of the upstream MCP endpoint.", "type": "string", "format": "uri", "example": "https://example.com/mcp" }, "id": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "is_shared_oauth_callback_enabled": { "description": "When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true.", "type": "boolean", "default": false }, "last_successful_sync": { "type": "string", "format": "date-time", "readOnly": true }, "last_synced": { "type": "string", "format": "date-time", "readOnly": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "readOnly": true }, "name": { "description": "Display name for the MCP server.", "type": "string", "example": "My MCP Server", "maxLength": 350 }, "prompts": { "type": "array", "items": { "additionalProperties": true, "description": "Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "secure_web_gateway": { "description": "Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "status": { "description": "Current sync state of the server", "type": "string", "example": "ready", "default": "waiting", "enum": [ "waiting", "ready", "stale", "error" ], "readOnly": true }, "tools": { "type": "array", "items": { "additionalProperties": true, "description": "Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "updated_prompts": { "description": "Server-wide prompt capability overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } }, "updated_tools": { "description": "Server-wide tool capability overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": [ "id", "name", "hostname", "auth_type", "tools", "prompts" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "MCP Portal Servers" ], "x-api-token-group": [ "MCP Portals Write", "MCP Portals Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.mcp_portals" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "mcp.servers", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "mcp-portals-api-create-servers", "summary": "Create a new MCP Server", "description": "Creates a new MCP server for connecting to an upstream MCP endpoint.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "a86a8f5c339544d7bdc89926de14fb8c" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "auth_credentials": { "description": "Static credential for the upstream MCP server. For auth_type \"bearer\", either a raw token string (e.g. \"sk-abc123\"), which is wrapped server-side as `Authorization: Bearer `, or a JSON-encoded object of the form `{\"headers\":{\"Header-Name\":\"value\",...}}` for custom or multiple static headers (e.g. Cloudflare Access service tokens: `{\"headers\":{\"cf-access-client-id\":\"...\",\"cf-access-client-secret\":\"...\"}}`).", "type": "string", "example": "sk-my-bearer-token", "x-sensitive": true }, "auth_type": { "description": "Authentication method used to connect to the upstream MCP server.", "type": "string", "example": "unauthenticated", "enum": [ "oauth", "bearer", "unauthenticated" ] }, "client_secret": { "description": "Pre-registered OAuth client_secret. Write-only - accepted on create/update when auth_credentials.auth_mode is 'manual'. Stored AES-GCM-encrypted in server_oauth_secrets; never returned by read endpoints.", "type": "string", "writeOnly": true, "x-sensitive": true }, "description": { "description": "Optional description of the MCP server.", "type": "string", "example": "This is one remote MCP server", "maxLength": 512, "nullable": true }, "hostname": { "description": "URL of the upstream MCP endpoint.", "type": "string", "format": "uri", "example": "https://example.com/mcp" }, "id": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "is_shared_oauth_callback_enabled": { "description": "When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true.", "type": "boolean", "default": false }, "name": { "description": "Display name for the MCP server.", "type": "string", "example": "My MCP Server", "maxLength": 350 }, "secure_web_gateway": { "description": "Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "updated_prompts": { "description": "Server-wide prompt capability overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } }, "updated_tools": { "description": "Server-wide tool capability overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": [ "id", "name", "hostname", "auth_type" ] } } } }, "responses": { "201": { "description": "Returns the created Object", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "auth_config_summary": { "description": "Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value.", "type": "object", "properties": { "auth_mode": { "type": "string", "enum": [ "dcr", "manual" ] }, "client_secret_version": { "type": "number" }, "config": { "type": "object", "properties": { "authorization_endpoint": { "type": "string" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "revocation_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" } } }, "has_client_secret": { "type": "boolean" }, "registration_info": { "type": "object", "properties": { "client_id": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string" }, "token_endpoint_auth_method": { "type": "string" } } } }, "readOnly": true }, "auth_type": { "description": "Authentication method used to connect to the upstream MCP server.", "type": "string", "example": "unauthenticated", "enum": [ "oauth", "bearer", "unauthenticated" ] }, "authentication_status": { "description": "Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow.", "type": "string", "enum": [ "not_required", "required", "connected", "stale", "manual" ], "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "readOnly": true }, "description": { "description": "Optional description of the MCP server.", "type": "string", "example": "This is one remote MCP server", "maxLength": 512, "nullable": true }, "error": { "type": "string", "readOnly": true }, "error_details": { "type": "object", "properties": { "cause": { "description": "Underlying error message", "type": "string" }, "is_upstream": { "description": "True = MCP server returned an error. False = couldn't reach the server", "type": "boolean" }, "mcp_code": { "description": "MCP protocol error code", "type": "number" }, "retryable": { "description": "Whether the error is transient and worth retrying", "type": "boolean" }, "status_code": { "description": "HTTP status code from the server", "type": "number" } }, "readOnly": true }, "hostname": { "description": "URL of the upstream MCP endpoint.", "type": "string", "format": "uri", "example": "https://example.com/mcp" }, "id": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "is_shared_oauth_callback_enabled": { "description": "When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true.", "type": "boolean", "default": false }, "last_successful_sync": { "type": "string", "format": "date-time", "readOnly": true }, "last_synced": { "type": "string", "format": "date-time", "readOnly": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "readOnly": true }, "name": { "description": "Display name for the MCP server.", "type": "string", "example": "My MCP Server", "maxLength": 350 }, "prompts": { "type": "array", "items": { "additionalProperties": true, "description": "Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "secure_web_gateway": { "description": "Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "status": { "description": "Current sync state of the server", "type": "string", "example": "ready", "default": "waiting", "enum": [ "waiting", "ready", "stale", "error" ], "readOnly": true }, "tools": { "type": "array", "items": { "additionalProperties": true, "description": "Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "updated_prompts": { "description": "Server-wide prompt capability overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } }, "updated_tools": { "description": "Server-wide tool capability overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": [ "id", "name", "hostname", "auth_type", "tools", "prompts" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7001 }, "message": { "type": "string", "example": "Input Validation Error" }, "path": { "type": "array", "items": { "example": "body", "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "MCP Portal Servers" ], "x-api-token-group": [ "MCP Portals Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.mcp_portals" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "mcp.servers", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/access/ai-controls/mcp/servers/{id}": { "delete": { "operationId": "mcp-portals-api-delete-servers", "summary": "Delete an MCP Server", "description": "Deletes an MCP server from the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "a86a8f5c339544d7bdc89926de14fb8c" } }, { "name": "id", "in": "path", "required": true, "schema": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } } ], "responses": { "200": { "description": "Returns the Object if it was successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "auth_config_summary": { "description": "Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value.", "type": "object", "properties": { "auth_mode": { "type": "string", "enum": [ "dcr", "manual" ] }, "client_secret_version": { "type": "number" }, "config": { "type": "object", "properties": { "authorization_endpoint": { "type": "string" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "revocation_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" } } }, "has_client_secret": { "type": "boolean" }, "registration_info": { "type": "object", "properties": { "client_id": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string" }, "token_endpoint_auth_method": { "type": "string" } } } }, "readOnly": true }, "auth_type": { "description": "Authentication method used to connect to the upstream MCP server.", "type": "string", "example": "unauthenticated", "enum": [ "oauth", "bearer", "unauthenticated" ] }, "authentication_status": { "description": "Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow.", "type": "string", "enum": [ "not_required", "required", "connected", "stale", "manual" ], "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "readOnly": true }, "description": { "description": "Optional description of the MCP server.", "type": "string", "example": "This is one remote MCP server", "maxLength": 512, "nullable": true }, "error": { "type": "string", "readOnly": true }, "error_details": { "type": "object", "properties": { "cause": { "description": "Underlying error message", "type": "string" }, "is_upstream": { "description": "True = MCP server returned an error. False = couldn't reach the server", "type": "boolean" }, "mcp_code": { "description": "MCP protocol error code", "type": "number" }, "retryable": { "description": "Whether the error is transient and worth retrying", "type": "boolean" }, "status_code": { "description": "HTTP status code from the server", "type": "number" } }, "readOnly": true }, "hostname": { "description": "URL of the upstream MCP endpoint.", "type": "string", "format": "uri", "example": "https://example.com/mcp" }, "id": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "is_shared_oauth_callback_enabled": { "description": "When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true.", "type": "boolean", "default": false }, "last_successful_sync": { "type": "string", "format": "date-time", "readOnly": true }, "last_synced": { "type": "string", "format": "date-time", "readOnly": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "readOnly": true }, "name": { "description": "Display name for the MCP server.", "type": "string", "example": "My MCP Server", "maxLength": 350 }, "prompts": { "type": "array", "items": { "additionalProperties": true, "description": "Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "secure_web_gateway": { "description": "Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "status": { "description": "Current sync state of the server", "type": "string", "example": "ready", "default": "waiting", "enum": [ "waiting", "ready", "stale", "error" ], "readOnly": true }, "tools": { "type": "array", "items": { "additionalProperties": true, "description": "Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "updated_prompts": { "description": "Server-wide prompt capability overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } }, "updated_tools": { "description": "Server-wide tool capability overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": [ "id", "name", "hostname", "auth_type", "tools", "prompts" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "MCP Portal Servers" ], "x-api-token-group": [ "MCP Portals Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.mcp_portals" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "mcp.servers", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation permanently deletes the MCP server, removes it from every portal, and deletes its stored OAuth secrets." }, "get": { "operationId": "mcp-portals-api-fetch-servers", "summary": "Read the details of an MCP Server", "description": "Retrieves an MCP server's configuration and capability sync state.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "a86a8f5c339544d7bdc89926de14fb8c" } }, { "name": "id", "in": "path", "required": true, "schema": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } } ], "responses": { "200": { "description": "Returns a single object if found", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "auth_config_summary": { "description": "Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value.", "type": "object", "properties": { "auth_mode": { "type": "string", "enum": [ "dcr", "manual" ] }, "client_secret_version": { "type": "number" }, "config": { "type": "object", "properties": { "authorization_endpoint": { "type": "string" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "revocation_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" } } }, "has_client_secret": { "type": "boolean" }, "registration_info": { "type": "object", "properties": { "client_id": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string" }, "token_endpoint_auth_method": { "type": "string" } } } }, "readOnly": true }, "auth_type": { "description": "Authentication method used to connect to the upstream MCP server.", "type": "string", "example": "unauthenticated", "enum": [ "oauth", "bearer", "unauthenticated" ] }, "authentication_status": { "description": "Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow.", "type": "string", "enum": [ "not_required", "required", "connected", "stale", "manual" ], "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "readOnly": true }, "description": { "description": "Optional description of the MCP server.", "type": "string", "example": "This is one remote MCP server", "maxLength": 512, "nullable": true }, "error": { "type": "string", "readOnly": true }, "error_details": { "type": "object", "properties": { "cause": { "description": "Underlying error message", "type": "string" }, "is_upstream": { "description": "True = MCP server returned an error. False = couldn't reach the server", "type": "boolean" }, "mcp_code": { "description": "MCP protocol error code", "type": "number" }, "retryable": { "description": "Whether the error is transient and worth retrying", "type": "boolean" }, "status_code": { "description": "HTTP status code from the server", "type": "number" } }, "readOnly": true }, "hostname": { "description": "URL of the upstream MCP endpoint.", "type": "string", "format": "uri", "example": "https://example.com/mcp" }, "id": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "is_shared_oauth_callback_enabled": { "description": "When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true.", "type": "boolean", "default": false }, "last_successful_sync": { "type": "string", "format": "date-time", "readOnly": true }, "last_synced": { "type": "string", "format": "date-time", "readOnly": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "readOnly": true }, "name": { "description": "Display name for the MCP server.", "type": "string", "example": "My MCP Server", "maxLength": 350 }, "prompts": { "type": "array", "items": { "additionalProperties": true, "description": "Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "secure_web_gateway": { "description": "Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "status": { "description": "Current sync state of the server", "type": "string", "example": "ready", "default": "waiting", "enum": [ "waiting", "ready", "stale", "error" ], "readOnly": true }, "tools": { "type": "array", "items": { "additionalProperties": true, "description": "Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "updated_prompts": { "description": "Server-wide prompt capability overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } }, "updated_tools": { "description": "Server-wide tool capability overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": [ "id", "name", "hostname", "auth_type", "tools", "prompts" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "MCP Portal Servers" ], "x-api-token-group": [ "MCP Portals Write", "MCP Portals Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.mcp_portals" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "mcp.servers", "x-fern-sdk-method-name": "read", "x-forge-hidden": true }, "put": { "operationId": "mcp-portals-api-update-servers", "summary": "Update an MCP Server", "description": "Updates an MCP server's configuration and credentials.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "a86a8f5c339544d7bdc89926de14fb8c" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "auth_credentials": { "description": "Static credential for the upstream MCP server. For auth_type \"bearer\", either a raw token string (e.g. \"sk-abc123\"), which is wrapped server-side as `Authorization: Bearer `, or a JSON-encoded object of the form `{\"headers\":{\"Header-Name\":\"value\",...}}` for custom or multiple static headers (e.g. Cloudflare Access service tokens: `{\"headers\":{\"cf-access-client-id\":\"...\",\"cf-access-client-secret\":\"...\"}}`).", "type": "string", "example": "sk-my-bearer-token", "x-sensitive": true }, "client_secret": { "description": "Pre-registered OAuth client_secret. Write-only - accepted on create/update when auth_credentials.auth_mode is 'manual'. Stored AES-GCM-encrypted in server_oauth_secrets; never returned by read endpoints.", "type": "string", "writeOnly": true, "x-sensitive": true }, "description": { "description": "Optional description of the MCP server.", "type": "string", "example": "This is one remote MCP server", "maxLength": 512, "nullable": true }, "is_shared_oauth_callback_enabled": { "description": "When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true.", "type": "boolean", "default": false }, "name": { "description": "Display name for the MCP server.", "type": "string", "example": "My MCP Server", "maxLength": 350 }, "secure_web_gateway": { "description": "Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "updated_prompts": { "description": "Server-wide prompt capability overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } }, "updated_tools": { "description": "Server-wide tool capability overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } } } } } } }, "responses": { "200": { "description": "Returns the updated Object", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "auth_config_summary": { "description": "Safe subset of auth_credentials surfaced to the dashboard. Includes auth_mode (dcr|manual), has_client_secret, client_secret_version, and the OAuth endpoints + client_id for manual servers. Never includes the secret value.", "type": "object", "properties": { "auth_mode": { "type": "string", "enum": [ "dcr", "manual" ] }, "client_secret_version": { "type": "number" }, "config": { "type": "object", "properties": { "authorization_endpoint": { "type": "string" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "revocation_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" } } }, "has_client_secret": { "type": "boolean" }, "registration_info": { "type": "object", "properties": { "client_id": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string" }, "token_endpoint_auth_method": { "type": "string" } } } }, "readOnly": true }, "auth_type": { "description": "Authentication method used to connect to the upstream MCP server.", "type": "string", "example": "unauthenticated", "enum": [ "oauth", "bearer", "unauthenticated" ] }, "authentication_status": { "description": "Whether administrative authentication is required before capabilities can be synced. Manual OAuth is user-managed and has no administrative authentication flow.", "type": "string", "enum": [ "not_required", "required", "connected", "stale", "manual" ], "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "readOnly": true }, "description": { "description": "Optional description of the MCP server.", "type": "string", "example": "This is one remote MCP server", "maxLength": 512, "nullable": true }, "error": { "type": "string", "readOnly": true }, "error_details": { "type": "object", "properties": { "cause": { "description": "Underlying error message", "type": "string" }, "is_upstream": { "description": "True = MCP server returned an error. False = couldn't reach the server", "type": "boolean" }, "mcp_code": { "description": "MCP protocol error code", "type": "number" }, "retryable": { "description": "Whether the error is transient and worth retrying", "type": "boolean" }, "status_code": { "description": "HTTP status code from the server", "type": "number" } }, "readOnly": true }, "hostname": { "description": "URL of the upstream MCP endpoint.", "type": "string", "format": "uri", "example": "https://example.com/mcp" }, "id": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" }, "is_shared_oauth_callback_enabled": { "description": "When true, the gateway worker uses the shared Cloudflare-owned OAuth callback endpoint as the redirect_uri for upstream on-behalf OAuth, instead of the customer portal hostname. Defaults to false (off); opt in per server by setting true.", "type": "boolean", "default": false }, "last_successful_sync": { "type": "string", "format": "date-time", "readOnly": true }, "last_synced": { "type": "string", "format": "date-time", "readOnly": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "readOnly": true }, "name": { "description": "Display name for the MCP server.", "type": "string", "example": "My MCP Server", "maxLength": 350 }, "prompts": { "type": "array", "items": { "additionalProperties": true, "description": "Prompt definition synced from the upstream MCP server. It follows the MCP Prompt shape: name plus optional title, description, and arguments, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "secure_web_gateway": { "description": "Route outbound traffic to this MCP server through Zero Trust Secure Web Gateway.", "type": "boolean", "example": false, "default": false }, "status": { "description": "Current sync state of the server", "type": "string", "example": "ready", "default": "waiting", "enum": [ "waiting", "ready", "stale", "error" ], "readOnly": true }, "tools": { "type": "array", "items": { "additionalProperties": true, "description": "Tool definition synced from the upstream MCP server. It follows the MCP Tool shape: name plus optional title, description, inputSchema, outputSchema, and annotations, with unknown fields passed through unchanged.", "type": "object" }, "readOnly": true }, "updated_prompts": { "description": "Server-wide prompt capability overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } }, "updated_tools": { "description": "Server-wide tool capability overrides.", "type": "array", "items": { "properties": { "alias": { "description": "Custom name exposed for the capability.", "type": "string", "example": "my-custom-alias", "maxLength": 40, "pattern": "^[a-zA-Z0-9]+([_-][a-zA-Z0-9]+)*$" }, "description": { "description": "Custom description exposed for the capability.", "type": "string" }, "enabled": { "description": "Whether the capability is available through the MCP server.", "type": "boolean" }, "name": { "description": "Name of the tool or prompt capability to override.", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": [ "id", "name", "hostname", "auth_type", "tools", "prompts" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7001 }, "message": { "type": "string", "example": "Input Validation Error" }, "path": { "type": "array", "items": { "example": "body", "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "MCP Portal Servers" ], "x-api-token-group": [ "MCP Portals Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.mcp_portals" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "mcp.servers", "x-fern-sdk-method-name": "update", "x-forge-hidden": true, "x-forge-params": { "is_shared_oauth_callback_enabled": { "default": null }, "secure_web_gateway": { "default": null } } } }, "/accounts/{account_id}/access/ai-controls/mcp/servers/{id}/sync": { "post": { "operationId": "mcp-portals-api-sync-server", "summary": "Sync MCP Server Capabilities", "description": "Syncs an MCP server's capabilities and returns the updated server state, including any connection errors.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "description": "Unique identifier for the MCP server.", "type": "string", "example": "my-mcp-server", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "a86a8f5c339544d7bdc89926de14fb8c" } } ], "responses": { "200": { "description": "Sync completed. Check result.status and result.error_details for outcome.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "error": { "type": "string" }, "error_details": { "type": "object", "properties": { "cause": { "description": "Underlying error message", "type": "string" }, "is_upstream": { "description": "True = MCP server returned an error. False = couldn't reach the server", "type": "boolean" }, "mcp_code": { "description": "MCP protocol error code", "type": "number" }, "retryable": { "description": "Whether the error is transient and worth retrying", "type": "boolean" }, "status_code": { "description": "HTTP status code from the server", "type": "number" } }, "readOnly": true }, "status": { "type": "string", "enum": [ "waiting", "ready", "stale", "error" ] } } }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "MCP Portal Servers" ], "x-api-token-group": [ "MCP Portals Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.mcp_portals" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "mcp.servers", "x-fern-sdk-method-name": "sync", "x-forge-hidden": true } }, "/accounts/{account_id}/access/apps": { "get": { "operationId": "access-applications-list-access-applications", "summary": "List Access applications", "description": "Lists all Access applications in an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "name", "in": "query", "schema": { "description": "The name of the app.", "type": "string" } }, { "name": "domain", "in": "query", "schema": { "description": "The domain of the app.", "type": "string" } }, { "name": "aud", "in": "query", "schema": { "description": "The aud of the app.", "type": "string" } }, { "name": "target_attributes", "in": "query", "schema": { "description": "Target Criteria attributes in key=value format.", "type": "string" } }, { "name": "exact", "in": "query", "schema": { "description": "True for only exact string matches against passed name/domain query parameters.", "type": "boolean" } }, { "name": "search", "in": "query", "schema": { "description": "Search for apps by other listed query parameters.", "type": "string" } }, { "$ref": "#/components/parameters/access_page" }, { "$ref": "#/components/parameters/access_per_page" } ], "responses": { "200": { "description": "List Access applications response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-7" } } } }, "4XX": { "description": "List Access applications response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access applications" ], "x-api-token-group": [ "Access: Apps and Policies Revoke", "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications", "x-fern-sdk-method-name": "list", "x-forge-hidden": true, "x-stability": "beta" }, "post": { "operationId": "access-applications-add-an-application", "summary": "Add an Access application", "description": "Adds a new application to Access.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_app_request" } } } }, "responses": { "201": { "description": "Add an Access application response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/access_single_response-8" }, { "properties": { "result": { "$ref": "#/components/schemas/access_app_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Add an Access application response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access applications" ], "x-api-token-group": [ "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-stability": "beta" } }, "/accounts/{account_id}/access/apps/ca": { "get": { "operationId": "access-short-lived-certificate-c-as-list-short-lived-certificate-c-as", "summary": "List short-lived certificate CAs", "description": "Lists short-lived certificate CAs and their public keys.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "$ref": "#/components/parameters/access_page" }, { "name": "per_page", "in": "query", "schema": { "description": "Number of results per page.", "type": "integer", "default": 100, "maximum": 1000 } } ], "responses": { "200": { "description": "List short-lived certificate CAs response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-4" } } } }, "4XX": { "description": "List short-lived certificate CAs response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access short-lived certificate CAs" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications.cas", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/access/apps/{app_id}": { "delete": { "operationId": "access-applications-delete-an-access-application", "summary": "Delete an Access application", "description": "Deletes an application from Access.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_app_id" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "202": { "description": "Delete an Access application response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response" } } } }, "4XX": { "description": "Delete an Access application response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access applications" ], "x-api-token-group": [ "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "access-applications-get-an-access-application", "summary": "Get an Access application", "description": "Fetches information about an Access application.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_app_id" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get an Access application response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-8" } } } }, "4XX": { "description": "Get an Access application response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access applications" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stability": "beta" }, "put": { "operationId": "access-applications-update-an-access-application", "summary": "Update an Access application", "description": "Updates an Access application.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_app_id" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_app_request" } } } }, "responses": { "200": { "description": "Update an Access application response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/access_single_response-8" }, { "properties": { "result": { "$ref": "#/components/schemas/access_app_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Update an Access application response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access applications" ], "x-api-token-group": [ "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications", "x-fern-sdk-method-name": "update", "x-forge-hidden": true, "x-stability": "beta" } }, "/accounts/{account_id}/access/apps/{app_id}/ca": { "delete": { "operationId": "access-short-lived-certificate-c-as-delete-a-short-lived-certificate-ca", "summary": "Delete a short-lived certificate CA", "description": "Deletes a short-lived certificate CA.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "202": { "description": "Delete a short-lived certificate CA response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response-2" } } } }, "4XX": { "description": "Delete a short-lived certificate CA response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access short-lived certificate CAs" ], "x-api-token-group": [ "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications.cas", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "access-short-lived-certificate-c-as-get-a-short-lived-certificate-ca", "summary": "Get a short-lived certificate CA", "description": "Fetches a short-lived certificate CA and its public key.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get a short-lived certificate CA response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-5" } } } }, "4XX": { "description": "Get a short-lived certificate CA response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access short-lived certificate CAs" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications.cas", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "access-short-lived-certificate-c-as-create-a-short-lived-certificate-ca", "summary": "Create a short-lived certificate CA", "description": "Generates a new short-lived certificate CA and public key.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Create a short-lived certificate CA response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-5" } } } }, "4XX": { "description": "Create a short-lived certificate CA response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access short-lived certificate CAs" ], "x-api-token-group": [ "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications.cas", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/access/apps/{app_id}/policies": { "get": { "operationId": "access-policies-list-access-app-policies", "summary": "List Access application policies", "description": "Lists Access policies configured for an application. Returns both exclusively scoped and reusable policies used by the application.", "parameters": [ { "name": "app_id", "in": "path", "description": "The application ID.", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "$ref": "#/components/parameters/access_page" }, { "name": "per_page", "in": "query", "schema": { "description": "Number of results per page.", "type": "integer", "default": 200, "maximum": 1000 } } ], "responses": { "200": { "description": "List Access application policies response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-8" } } } }, "4XX": { "description": "List Access application policies response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access application-scoped policies" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications.policies", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "access-policies-create-an-access-policy", "summary": "Create an Access application policy", "description": "Creates a policy applying exclusive to a single application that defines the users or groups who can reach it. We recommend creating a reusable policy instead and subsequently referencing its ID in the application's 'policies' array.", "parameters": [ { "name": "app_id", "in": "path", "description": "The application ID.", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_app_policy_write_request" } } } }, "responses": { "201": { "description": "Create an Access application policy response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-9" } } } }, "4XX": { "description": "Create an Access application policy response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access application-scoped policies" ], "x-api-token-group": [ "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications.policies", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/access/apps/{app_id}/policies/{policy_id}": { "delete": { "operationId": "access-policies-delete-an-access-policy", "summary": "Delete an Access application policy", "description": "Deletes an Access policy specific to an application. To delete a reusable policy, use the /accounts/{account_id}/policies/{uid} endpoint.", "parameters": [ { "name": "app_id", "in": "path", "description": "The application ID.", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "policy_id", "in": "path", "description": "The policy ID.", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "202": { "description": "Delete an Access application policy response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response" } } } }, "4XX": { "description": "Delete an Access application policy response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access application-scoped policies" ], "x-api-token-group": [ "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications.policies", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "access-policies-get-an-access-policy", "summary": "Get an Access application policy", "description": "Fetches a single Access policy configured for an application. Returns both exclusively owned and reusable policies used by the application.", "parameters": [ { "name": "app_id", "in": "path", "description": "The application ID.", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "policy_id", "in": "path", "description": "The policy ID.", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get an Access policy response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-9" } } } }, "4XX": { "description": "Get an Access policy response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access application-scoped policies" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications.policies", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "access-policies-update-an-access-policy", "summary": "Update an Access application policy", "description": "Updates an Access policy specific to an application. To update a reusable policy, use the /accounts/{account_id}/policies/{uid} endpoint.", "parameters": [ { "name": "app_id", "in": "path", "description": "The application ID.", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "policy_id", "in": "path", "description": "The policy ID.", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "fido2_key_only": { "summary": "Update a policy requiring a FIDO2 key", "value": { "decision": "allow", "include": [ { "everyone": {} } ], "mfa_config": { "allowed_authenticators": [ "ssh_fido2_key" ] }, "name": "Allow SSH users with a FIDO2 key" } }, "piv_and_fido2_key": { "summary": "Update a policy allowing a PIV key or FIDO2 key", "value": { "decision": "allow", "include": [ { "everyone": {} } ], "mfa_config": { "allowed_authenticators": [ "piv_key", "ssh_fido2_key" ] }, "name": "Allow SSH users with a PIV key or FIDO2 key" } }, "piv_only": { "summary": "Update a policy requiring a PIV key", "value": { "decision": "allow", "include": [ { "everyone": {} } ], "mfa_config": { "allowed_authenticators": [ "piv_key" ] }, "name": "Allow SSH users with a PIV key" } } }, "schema": { "$ref": "#/components/schemas/access_app_policy_write_request" } } } }, "responses": { "200": { "description": "Update an Access application policy response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-9" } } } }, "4XX": { "description": "Update an Access application policy response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access application-scoped policies" ], "x-api-token-group": [ "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications.policies", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/access/apps/{app_id}/policies/{policy_id}/make_reusable": { "put": { "operationId": "access-policies-convert-reusable", "summary": "Convert an Access application policy to a reusable policy", "description": "Converts an application-scoped policy to a reusable policy. The policy will no longer be exclusively scoped to the application. Further updates to the policy should go through the /accounts/{account_id}/policies/{uid} endpoint.", "parameters": [ { "name": "app_id", "in": "path", "description": "The application ID.", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "policy_id", "in": "path", "description": "The policy ID.", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Convert an Access application policy to a reusable policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-8" } } } }, "4XX": { "description": "Convert an Access application policy to a reusable policy failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access application-scoped policies" ], "x-api-token-group": [ "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps.policies.make.reusable", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/access/apps/{app_id}/revoke_tokens": { "post": { "operationId": "access-applications-revoke-service-tokens", "summary": "Revoke application tokens", "description": "Revokes all tokens issued for an application.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_app_id" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "202": { "description": "Revoke application tokens response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_empty_response-2" } } } }, "4XX": { "description": "Revoke application tokens response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access applications" ], "x-api-token-group": [ "Access: Apps and Policies Revoke", "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications", "x-fern-sdk-method-name": "revoke-tokens", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation invalidates every service token for the app." } }, "/accounts/{account_id}/access/apps/{app_id}/settings": { "patch": { "operationId": "access-applications-patch-update-access-application-settings", "summary": "Update Access application settings", "description": "Updates Access application settings.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_app_id" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_app_settings_request" } } } }, "responses": { "202": { "description": "Update Access application settings response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/access_single_response_update" } ] } } } }, "4XX": { "description": "Update Access application settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access applications" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications.settings", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "access-applications-put-update-access-application-settings", "summary": "Update Access application settings", "description": "Updates Access application settings.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_app_id" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_app_settings_request" } } } }, "responses": { "202": { "description": "Update Access application settings response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/access_single_response_update" } ] } } } }, "4XX": { "description": "Update Access application settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access applications" ], "x-api-token-group": [ "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications.settings", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/access/apps/{app_id}/user_policy_checks": { "get": { "operationId": "access-applications-test-access-policies", "summary": "Test Access policies", "description": "Tests if a specific user has permission to access an application.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_app_id" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Test Access policies response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_policy_check_response" } } } }, "4XX": { "description": "Test Access policies response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access applications" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications.user-policy-checks", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/access/authenticator_device_aaguids": { "get": { "operationId": "access-authenticator-device-aaguids-list", "summary": "List authenticator device AAGUIDs", "description": "Returns a list of Authenticator Device AAGUIDs for MFA configuration.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "List authenticator device AAGUIDs response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-16" } } } }, "4XX": { "description": "List authenticator device AAGUIDs response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access Authenticator Device AAGUIDs" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.authenticator-device-aaguids", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/access/bookmarks": { "get": { "operationId": "access-bookmark-applications-(-deprecated)-list-bookmark-applications", "summary": "List Bookmark applications", "description": "Lists Bookmark applications.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier-3" } } ], "responses": { "200": { "description": "List Bookmark applications response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-14" } } } }, "4XX": { "description": "List Bookmark applications response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access Bookmark applications (Deprecated)" ], "x-api-token-group": [ "Access: Apps and Policies Revoke", "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-cfDeprecation": { "description": "This endpoint is deprecated in favor of using a specialized Access Application App Type.", "display": true, "eol": "2023-03-19T00:00:00Z", "id": "bookmarks_deprecation" }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.bookmarks", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/access/bookmarks/{bookmark_id}": { "delete": { "operationId": "access-bookmark-applications-(-deprecated)-delete-a-bookmark-application", "summary": "Delete a Bookmark application", "description": "Deletes a Bookmark application.", "parameters": [ { "name": "bookmark_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier-3" } } ], "responses": { "200": { "description": "Delete a Bookmark application response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response" } } } }, "4XX": { "description": "Delete a Bookmark application response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access Bookmark applications (Deprecated)" ], "x-api-token-group": [ "Access: Apps and Policies Write" ], "x-cfDeprecation": { "description": "This endpoint is deprecated in favor of using a specialized Access Application App Type.", "display": true, "eol": "2023-03-19T00:00:00Z", "id": "bookmarks_deprecation" }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.bookmarks", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "access-bookmark-applications-(-deprecated)-get-a-bookmark-application", "summary": "Get a Bookmark application", "description": "Fetches a single Bookmark application.", "parameters": [ { "name": "bookmark_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier-3" } } ], "responses": { "200": { "description": "Get a Bookmark application response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-13" } } } }, "4XX": { "description": "Get a Bookmark application response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access Bookmark applications (Deprecated)" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-cfDeprecation": { "description": "This endpoint is deprecated in favor of using a specialized Access Application App Type.", "display": true, "eol": "2023-03-19T00:00:00Z", "id": "bookmarks_deprecation" }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.bookmarks", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "access-bookmark-applications-(-deprecated)-create-a-bookmark-application", "summary": "Create a Bookmark application", "description": "Create a new Bookmark application.", "parameters": [ { "name": "bookmark_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier-3" } } ], "responses": { "200": { "description": "Create a Bookmark application response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-13" } } } }, "4XX": { "description": "Create a Bookmark application response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access Bookmark applications (Deprecated)" ], "x-cfDeprecation": { "description": "This endpoint is deprecated in favor of using a specialized Access Application App Type.", "display": true, "eol": "2023-03-19T00:00:00Z", "id": "bookmarks_deprecation" }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.bookmarks", "x-fern-sdk-method-name": "create", "x-forge-hidden": true }, "put": { "operationId": "access-bookmark-applications-(-deprecated)-update-a-bookmark-application", "summary": "Update a Bookmark application", "description": "Updates a configured Bookmark application.", "parameters": [ { "name": "bookmark_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier-3" } } ], "responses": { "200": { "description": "Update a Bookmark application response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-13" } } } }, "4XX": { "description": "Update a Bookmark application response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access Bookmark applications (Deprecated)" ], "x-api-token-group": [ "Access: Apps and Policies Write" ], "x-cfDeprecation": { "description": "This endpoint is deprecated in favor of using a specialized Access Application App Type.", "display": true, "eol": "2023-03-19T00:00:00Z", "id": "bookmarks_deprecation" }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.bookmarks", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/access/certificates": { "get": { "operationId": "access-mtls-authentication-list-mtls-certificates", "summary": "List mTLS certificates", "description": "Lists all mTLS root certificates.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "$ref": "#/components/parameters/access_page" }, { "name": "per_page", "in": "query", "schema": { "description": "Number of results per page.", "type": "integer", "default": 50, "maximum": 1000 } } ], "responses": { "200": { "description": "List mTLS certificates response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-5" } } } }, "4XX": { "description": "List mTLS certificates response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access mTLS authentication" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write", "Access: Mutual TLS Certificates Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.certificates", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "access-mtls-authentication-add-an-mtls-certificate", "summary": "Add an mTLS certificate", "description": "Adds a new mTLS root certificate to Access.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "associated_hostnames": { "$ref": "#/components/schemas/access_associated_hostnames" }, "certificate": { "description": "The certificate content.", "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIGAjCCA+qgAwIBAgIJAI7kymlF7CWT...N4RI7KKB7nikiuUf8vhULKy5IX10\nDrUtmu/B\n-----END CERTIFICATE-----" }, "name": { "$ref": "#/components/schemas/access_name-7" } }, "required": [ "name", "certificate" ] } } } }, "responses": { "201": { "description": "Add an mTLS certificate response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-6" } } } }, "4XX": { "description": "Add an mTLS certificate response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access mTLS authentication" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.certificates", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/access/certificates/settings": { "get": { "operationId": "access-mtls-authentication-list-mtls-certificates-hostname-settings", "summary": "List all mTLS hostname settings", "description": "List all mTLS hostname settings for this account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "List mTLS hostname settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection_hostnames" } } } }, "4XX": { "description": "List mTLS hostname settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access mTLS authentication" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write", "Access: Mutual TLS Certificates Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.certificates.settings", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "access-mtls-authentication-update-an-mtls-certificate-settings", "summary": "Update an mTLS certificate's hostname settings", "description": "Updates an mTLS certificate's hostname settings.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "array", "items": { "$ref": "#/components/schemas/access_settings" } } }, "required": [ "settings" ] } } } }, "responses": { "202": { "description": "Update an mTLS certificates hostname settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection_hostnames" } } } }, "4XX": { "description": "Update an mTLS certificates hostname settings failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access mTLS authentication" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.certificates.settings", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/access/certificates/{certificate_id}": { "delete": { "operationId": "access-mtls-authentication-delete-an-mtls-certificate", "summary": "Delete an mTLS certificate", "description": "Deletes an mTLS certificate.", "parameters": [ { "name": "certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Delete an mTLS certificate response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response-3" } } } }, "4XX": { "description": "Delete an mTLS certificate response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access mTLS authentication" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.certificates", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "access-mtls-authentication-get-an-mtls-certificate", "summary": "Get an mTLS certificate", "description": "Fetches a single mTLS certificate.", "parameters": [ { "name": "certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get an mTLS certificate response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-6" } } } }, "4XX": { "description": "Get an mTLS certificate response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access mTLS authentication" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write", "Access: Mutual TLS Certificates Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.certificates", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "access-mtls-authentication-update-an-mtls-certificate", "summary": "Update an mTLS certificate", "description": "Updates a configured mTLS certificate.", "parameters": [ { "name": "certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "associated_hostnames": { "$ref": "#/components/schemas/access_associated_hostnames" }, "name": { "$ref": "#/components/schemas/access_name-7" } }, "required": [ "associated_hostnames" ] } } } }, "responses": { "200": { "description": "Update an mTLS certificate response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-6" } } } }, "4XX": { "description": "Update an mTLS certificate response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access mTLS authentication" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.certificates", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/access/custom_pages": { "get": { "operationId": "access-custom-pages-list-custom-pages", "summary": "List custom pages", "description": "List custom pages", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "$ref": "#/components/parameters/access_page" }, { "name": "per_page", "in": "query", "schema": { "description": "Number of results per page.", "type": "integer", "default": 50, "maximum": 1000 } } ], "responses": { "200": { "description": "List custom pages response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-10" } } } }, "4XX": { "description": "List custom pages response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access custom pages" ], "x-api-token-group": [ "Access: Custom Pages Write", "Access: Custom Pages Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.custom-pages", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "access-custom-pages-create-a-custom-page", "summary": "Create a custom page", "description": "Create a custom page", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_custom_page" } } } }, "responses": { "201": { "description": "Create a custom page response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response_without_html" } } } }, "422": { "description": "Template failed content validation; the verdict rides in the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_validate_response" } } } }, "4XX": { "description": "Create a custom page response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access custom pages" ], "x-api-token-group": [ "Access: Custom Pages Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.custom-pages", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/access/custom_pages/validate": { "post": { "operationId": "access-custom-pages-validate-a-custom-page-template", "summary": "Validate a custom page template", "description": "Validate a Liquid template and return its errors and warnings without persisting it.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_custom_page_validate" } } } }, "responses": { "200": { "description": "Validate a custom page template response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_validate_response" } } } }, "4XX": { "description": "Validate a custom page template response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access custom pages" ], "x-api-token-group": [ "Access: Custom Pages Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.custom-pages", "x-fern-sdk-method-name": "validate", "x-forge-hidden": true } }, "/accounts/{account_id}/access/custom_pages/{custom_page_id}": { "delete": { "operationId": "access-custom-pages-delete-a-custom-page", "summary": "Delete a custom page", "description": "Delete a custom page", "parameters": [ { "name": "custom_page_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "202": { "description": "Delete a custom page response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response-3" } } } }, "4XX": { "description": "Delete a custom page response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access custom pages" ], "x-api-token-group": [ "Access: Custom Pages Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.custom-pages", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "access-custom-pages-get-a-custom-page", "summary": "Get a custom page", "description": "Fetches a custom page and also returns its HTML.", "parameters": [ { "name": "custom_page_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get a custom page response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-11" } } } }, "4XX": { "description": "Get a custom page response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access custom pages" ], "x-api-token-group": [ "Access: Custom Pages Write", "Access: Custom Pages Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.custom-pages", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "access-custom-pages-update-a-custom-page", "summary": "Update a custom page", "description": "Update a custom page", "parameters": [ { "name": "custom_page_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_custom_page" } } } }, "responses": { "200": { "description": "Update a custom page response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response_without_html" } } } }, "422": { "description": "Template failed content validation; the verdict rides in the result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_validate_response" } } } }, "4XX": { "description": "Update a custom page response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access custom pages" ], "x-api-token-group": [ "Access: Custom Pages Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.custom-pages", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/access/gateway_ca": { "get": { "operationId": "access-gateway-ca-list-SSH-ca", "summary": "List SSH Certificate Authorities (CA)", "description": "Lists SSH Certificate Authorities (CA).", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "List SSH Certificate Authorities (CA) response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-6" } } } }, "4XX": { "description": "List SSH Certificate Authorities (CA) response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Gateway CA" ], "x-api-token-group": [ "Access: SSH Auditing Write", "Access: SSH Auditing Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.gateway-ca", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "access-gateway-ca-add-an-SSH-ca", "summary": "Add a new SSH Certificate Authority (CA)", "description": "Adds a new SSH Certificate Authority (CA).", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "201": { "description": "Add a new SSH Certificate Authority (CA) response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-7" } } } }, "4XX": { "description": "Add a new SSH Certificate Authority (CA) response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Gateway CA" ], "x-api-token-group": [ "Access: SSH Auditing Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.gateway-ca", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/access/gateway_ca/{certificate_id}": { "delete": { "operationId": "access-gateway-ca-delete-an-SSH-ca", "summary": "Delete an SSH Certificate Authority (CA)", "description": "Deletes an SSH Certificate Authority.", "parameters": [ { "name": "certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Delete an SSH Certificate Authority (CA) response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response" } } } }, "4XX": { "description": "Delete an SSH Certificate Authority (CA) response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Gateway CA" ], "x-api-token-group": [ "Access: SSH Auditing Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.gateway-ca", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true } }, "/accounts/{account_id}/access/groups": { "get": { "operationId": "access-groups-list-access-groups", "summary": "List Access groups", "description": "Lists all Access groups.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "name", "in": "query", "schema": { "description": "The name of the group.", "type": "string" } }, { "name": "search", "in": "query", "schema": { "description": "Search for groups by other listed query parameters.", "type": "string" } }, { "$ref": "#/components/parameters/access_page" }, { "$ref": "#/components/parameters/access_per_page" } ], "responses": { "200": { "description": "List Access groups response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-2" } } } }, "4XX": { "description": "List Access groups response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access groups" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write", "Access: Organizations, Identity Providers, and Groups Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.groups", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "access-groups-create-an-access-group", "summary": "Create an Access group", "description": "Creates a new Access group.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "exclude": { "$ref": "#/components/schemas/access_exclude" }, "include": { "$ref": "#/components/schemas/access_include" }, "is_default": { "$ref": "#/components/schemas/access_is_default" }, "name": { "$ref": "#/components/schemas/access_name-6" }, "require": { "$ref": "#/components/schemas/access_require" } }, "required": [ "name", "include" ] } } } }, "responses": { "201": { "description": "Create an Access group response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-4" } } } }, "4XX": { "description": "Create an Access group response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access groups" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.groups", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/access/groups/{group_id}": { "delete": { "operationId": "access-groups-delete-an-access-group", "summary": "Delete an Access group", "description": "Deletes an Access group.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "202": { "description": "Delete an Access group response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response" } } } }, "4XX": { "description": "Delete an Access group response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access groups" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.groups", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "access-groups-get-an-access-group", "summary": "Get an Access group", "description": "Fetches a single Access group.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get an Access group response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-4" } } } }, "4XX": { "description": "Get an Access group response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access groups" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write", "Access: Organizations, Identity Providers, and Groups Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.groups", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "access-groups-update-an-access-group", "summary": "Update an Access group", "description": "Updates a configured Access group.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "exclude": { "$ref": "#/components/schemas/access_exclude" }, "include": { "$ref": "#/components/schemas/access_include" }, "is_default": { "$ref": "#/components/schemas/access_is_default" }, "name": { "$ref": "#/components/schemas/access_name-6" }, "require": { "$ref": "#/components/schemas/access_require" } }, "required": [ "name", "include" ] } } } }, "responses": { "200": { "description": "Update an Access group response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-4" } } } }, "4XX": { "description": "Update an Access group response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access groups" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.groups", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/access/identity_providers": { "get": { "operationId": "access-identity-providers-list-access-identity-providers", "summary": "List Access identity providers", "description": "Lists all configured identity providers.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "scim_enabled", "in": "query", "schema": { "description": "Indicates to Access to only retrieve identity providers that have the System for Cross-Domain Identity Management (SCIM) enabled.", "type": "string", "example": true } }, { "$ref": "#/components/parameters/access_page" }, { "name": "per_page", "in": "query", "schema": { "description": "Number of results per page.", "type": "integer", "default": 200, "maximum": 1000 } } ], "responses": { "200": { "description": "List Access identity providers response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection" } } } }, "4XX": { "description": "List Access identity providers response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access identity providers" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write", "Access: Organizations, Identity Providers, and Groups Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.identity-providers", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "access-identity-providers-add-an-access-identity-provider", "summary": "Add an Access identity provider", "description": "Adds a new identity provider to Access.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_identity-providers" } } } }, "responses": { "201": { "description": "Add an Access identity provider response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-3" } } } }, "4XX": { "description": "Add an Access identity provider response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access identity providers" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.identity-providers", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/access/identity_providers/{identity_provider_id}": { "delete": { "operationId": "access-identity-providers-delete-an-access-identity-provider", "summary": "Delete an Access identity provider", "description": "Deletes an identity provider from Access.", "parameters": [ { "name": "identity_provider_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "202": { "description": "Delete an Access identity provider response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response" } } } }, "4XX": { "description": "Delete an Access identity provider response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access identity providers" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.identity-providers", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "access-identity-providers-get-an-access-identity-provider", "summary": "Get an Access identity provider", "description": "Fetches a configured identity provider.", "parameters": [ { "name": "identity_provider_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get an Access identity provider response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-3" } } } }, "4XX": { "description": "Get an Access identity provider response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access identity providers" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write", "Access: Organizations, Identity Providers, and Groups Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.identity-providers", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "access-identity-providers-update-an-access-identity-provider", "summary": "Update an Access identity provider", "description": "Updates a configured identity provider.", "parameters": [ { "name": "identity_provider_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_identity-providers" } } } }, "responses": { "200": { "description": "Update an Access identity provider response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-3" } } } }, "4XX": { "description": "Update an Access identity provider response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access identity providers" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.identity-providers", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/access/identity_providers/{identity_provider_id}/saml_certificate": { "post": { "operationId": "access-identity-providers-create-saml-certificate-for-identity-provider", "summary": "Create SAML encryption certificate for Identity Provider", "description": "Creates a new SAML encryption certificate set and assigns it to the specified \nSAML Identity Provider. This endpoint is idempotent - if the IdP already has \na certificate set assigned, the existing certificate set is returned with a 200 status.\n\n**Workflow for enabling SAML encryption:**\n1. Call this endpoint to create and assign a certificate set to the IdP\n2. Update the IdP configuration (PUT `/identity_providers/{id}`) with:\n - `config.enable_encryption: true`\n - `saml_certificate_set_id: `\n3. Configure the certificate's public key in your external SAML Identity Provider\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "identity_provider_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } } ], "responses": { "200": { "description": "IdP already has a certificate set assigned (idempotent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_saml_certificate_set_response" } } } }, "201": { "description": "SAML certificate set created and assigned to IdP", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_saml_certificate_set_response" } } } }, "403": { "description": "SAML encryption not enabled for organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } }, "404": { "description": "Identity provider not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } }, "4XX": { "description": "Create SAML certificate for IdP response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access identity providers" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.identity-providers.saml-certificate", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/access/identity_providers/{identity_provider_id}/scim/groups": { "get": { "operationId": "access-identity-providers-list-scim-group-resources", "summary": "List SCIM Group resources", "description": "Lists SCIM Group resources synced to Cloudflare via the System for Cross-domain Identity Management (SCIM).", "parameters": [ { "name": "identity_provider_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "cf_resource_id", "in": "query", "schema": { "$ref": "#/components/schemas/access_cf_resource_id" }, "explode": true, "style": "form" }, { "name": "idp_resource_id", "in": "query", "schema": { "$ref": "#/components/schemas/access_idp_resource_id" }, "explode": true, "style": "form" }, { "name": "name", "in": "query", "schema": { "$ref": "#/components/schemas/access_name-4" } }, { "$ref": "#/components/parameters/access_page" }, { "name": "per_page", "in": "query", "schema": { "description": "Number of results per page.", "type": "integer", "default": 100, "maximum": 100 } } ], "responses": { "200": { "description": "List SCIM Group resources response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_scim_groups_response" } } } }, "4XX": { "description": "List SCIM Group resources response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access identity providers" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write", "Access: Organizations, Identity Providers, and Groups Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.identity-providers.scim.groups", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/access/identity_providers/{identity_provider_id}/scim/users": { "get": { "operationId": "access-identity-providers-list-scim-user-resources", "summary": "List SCIM User resources", "description": "Lists SCIM User resources synced to Cloudflare via the System for Cross-domain Identity Management (SCIM).", "parameters": [ { "name": "identity_provider_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "cf_resource_id", "in": "query", "schema": { "$ref": "#/components/schemas/access_cf_resource_id-2" }, "explode": true, "style": "form" }, { "name": "idp_resource_id", "in": "query", "schema": { "$ref": "#/components/schemas/access_idp_resource_id-2" }, "explode": true, "style": "form" }, { "name": "username", "in": "query", "schema": { "$ref": "#/components/schemas/access_username" } }, { "name": "email", "in": "query", "schema": { "$ref": "#/components/schemas/access_email" } }, { "name": "name", "in": "query", "schema": { "$ref": "#/components/schemas/access_name-5" } }, { "$ref": "#/components/parameters/access_page" }, { "name": "per_page", "in": "query", "schema": { "description": "Number of results per page.", "type": "integer", "default": 100, "maximum": 100 } } ], "responses": { "200": { "description": "List SCIM User resources response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_scim_users_response" } } } }, "4XX": { "description": "List SCIM User resources response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access identity providers" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write", "Access: Organizations, Identity Providers, and Groups Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.identity-providers.scim.users", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/access/idp_federation_grants": { "get": { "operationId": "access-idp-federation-grants-list", "summary": "List IdP federation grants", "description": "Lists the IdP federation grants owned by the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "List IdP federation grants response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_idp_federation_grant_list_response" } } } }, "4XX": { "description": "List IdP federation grants response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access IdP federation grants" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.idp-federation-grants", "x-fern-sdk-method-name": "list", "x-forge-hidden": true, "x-stability": "beta" }, "post": { "operationId": "access-idp-federation-grants-create", "summary": "Create an IdP federation grant", "description": "Creates an IdP federation grant for the specified identity provider, making it\navailable for federation to other accounts in the same Cloudflare organization.\n\nThe account must belong to a Cloudflare organization. One-time pin and\nCloudflare-managed identity providers cannot be federated. An account\ncan federate at most five identity providers at a time.\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_idp_federation_grant_create_request" } } } }, "responses": { "201": { "description": "Create IdP federation grant response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_idp_federation_grant_response" } } } }, "4XX": { "description": "Create IdP federation grant response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access IdP federation grants" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.idp-federation-grants", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-stability": "beta" } }, "/accounts/{account_id}/access/idp_federation_grants/{grant_id}": { "delete": { "operationId": "access-idp-federation-grants-delete", "summary": "Delete an IdP federation grant", "description": "Deletes an IdP federation grant. The identity provider remains in the account,\nbut it is no longer available for federation to other accounts.\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "grant_id", "in": "path", "description": "UID of the IdP federation grant.", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "202": { "description": "Delete IdP federation grant response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_idp_federation_grant_id_response" } } } }, "404": { "description": "IdP federation grant does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } }, "4XX": { "description": "Delete IdP federation grant response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access IdP federation grants" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.idp-federation-grants", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "access-idp-federation-grants-get", "summary": "Get an IdP federation grant", "description": "Retrieves a single IdP federation grant by its UID.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "grant_id", "in": "path", "description": "UID of the IdP federation grant.", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get IdP federation grant response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_idp_federation_grant_response" } } } }, "404": { "description": "IdP federation grant does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } }, "4XX": { "description": "Get IdP federation grant response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access IdP federation grants" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.idp-federation-grants", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stability": "beta" } }, "/accounts/{account_id}/access/keys": { "get": { "operationId": "access-key-configuration-get-the-access-key-configuration", "summary": "Get the Access key configuration", "description": "Gets the Access key rotation settings for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get the Access key configuration response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-12" } } } }, "4XX": { "description": "Get the Access key configuration response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access key configuration" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write", "Access: Organizations, Identity Providers, and Groups Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.keys", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "access-key-configuration-update-the-access-key-configuration", "summary": "Update the Access key configuration", "description": "Updates the Access key rotation settings for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key_rotation_interval_days": { "$ref": "#/components/schemas/access_key_rotation_interval_days" } }, "required": [ "key_rotation_interval_days" ] } } } }, "responses": { "200": { "description": "Update the Access key configuration response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-12" } } } }, "4XX": { "description": "Update the Access key configuration response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access key configuration" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.keys", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/access/keys/rotate": { "post": { "operationId": "access-key-configuration-rotate-access-keys", "summary": "Rotate Access keys", "description": "Perfoms a key rotation for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Rotate Access keys response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-12" } } } }, "4XX": { "description": "Rotate Access keys response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access key configuration" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.keys", "x-fern-sdk-method-name": "rotate", "x-forge-hidden": true } }, "/accounts/{account_id}/access/logs/access_requests": { "get": { "operationId": "access-authentication-logs-get-access-authentication-logs", "summary": "Get Access authentication logs", "description": "Gets a list of Access authentication audit logs for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "limit", "in": "query", "description": "The maximum number of log entries to retrieve.", "schema": { "type": "integer", "default": 25 }, "example": 25 }, { "name": "direction", "in": "query", "description": "The chronological sorting order for the logs.", "schema": { "type": "string", "default": "desc", "enum": [ "desc", "asc" ] }, "example": "desc" }, { "name": "since", "in": "query", "description": "The earliest event timestamp to query.", "schema": { "type": "string", "format": "date-time", "example": "2020-07-01T05:20:00Z" } }, { "name": "until", "in": "query", "description": "The latest event timestamp to query.", "schema": { "type": "string", "format": "date-time", "example": "2020-10-01T05:20:00Z" } }, { "$ref": "#/components/parameters/access_page" }, { "name": "per_page", "in": "query", "schema": { "description": "Number of results per page.", "type": "integer", "default": 25 } }, { "name": "email", "in": "query", "description": "Filter by user email. Match mode is controlled by `emailOp` (preferred) or the legacy `email_exact` flag.\n- Default (no `emailOp`, `email_exact=false` or unset): substring match — `email=@example.com` returns all events with that domain.\n- Exact match: set `emailOp=eq` (preferred) or `email_exact=true` — e.g. `email=user@example.com&email_exact=true` returns only that user.\n- Explicit substring match: set `emailOp=contains` (without `email_exact=true`). When both are set, `email_exact=true` takes precedence and the match is exact.\n- Exclusion: set `emailOp=neq`. With `email_exact=true` this is an exact-value exclusion; without it, a fuzzy substring exclusion.\n", "schema": { "$ref": "#/components/schemas/access_email-3" } }, { "name": "email_exact", "in": "query", "description": "When true, `email` is matched exactly instead of substring matching.", "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "user_id", "in": "query", "description": "Deprecated. Accepted for backward compatibility but no longer applied\nas a filter. Use `email` instead.\n", "schema": { "$ref": "#/components/schemas/access_user_id" }, "deprecated": true }, { "name": "allowedOp", "in": "query", "description": "Operator for the `allowed` filter.", "schema": { "type": "string", "default": "eq", "enum": [ "eq", "neq" ] } }, { "name": "country_codeOp", "in": "query", "description": "Operator for the `country_code` filter.", "schema": { "type": "string", "default": "eq", "enum": [ "eq", "neq" ] } }, { "name": "app_typeOp", "in": "query", "description": "Operator for the `app_type` filter.", "schema": { "type": "string", "default": "eq", "enum": [ "eq", "neq" ] } }, { "name": "app_uidOp", "in": "query", "description": "Operator for the `app_uid` filter.", "schema": { "type": "string", "default": "eq", "enum": [ "eq", "neq" ] } }, { "name": "ray_idOp", "in": "query", "description": "Operator for the `ray_id` filter.", "schema": { "type": "string", "default": "eq", "enum": [ "eq", "neq" ] } }, { "name": "emailOp", "in": "query", "description": "Operator for the `email` filter.\n`contains` performs a substring (case-sensitive) match. When `email_exact=true`\nis also set, `email_exact` takes precedence and `contains` is ignored.\n", "schema": { "type": "string", "default": "eq", "enum": [ "eq", "neq", "contains" ] } }, { "name": "idpOp", "in": "query", "description": "Operator for the `idp` filter.", "schema": { "type": "string", "default": "eq", "enum": [ "eq", "neq" ] } }, { "name": "non_identityOp", "in": "query", "description": "Operator for the `non_identity` filter.", "schema": { "type": "string", "default": "eq", "enum": [ "eq", "neq" ] } }, { "name": "user_idOp", "in": "query", "description": "Deprecated. Accepted for backward compatibility but no longer applied\nas a filter (the `user_id` parameter is itself deprecated).\n", "schema": { "type": "string", "default": "eq", "enum": [ "eq", "neq" ] }, "deprecated": true }, { "name": "fields", "in": "query", "description": "Comma-separated list of fields to include in the response.\nWhen omitted, all fields are returned.\n", "schema": { "type": "string" }, "example": "action,allowed,app_name,country,created_at,ray_id,user_email" } ], "responses": { "200": { "description": "Get Access authentication logs response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-11" } } } }, "4XX": { "description": "Get Access authentication logs response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access authentication logs" ], "x-api-token-group": [ "Access: Audit Logs Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.logs.access-requests", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/access/logs/jit_requests": { "get": { "operationId": "access-jit-request-logs-list", "summary": "List Access JIT request logs", "description": "Lists account-wide Access JIT request logs reconstructed from request lifecycle events.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "$ref": "#/components/parameters/access_page" }, { "name": "per_page", "in": "query", "schema": { "description": "Number of results per page.", "type": "integer", "default": 25, "maximum": 1000 } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/access_jit_request_status" } }, { "name": "search", "in": "query", "description": "Case-insensitive search over request ID, requester email, application audience, and application hostname.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "description": "The earliest request timestamp to query. Defaults to 366 days before the current time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "description": "The latest request timestamp to query. Defaults to the current time.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Access JIT request logs response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-12" } } } }, "4XX": { "description": "Access JIT request logs response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access JIT request logs" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.logs.jit-requests", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/access/logs/jit_requests/{knock_request_id}": { "get": { "operationId": "access-jit-request-logs-get", "summary": "Get an Access JIT request log", "description": "Gets an account-scoped Access JIT request summary and its lifecycle events in chronological order.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "knock_request_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Access JIT request log detail response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_single" } } } }, "404": { "description": "Access JIT request log not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } }, "4XX": { "description": "Access JIT request log detail response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access JIT request logs" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.logs.jit-requests", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/access/logs/scim/updates": { "get": { "operationId": "access-scim-update-logs-list-access-scim-update-logs", "summary": "List Access SCIM update logs", "description": "Lists Access SCIM update logs that maintain a record of updates made to User and Group resources synced to Cloudflare via the System for Cross-domain Identity Management (SCIM).", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "limit", "in": "query", "schema": { "$ref": "#/components/schemas/access_limit" } }, { "name": "direction", "in": "query", "schema": { "$ref": "#/components/schemas/access_direction" }, "example": "desc" }, { "name": "since", "in": "query", "schema": { "$ref": "#/components/schemas/access_since" } }, { "name": "until", "in": "query", "schema": { "$ref": "#/components/schemas/access_until" } }, { "name": "idp_id", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/access_idp_id" }, "explode": true, "style": "form" }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/access_status-2" }, "explode": true, "style": "form" }, { "name": "resource_type", "in": "query", "schema": { "$ref": "#/components/schemas/access_resource_type" }, "explode": true, "style": "form" }, { "name": "request_method", "in": "query", "schema": { "$ref": "#/components/schemas/access_request_method" }, "explode": true, "style": "form" }, { "name": "resource_user_email", "in": "query", "schema": { "$ref": "#/components/schemas/access_resource_user_email" }, "explode": true, "style": "form" }, { "name": "resource_group_name", "in": "query", "schema": { "$ref": "#/components/schemas/access_resource_group_name" }, "explode": true, "style": "form" }, { "name": "cf_resource_id", "in": "query", "schema": { "$ref": "#/components/schemas/access_cf_resource_id-3" }, "explode": true, "style": "form" }, { "name": "idp_resource_id", "in": "query", "schema": { "$ref": "#/components/schemas/access_idp_resource_id-3" }, "explode": true, "style": "form" }, { "$ref": "#/components/parameters/access_page" }, { "name": "per_page", "in": "query", "schema": { "description": "Number of results per page.", "type": "integer", "default": 20, "maximum": 1000 } } ], "responses": { "200": { "description": "Get Access SCIM update logs response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_scim_update_logs_response" } } } }, "4XX": { "description": "Get Access SCIM update logs response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access SCIM update logs" ], "x-api-token-group": [ "Access: SCIM Logs Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.logs.scim.updates", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/access/organizations": { "get": { "operationId": "zero-trust-organization-get-your-zero-trust-organization", "summary": "Get your Zero Trust organization", "description": "Returns the configuration for your Zero Trust organization.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get your Zero Trust organization response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_get_response" } } } }, "4XX": { "description": "Get your Zero Trust organization response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust organization" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Revoke", "Access: Organizations, Identity Providers, and Groups Write", "Access: Organizations, Identity Providers, and Groups Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.organizations", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "zero-trust-organization-create-your-zero-trust-organization", "summary": "Create your Zero Trust organization", "description": "Sets up a Zero Trust organization for your account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allow_authenticate_via_warp": { "$ref": "#/components/schemas/access_allow_authenticate_via_warp" }, "auth_domain": { "$ref": "#/components/schemas/access_auth_domain" }, "auto_redirect_to_identity": { "$ref": "#/components/schemas/access_auto_redirect_to_identity" }, "deny_unmatched_requests": { "$ref": "#/components/schemas/access_deny_unmatched_requests" }, "deny_unmatched_requests_exempted_zone_names": { "$ref": "#/components/schemas/access_deny_unmatched_requests_exempted_zone_names" }, "is_ui_read_only": { "$ref": "#/components/schemas/access_is_ui_read_only" }, "login_design": { "$ref": "#/components/schemas/access_login_design" }, "mfa_config": { "$ref": "#/components/schemas/access_org_mfa_config" }, "mfa_piv_key_requirements": { "$ref": "#/components/schemas/access_mfa_piv_key_requirements" }, "mfa_required_for_all_apps": { "$ref": "#/components/schemas/access_mfa_required_for_all_apps" }, "name": { "$ref": "#/components/schemas/access_name" }, "session_duration": { "$ref": "#/components/schemas/access_session_duration" }, "ui_read_only_toggle_reason": { "$ref": "#/components/schemas/access_ui_read_only_toggle_reason" }, "user_seat_expiration_inactive_time": { "$ref": "#/components/schemas/access_user_seat_expiration_inactive_time" }, "warp_auth_non_browser_401": { "$ref": "#/components/schemas/access_warp_auth_non_browser_401" }, "warp_auth_session_duration": { "$ref": "#/components/schemas/access_warp_auth_session_duration" } }, "required": [ "name", "auth_domain" ] } } } }, "responses": { "201": { "description": "Create your Zero Trust organization response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response" } } } }, "4XX": { "description": "Create your Zero Trust organization response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust organization" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.organizations", "x-fern-sdk-method-name": "create", "x-forge-hidden": true }, "put": { "operationId": "zero-trust-organization-update-your-zero-trust-organization", "summary": "Update your Zero Trust organization", "description": "Updates the configuration for your Zero Trust organization.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allow_authenticate_via_warp": { "$ref": "#/components/schemas/access_allow_authenticate_via_warp" }, "auth_domain": { "$ref": "#/components/schemas/access_auth_domain" }, "auto_redirect_to_identity": { "$ref": "#/components/schemas/access_auto_redirect_to_identity" }, "custom_pages": { "$ref": "#/components/schemas/access_custom_pages" }, "deny_unmatched_requests": { "$ref": "#/components/schemas/access_deny_unmatched_requests" }, "deny_unmatched_requests_exempted_zone_names": { "$ref": "#/components/schemas/access_deny_unmatched_requests_exempted_zone_names" }, "is_ui_read_only": { "$ref": "#/components/schemas/access_is_ui_read_only" }, "login_design": { "$ref": "#/components/schemas/access_login_design" }, "mfa_config": { "$ref": "#/components/schemas/access_org_mfa_config" }, "mfa_piv_key_requirements": { "$ref": "#/components/schemas/access_mfa_piv_key_requirements" }, "mfa_required_for_all_apps": { "$ref": "#/components/schemas/access_mfa_required_for_all_apps" }, "name": { "$ref": "#/components/schemas/access_name" }, "session_duration": { "$ref": "#/components/schemas/access_session_duration" }, "ui_read_only_toggle_reason": { "$ref": "#/components/schemas/access_ui_read_only_toggle_reason" }, "user_seat_expiration_inactive_time": { "$ref": "#/components/schemas/access_user_seat_expiration_inactive_time" }, "warp_auth_non_browser_401": { "$ref": "#/components/schemas/access_warp_auth_non_browser_401" }, "warp_auth_session_duration": { "$ref": "#/components/schemas/access_warp_auth_session_duration" } } } } } }, "responses": { "200": { "description": "Update your Zero Trust organization response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response" } } } }, "4XX": { "description": "Update your Zero Trust organization response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust organization" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.organizations", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/access/organizations/doh": { "get": { "operationId": "zero-trust-organization-get-your-zero-trust-organization-doh-settings", "summary": "Get your Zero Trust organization DoH settings", "description": "Returns the DoH settings for your Zero Trust organization.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get your Zero Trust organization DoH settings response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/access_single_response-2" }, { "properties": { "result": { "type": "object", "properties": { "doh_jwt_duration": { "description": "The duration the DoH JWT is valid for. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. Note that the maximum duration for this setting is the same as the key rotation period on the account.", "type": "string", "example": "800h" } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Get your Zero Trust organization DoH settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust organization" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Revoke", "Access: Organizations, Identity Providers, and Groups Write", "Access: Organizations, Identity Providers, and Groups Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.organizations.doh", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "zero-trust-organization-update-your-zero-trust-organization-doh-settings", "summary": "Update your Zero Trust organization DoH settings", "description": "Updates the DoH settings for your Zero Trust organization.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "doh_jwt_duration": { "$ref": "#/components/schemas/access_doh_jwt_duration" }, "service_token_id": { "description": "The uuid of the service token you want to use for DoH authentication", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" } } } } } }, "responses": { "201": { "description": "Update your Zero Trust organization DoH settings response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/access_single_response-2" }, { "properties": { "result": { "type": "object", "properties": { "doh_jwt_duration": { "$ref": "#/components/schemas/access_doh_jwt_duration" } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Update your Zero Trust organization DoH settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust organization" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.organizations.doh", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/access/organizations/revoke_user": { "post": { "operationId": "zero-trust-organization-revoke-all-access-tokens-for-a-user", "summary": "Revoke all Access tokens for a user", "description": "Revokes a user's access across all applications.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "devices", "in": "query", "description": "When set to `true`, all devices associated with the user will be revoked.", "schema": { "type": "boolean" }, "example": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "devices": { "description": "When set to `true`, all devices associated with the user will be revoked.", "type": "boolean", "example": true }, "email": { "description": "The email of the user to revoke.", "type": "string", "example": "test@example.com" }, "user_uid": { "description": "The uuid of the user to revoke.", "type": "string", "example": "699d98642c564d2e855e9661899b7252" }, "warp_session_reauth": { "description": "When set to `true`, the user will be required to re-authenticate to WARP for all Gateway policies that enforce a WARP client session duration. When `false`, the user’s WARP session will remain active", "type": "boolean", "example": true } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Revoke all Access tokens for a user response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_empty_response" } } } }, "4XX": { "description": "Revoke all Access tokens for a user response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust organization" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.organizations", "x-fern-sdk-method-name": "revoke-users", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation revokes all access tokens for a user destructively." } }, "/accounts/{account_id}/access/policies": { "get": { "operationId": "access-policies-list-access-reusable-policies", "summary": "List Access reusable policies", "description": "Lists Access reusable policies.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "$ref": "#/components/parameters/access_page" }, { "name": "per_page", "in": "query", "schema": { "description": "Number of results per page.", "type": "integer", "default": 100, "maximum": 1000 } } ], "responses": { "200": { "description": "List Access reusable policies response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-9" } } } }, "4XX": { "description": "List Access reusable policies response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access reusable policies" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.policies", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "access-policies-create-an-access-reusable-policy", "summary": "Create an Access reusable policy", "description": "Creates a new Access reusable policy.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_policy_req" } } } }, "responses": { "201": { "description": "Create an Access reusable policy response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-10" } } } }, "4XX": { "description": "Create an Access reusable policy response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access reusable policies" ], "x-api-token-group": [ "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.policies", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/access/policies/{policy_id}": { "delete": { "operationId": "access-policies-delete-an-access-reusable-policy", "summary": "Delete an Access reusable policy", "description": "Deletes an Access reusable policy.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid-2" } } ], "responses": { "202": { "description": "Delete an Access reusable policy response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response-4" } } } }, "4XX": { "description": "Delete an Access reusable policy response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access reusable policies" ], "x-api-token-group": [ "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.policies", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "access-policies-get-an-access-reusable-policy", "summary": "Get an Access reusable policy", "description": "Fetches a single Access reusable policy.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid-2" } } ], "responses": { "200": { "description": "Get an Access reusable policy response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-10" } } } }, "4XX": { "description": "Get an Access reusable policy response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access reusable policies" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.policies", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "access-policies-update-an-access-reusable-policy", "summary": "Update an Access reusable policy", "description": "Updates a Access reusable policy.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid-2" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_policy_req" } } } }, "responses": { "200": { "description": "Update an Access reusable policy response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-10" } } } }, "4XX": { "description": "Update an Access reusable policy response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access reusable policies" ], "x-api-token-group": [ "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.policies", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/access/policy-tests": { "post": { "operationId": "access-policy-tests", "summary": "Start Access policy test", "description": "Starts an Access policy test.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_policy_init_req" } } } }, "responses": { "200": { "description": "Start Access policy test response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_policy_init_resp" } } } }, "400": { "description": "Start Access policy test response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access policy tester" ], "x-api-token-group": [ "Access: Policy Test Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications.policy-tests", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/access/policy-tests/{policy_test_id}": { "get": { "operationId": "access-policy-tests-get-an-update", "summary": "Get the current status of a given Access policy test", "description": "Fetches the current status of a given Access policy test.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "policy_test_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_policy_test_id" } } ], "responses": { "200": { "description": "Get an Access policy test update response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_policy_update_resp" } } } }, "400": { "description": "Get an Access policy test update response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access policy tester" ], "x-api-token-group": [ "Access: Policy Test Write", "Access: Policy Test Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications.policy-tests", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/access/policy-tests/{policy_test_id}/users": { "get": { "operationId": "access-policy-tests-get-a-user-page", "summary": "Get an Access policy test users page", "description": "Fetches a single page of user results from an Access policy test.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "policy_test_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_policy_test_id" } }, { "$ref": "#/components/parameters/access_page" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 1000 } }, { "name": "status", "in": "query", "description": "Filter users by their policy evaluation status.", "schema": { "type": "string", "enum": [ "success", "fail", "error" ] } } ], "responses": { "200": { "description": "Get an Access policy tester users page response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_policy_users_resp" } } } }, "400": { "description": "Get an Access policy tester users page response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access policy tester" ], "x-api-token-group": [ "Access: Policy Test Write", "Access: Policy Test Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.applications.policy-tests.users", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/access/saml_certificates": { "get": { "operationId": "access-saml-certificates-list-certificate-sets", "summary": "List SAML certificate sets", "description": "Returns a paginated list of the organization's SAML encryption certificate sets.\nEach certificate set includes the current and (if present) previous certificates.\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "page", "in": "query", "description": "Page number of paginated results.", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Maximum number of results per page.", "schema": { "type": "integer", "default": 25, "maximum": 1000, "minimum": 1 } }, { "name": "id", "in": "query", "description": "Filter by SAML certificate set UID. Accepts a comma-separated list of UIDs.", "schema": { "type": "string", "example": "a5bb4b3f-c2d1-4e6a-8f9b-1d3e4f5a6b7c,f174e90a-fafe-4643-bbbc-4a0ed4fc8415" } } ], "responses": { "200": { "description": "List SAML certificate sets response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_certificate_set_list_response" } } } }, "4XX": { "description": "List SAML certificate sets response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access SAML encryption certificates" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.saml-certificates", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/access/saml_certificates/{saml_cert_set_id}": { "get": { "operationId": "access-saml-certificates-get-certificate-set", "summary": "Get SAML certificate set", "description": "Retrieves a specific SAML encryption certificate set by its UID, including both current and previous certificates if available.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "saml_cert_set_id", "in": "path", "description": "UID of the SAML certificate set.", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } } ], "responses": { "200": { "description": "Get SAML certificate set response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_certificate_set_response" } } } }, "404": { "description": "SAML certificate set does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } }, "4XX": { "description": "Get SAML certificate set response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access SAML encryption certificates" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.saml-certificates", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/access/saml_certificates/{saml_cert_set_id}/pem": { "get": { "operationId": "access-saml-certificates-get-pem", "summary": "Download current certificate in PEM format", "description": "Downloads the current SAML encryption certificate's public key in PEM format for the specified certificate set. This endpoint is useful for providing the certificate to Identity Providers for SAML assertion encryption configuration.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "saml_cert_set_id", "in": "path", "description": "UID of the SAML certificate set.", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } } ], "responses": { "200": { "description": "PEM certificate file", "headers": { "Content-Disposition": { "schema": { "type": "string", "example": "attachment; filename=\"saml_certificate.pem\"" } } }, "content": { "application/x-pem-file": { "schema": { "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIGAjCCA+qgAwIBAgIJAI7kymlF7CWT...\n...certificate content...\n-----END CERTIFICATE-----\n" } } } }, "404": { "description": "SAML certificate set does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } }, "4XX": { "description": "Get PEM certificate response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access SAML encryption certificates" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.saml-certificates", "x-fern-sdk-method-name": "get-pem", "x-forge-hidden": true } }, "/accounts/{account_id}/access/saml_certificates/{saml_cert_set_id}/rotate": { "post": { "operationId": "access-saml-certificates-rotate-certificate", "summary": "Rotate SAML certificate", "description": "Rotates the SAML encryption certificates within the specified certificate set. This generates a new\ncertificate and moves the current certificate to the previous slot. If a previous certificate exists,\nit will be deactivated and removed.\n\nThis endpoint ensures zero-downtime rotation by maintaining both current and previous certificates \nduring the transition period, allowing IdPs time to update their configurations. Automated rotation\nhappens 30 days before a current certificate's expiration.\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "saml_cert_set_id", "in": "path", "description": "UID of the SAML certificate set to rotate.", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } } ], "responses": { "200": { "description": "Rotate SAML certificate response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_certificate_set_response" } } } }, "404": { "description": "SAML certificate set does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } }, "4XX": { "description": "Rotate SAML certificate response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access SAML encryption certificates" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.saml-certificates", "x-fern-sdk-method-name": "rotate", "x-forge-hidden": true } }, "/accounts/{account_id}/access/seats": { "patch": { "operationId": "zero-trust-seats-update-a-user-seat", "summary": "Update a user seat", "description": "Removes a user from a Zero Trust seat when both `access_seat` and `gateway_seat` are set to false.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier-2" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_seats_definition" } } } }, "responses": { "200": { "description": "Update a user seat response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-13" } } } }, "4XX": { "description": "Update a user seat response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust seats" ], "x-api-token-group": [ "Zero Trust: Seats Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.seats", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/access/service_tokens": { "get": { "operationId": "access-service-tokens-list-service-tokens", "summary": "List service tokens", "description": "Lists all service tokens.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "name", "in": "query", "schema": { "description": "The name of the service token.", "type": "string" } }, { "name": "search", "in": "query", "schema": { "description": "Search for service tokens by other listed query parameters.", "type": "string" } }, { "$ref": "#/components/parameters/access_page" }, { "$ref": "#/components/parameters/access_per_page" } ], "responses": { "200": { "description": "List service tokens response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-3" } } } }, "4XX": { "description": "List service tokens response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access service tokens" ], "x-api-token-group": [ "Access: Service Tokens Write", "Access: Service Tokens Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.service-tokens", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "access-service-tokens-create-a-service-token", "summary": "Create a service token", "description": "Generates a new service token. **Note:** This is the only time you can get the Client Secret. If you lose the Client Secret, you will have to rotate the Client Secret or create a new service token.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_secret_version": { "$ref": "#/components/schemas/access_client_secret_version" }, "duration": { "$ref": "#/components/schemas/access_duration" }, "enabled": { "$ref": "#/components/schemas/access_enabled" }, "name": { "$ref": "#/components/schemas/access_name-2" }, "previous_client_secret_expires_at": { "$ref": "#/components/schemas/access_previous_client_secret_expires_at" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Create a service token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_create_response" } } } }, "4XX": { "description": "Create a service token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access service tokens" ], "x-api-token-group": [ "Access: Service Tokens Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.service-tokens", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/access/service_tokens/{service_token_id}": { "delete": { "operationId": "access-service-tokens-delete-a-service-token", "summary": "Delete a service token", "description": "Deletes a service token.", "parameters": [ { "name": "service_token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Delete a service token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-2" } } } }, "4XX": { "description": "Delete a service token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access service tokens" ], "x-api-token-group": [ "Access: Service Tokens Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.service-tokens", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "access-service-tokens-get-a-service-token", "summary": "Get a service token", "description": "Fetches a single service token.", "parameters": [ { "name": "service_token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get a service token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-2" } } } }, "4XX": { "description": "Get a service token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access service tokens" ], "x-api-token-group": [ "Access: Service Tokens Write", "Access: Service Tokens Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.service-tokens", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "access-service-tokens-update-a-service-token", "summary": "Update a service token", "description": "Updates a configured service token.", "parameters": [ { "name": "service_token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_secret_version": { "$ref": "#/components/schemas/access_client_secret_version" }, "duration": { "$ref": "#/components/schemas/access_duration" }, "enabled": { "$ref": "#/components/schemas/access_enabled" }, "name": { "$ref": "#/components/schemas/access_name-2" }, "previous_client_secret_expires_at": { "$ref": "#/components/schemas/access_previous_client_secret_expires_at" } } } } } }, "responses": { "200": { "description": "Update a service token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-2" } } } }, "4XX": { "description": "Update a service token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access service tokens" ], "x-api-token-group": [ "Access: Service Tokens Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.service-tokens", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/access/service_tokens/{service_token_id}/refresh": { "post": { "operationId": "access-service-tokens-refresh-a-service-token", "summary": "Refresh a service token", "description": "Refreshes the expiration of a service token.", "parameters": [ { "name": "service_token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Refresh a service token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-2" } } } }, "4XX": { "description": "Refresh a service token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access service tokens" ], "x-api-token-group": [ "Access: Service Tokens Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.service-tokens", "x-fern-sdk-method-name": "refresh", "x-forge-hidden": true } }, "/accounts/{account_id}/access/service_tokens/{service_token_id}/rotate": { "post": { "operationId": "access-service-tokens-rotate-a-service-token", "summary": "Rotate a service token", "description": "Generates a new Client Secret for a service token and revokes the old one.", "parameters": [ { "name": "service_token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "previous_client_secret_expires_at": { "description": "The expiration of the previous `client_secret`. If not provided, it defaults to the current timestamp in order to immediately expire the previous secret.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "x-auditable": true } } } } } }, "responses": { "200": { "description": "Rotate a service token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_create_response" } } } }, "4XX": { "description": "Rotate a service token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access service tokens" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.service-tokens", "x-fern-sdk-method-name": "rotate", "x-forge-hidden": true } }, "/accounts/{account_id}/access/tags": { "get": { "operationId": "access-tags-list-tags", "summary": "List tags", "description": "List tags", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "$ref": "#/components/parameters/access_page" }, { "name": "per_page", "in": "query", "schema": { "description": "Number of results per page.", "type": "integer", "default": 50, "maximum": 1000 } } ], "responses": { "200": { "description": "List tags response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-15" } } } }, "4XX": { "description": "List tags response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access tags" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.tags", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "access-tags-create-tag", "summary": "Create a tag", "description": "Create a tag", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/access_name-13" } } } } } }, "responses": { "201": { "description": "Create a tag response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-14" } } } }, "4XX": { "description": "Create a tag response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access tags" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.tags", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/access/tags/{tag_name}": { "delete": { "operationId": "access-tags-delete-a-tag", "summary": "Delete a tag", "description": "Delete a tag", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "tag_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_name-13" } } ], "responses": { "202": { "description": "Delete a tag response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_name_response" } } } }, "4XX": { "description": "Delete a tag response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access tags" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.tags", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "access-tags-get-a-tag", "summary": "Get a tag", "description": "Get a tag", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "tag_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_name-13" } } ], "responses": { "200": { "description": "Get a tag response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-14" } } } }, "4XX": { "description": "Get a tag response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access tags" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.tags", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "access-tags-update-a-tag", "summary": "Update a tag", "description": "Update a tag", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "tag_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_name-13" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_tag_without_app_count" } } } }, "responses": { "200": { "description": "Update a tag response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-14" } } } }, "4XX": { "description": "Update a tag response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Access tags" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.tags", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/access/users": { "get": { "operationId": "zero-trust-users-get-users", "summary": "Get users", "description": "Gets a list of users for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "name", "in": "query", "schema": { "description": "The name of the user.", "type": "string" } }, { "name": "email", "in": "query", "schema": { "description": "The email of the user.", "type": "string" } }, { "name": "search", "in": "query", "schema": { "description": "Search for users by other listed query parameters.", "type": "string" } }, { "$ref": "#/components/parameters/access_page" }, { "$ref": "#/components/parameters/access_per_page" } ], "responses": { "200": { "description": "Get users response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-24" } } } }, "4XX": { "description": "Get users response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust users" ], "x-api-token-group": [ "Access: Audit Logs Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.users", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "zero-trust-users-create-user", "summary": "Create a user", "description": "Creates a new user.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/access_email-2" }, "name": { "$ref": "#/components/schemas/access_name-10" } }, "required": [ "email" ] } } } }, "responses": { "201": { "description": "Create user response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_user_response" } } } }, "4XX": { "description": "Create user response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust users" ], "x-api-token-group": null, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.users", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/access/users/{user_id}": { "delete": { "operationId": "zero-trust-users-delete-user", "summary": "Delete a user", "description": "Deletes a specific user for an account. This will also revoke any active seats and tokens for the user.", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "202": { "description": "Delete user response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_delete_user_response" } } } }, "4XX": { "description": "Delete user response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust users" ], "x-api-token-group": null, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.users", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "zero-trust-users-get-user", "summary": "Get a user", "description": "Gets a specific user for an account.", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get user response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_user_response" } } } }, "4XX": { "description": "Get user response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust users" ], "x-api-token-group": [ "Access: Audit Logs Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.users", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "zero-trust-users-update-user", "summary": "Update a user", "description": "Updates a specific user's name for an account. Requires the user's current email as confirmation (email cannot be changed).", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/access_email-2" }, "name": { "$ref": "#/components/schemas/access_name-10" } }, "required": [ "name", "email" ] } } } }, "responses": { "200": { "description": "Update user response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_user_response" } } } }, "4XX": { "description": "Update user response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust users" ], "x-api-token-group": [ "Zero Trust: Seats Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.users", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/access/users/{user_id}/active_sessions": { "get": { "operationId": "zero-trust-users-get-active-sessions", "summary": "Get active sessions", "description": "Get active sessions for a single user.", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get active sessions response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_active_sessions_response" } } } }, "4XX": { "description": "Get active sessions response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust users" ], "x-api-token-group": [ "Access: Audit Logs Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.users.active-sessions", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/access/users/{user_id}/active_sessions/{nonce}": { "get": { "operationId": "zero-trust-users-get-active-session", "summary": "Get single active session", "description": "Get an active session for a single user.", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "nonce", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_nonce" } } ], "responses": { "200": { "description": "Get active session response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_active_session_response" } } } }, "4XX": { "description": "Get active session response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust users" ], "x-api-token-group": [ "Access: Audit Logs Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.users.active-sessions", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/access/users/{user_id}/failed_logins": { "get": { "operationId": "zero-trust-users-get-failed-logins", "summary": "Get failed logins", "description": "Get all failed login attempts for a single user.", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get failed logins response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_failed_login_response" } } } }, "4XX": { "description": "Get failed logins response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust users" ], "x-api-token-group": [ "Access: Audit Logs Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.users.failed-logins", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/access/users/{user_id}/last_seen_identity": { "get": { "operationId": "zero-trust-users-get-last-seen-identity", "summary": "Get last seen identity", "description": "Get last seen identity for a single user.", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get active session response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_last_seen_identity_response" } } } }, "4XX": { "description": "Get active session response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust users" ], "x-api-token-group": [ "Access: Audit Logs Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.access.users.last-seen-identity", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/access/users/{user_id}/mfa_authenticators/{authenticator_id}": { "delete": { "operationId": "zero-trust-users-delete-mfa-authenticator", "summary": "Delete a user's MFA device", "description": "Deletes a specific MFA device, including a PIV key or FIDO2 key enrollment, for a user. This action is only available if MFA is turned on for the organization. Successful deletion revokes the enrollment and returns a null result.", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } }, { "name": "authenticator_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_authenticator_id" } } ], "responses": { "200": { "description": "Delete authenticator response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_delete_authenticator_response" } } } }, "4XX": { "description": "Delete authenticator response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zero Trust users" ], "x-api-token-group": null, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.users.mfa.authenticators", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/address_maps": { "get": { "operationId": "ip-address-management-address-maps-list-address-maps", "summary": "List Address Maps", "description": "List all address maps owned by the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "List Address Maps response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_response_collection-3" } } } }, "4XX": { "description": "List Address Maps response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_response_collection-3" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Address Maps" ], "x-api-token-group": [ "Address Maps Write", "Address Maps Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.address-maps", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "ip-address-management-address-maps-create-address-map", "summary": "Create Address Map", "description": "Create a new address map under the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/addressing_description-2" }, "enabled": { "$ref": "#/components/schemas/addressing_enabled" }, "ips": { "type": "array", "items": { "$ref": "#/components/schemas/addressing_ip_address" }, "example": [ "192.0.2.1" ] }, "memberships": { "$ref": "#/components/schemas/addressing_membership_requests" } } } } } }, "responses": { "200": { "description": "Create Address Map response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_full_response" } } } }, "4XX": { "description": "Create Address Map response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_full_response" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Address Maps" ], "x-api-token-group": [ "Address Maps Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.address-maps", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/address_maps/{address_map_id}": { "delete": { "operationId": "ip-address-management-address-maps-delete-address-map", "summary": "Delete Address Map", "description": "Delete a particular address map owned by the account. An Address Map must be disabled before it can be deleted.", "parameters": [ { "name": "address_map_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_address_map_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "Delete Address Map response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-collection" } } } }, "4XX": { "description": "Delete Address Map response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-collection" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Address Maps" ], "x-api-token-group": [ "Address Maps Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.address-maps", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "ip-address-management-address-maps-address-map-details", "summary": "Address Map Details", "description": "Show a particular address map owned by the account.", "parameters": [ { "name": "address_map_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_address_map_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "Address Map Details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_full_response" } } } }, "4XX": { "description": "Address Map Details response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_full_response" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Address Maps" ], "x-api-token-group": [ "Address Maps Write", "Address Maps Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.address-maps", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "ip-address-management-address-maps-update-address-map", "summary": "Update Address Map", "description": "Modify properties of an address map owned by the account.", "parameters": [ { "name": "address_map_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_address_map_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "default_sni": { "$ref": "#/components/schemas/addressing_default_sni" }, "description": { "$ref": "#/components/schemas/addressing_description-2" }, "enabled": { "$ref": "#/components/schemas/addressing_enabled" } } } } } }, "responses": { "200": { "description": "Update Address Map response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_single_response-3" } } } }, "4XX": { "description": "Update Address Map response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_single_response-3" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Address Maps" ], "x-api-token-group": [ "Address Maps Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.address-maps", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/address_maps/{address_map_id}/accounts/{member_account_id}": { "delete": { "operationId": "ip-address-management-address-maps-remove-an-account-membership-from-an-address-map", "summary": "Remove an account membership from an Address Map", "description": "Remove an account as a member of a particular address map.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } }, { "name": "address_map_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_address_map_identifier" } }, { "name": "member_account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "Remove an account membership from an Address Map response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-collection" } } } }, "4XX": { "description": "Remove an account membership from an Address Map response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-collection" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Address Maps" ], "x-api-token-group": [ "Address Maps Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.address-maps.accounts", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "put": { "operationId": "ip-address-management-address-maps-add-an-account-membership-to-an-address-map", "summary": "Add an account membership to an Address Map", "description": "Add an account as a member of a particular address map.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } }, { "name": "address_map_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_address_map_identifier" } }, { "name": "member_account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "Add an account membership to an Address Map response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-collection" } } } }, "4XX": { "description": "Add an account membership to an Address Map response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-collection" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Address Maps" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.address-maps.accounts", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/address_maps/{address_map_id}/ips/{ip_address}": { "delete": { "operationId": "ip-address-management-address-maps-remove-an-ip-from-an-address-map", "summary": "Remove an IP from an Address Map", "description": "Remove an IP from a particular address map.", "parameters": [ { "name": "ip_address", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_ip_address" } }, { "name": "address_map_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_address_map_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "Remove an IP from an Address Map response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-collection" } } } }, "4XX": { "description": "Remove an IP from an Address Map response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-collection" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Address Maps" ], "x-api-token-group": [ "Address Maps Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.address-maps.ips", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "put": { "operationId": "ip-address-management-address-maps-add-an-ip-to-an-address-map", "summary": "Add an IP to an Address Map", "description": "Add an IP from a prefix owned by the account to a particular address map.", "parameters": [ { "name": "ip_address", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_ip_address" } }, { "name": "address_map_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_address_map_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "Add an IP to an Address Map response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-collection" } } } }, "4XX": { "description": "Add an IP to an Address Map response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-collection" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Address Maps" ], "x-api-token-group": [ "Address Maps Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.address-maps.ips", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/address_maps/{address_map_id}/zones/{zone_id}": { "delete": { "operationId": "ip-address-management-address-maps-remove-a-zone-membership-from-an-address-map", "summary": "Remove a zone membership from an Address Map", "description": "Remove a zone as a member of a particular address map.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_zone_identifier" } }, { "name": "address_map_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_address_map_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "Remove a zone membership from an Address Map response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-collection" } } } }, "4XX": { "description": "Remove a zone membership from an Address Map response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-collection" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Address Maps" ], "x-api-token-group": [ "Address Maps Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.address-maps.zones", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "put": { "operationId": "ip-address-management-address-maps-add-a-zone-membership-to-an-address-map", "summary": "Add a zone membership to an Address Map", "description": "Add a zone as a member of a particular address map.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_zone_identifier" } }, { "name": "address_map_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_address_map_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "Add a zone membership to an Address Map response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-collection" } } } }, "4XX": { "description": "Add a zone membership to an Address Map response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-collection" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Address Maps" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.address-maps.zones", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/leases": { "get": { "operationId": "ip-address-management-list-leases", "summary": "List Leases", "description": "List all leases owned by the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier-2" } } ], "responses": { "200": { "description": "List Leases response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_response_collection-4" } } } }, "4XX": { "description": "List Leases response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_response_collection-4" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Leases" ], "x-api-token-group": null, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.leases", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/loa_documents": { "post": { "operationId": "ip-address-management-prefixes-upload-loa-document", "summary": "Upload LOA Document", "description": "Submit LOA document (pdf format) under the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "loa_document": { "description": "LOA document to upload.", "type": "string", "example": "@document.pdf" } }, "required": [ "loa_document" ] } } } }, "responses": { "201": { "description": "Upload LOA Document response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_loa_upload_response" } } } }, "4XX": { "description": "Upload LOA Document response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_loa_upload_response" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Prefixes" ], "x-api-token-group": [ "Magic Transit Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.loa-documents", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/loa_documents/{loa_document_id}/download": { "get": { "operationId": "ip-address-management-prefixes-download-loa-document", "summary": "Download LOA Document", "description": "Download specified LOA document under the account.", "parameters": [ { "name": "loa_document_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_loa_document_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "Download LOA Document response", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "4XX": { "description": "Download LOA Document response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Prefixes" ], "x-api-token-group": [ "Magic Transit Read", "Magic Transit Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.loa-documents", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/prefixes": { "get": { "operationId": "ip-address-management-prefixes-list-prefixes", "summary": "List Prefixes", "description": "List all prefixes owned by the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "List Prefixes response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_response_collection" } } } }, "4XX": { "description": "List Prefixes response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_response_collection" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Prefixes" ], "x-api-token-group": [ "Magic Transit Read", "Magic Transit Write", "IP Prefixes: Write", "IP Prefixes: Read", "IP Prefixes: BGP On Demand Write", "IP Prefixes: BGP On Demand Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "ip-address-management-prefixes-add-prefix", "summary": "Add Prefix", "description": "Add a new prefix under the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asn": { "$ref": "#/components/schemas/addressing_asn" }, "cidr": { "$ref": "#/components/schemas/addressing_cidr" }, "delegate_loa_creation": { "$ref": "#/components/schemas/addressing_delegate_loa_creation" }, "description": { "$ref": "#/components/schemas/addressing_description" }, "loa_document_id": { "$ref": "#/components/schemas/addressing_loa_document_identifier" } }, "required": [ "cidr", "asn" ] } } } }, "responses": { "201": { "description": "Add Prefix response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_single_response" } } } }, "4XX": { "description": "Add Prefix response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_single_response" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Prefixes" ], "x-api-token-group": null, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/prefixes/{prefix_id}": { "delete": { "operationId": "ip-address-management-prefixes-delete-prefix", "summary": "Delete Prefix", "description": "Delete an unapproved prefix owned by the account.", "parameters": [ { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "Delete Prefix response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-single" } } } }, "4XX": { "description": "Delete Prefix response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-collection" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Prefixes" ], "x-api-token-group": [ "Magic Transit Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "ip-address-management-prefixes-prefix-details", "summary": "Prefix Details", "description": "List a particular prefix owned by the account.", "parameters": [ { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "Prefix Details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_single_response" } } } }, "4XX": { "description": "Prefix Details response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_single_response" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Prefixes" ], "x-api-token-group": [ "Magic Transit Read", "Magic Transit Write", "IP Prefixes: Write", "IP Prefixes: Read", "IP Prefixes: BGP On Demand Write", "IP Prefixes: BGP On Demand Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "ip-address-management-prefixes-update-prefix-description", "summary": "Update Prefix Description", "description": "Modify the description for a prefix owned by the account.", "parameters": [ { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/addressing_description" } }, "required": [ "description" ] } } } }, "responses": { "200": { "description": "Update Prefix Description response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_single_response" } } } }, "4XX": { "description": "Update Prefix Description response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_single_response" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Prefixes" ], "x-api-token-group": [ "Magic Transit Write", "IP Prefixes: Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/prefixes/{prefix_id}/bgp/prefixes": { "get": { "operationId": "ip-address-management-prefixes-list-bgp-prefixes", "summary": "List BGP Prefixes", "description": "List all BGP Prefixes within the specified IP Prefix. BGP Prefixes are used to control which specific subnets are advertised to the Internet. It is possible to advertise subnets more specific than an IP Prefix by creating more specific BGP Prefixes.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } }, { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } } ], "responses": { "200": { "description": "List BGP Prefixes response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_response_collection_bgp" } } } }, "4XX": { "description": "List BGP Prefixes response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_response_collection_bgp" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management BGP Prefixes" ], "x-api-token-group": [ "Magic Transit Read", "Magic Transit Write", "IP Prefixes: Write", "IP Prefixes: Read", "IP Prefixes: BGP On Demand Write", "IP Prefixes: BGP On Demand Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes.bgp-prefixes", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "ip-address-management-prefixes-create-bgp-prefix", "summary": "Create BGP Prefix", "description": "Create a BGP prefix, controlling the BGP advertisement status of a specific subnet. When created, BGP prefixes are initially withdrawn, and can be advertised with the Update BGP Prefix API.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } }, { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_bgp_prefix_create" } } } }, "responses": { "200": { "description": "Create BGP Prefix response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_single_response_bgp" } } } }, "4XX": { "description": "Create BGP Prefix response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_single_response_bgp" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management BGP Prefixes" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes.bgp-prefixes", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/prefixes/{prefix_id}/bgp/prefixes/{bgp_prefix_id}": { "delete": { "operationId": "ip-address-management-prefixes-delete-bgp-prefix", "summary": "Delete BGP Prefix", "description": "Delete a BGP Prefix associated with the specified IP Prefix. A BGP Prefix must be withdrawn before it can be deleted.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } }, { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } }, { "name": "bgp_prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_bgp_prefix_identifier" } } ], "responses": { "200": { "description": "Delete BGP Prefix response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-common" } } } }, "4XX": { "description": "Delete BGP Prefix response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management BGP Prefixes" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes.bgp-prefixes", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "ip-address-management-prefixes-fetch-bgp-prefix", "summary": "Fetch BGP Prefix", "description": "Retrieve a single BGP Prefix according to its identifier", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } }, { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } }, { "name": "bgp_prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_bgp_prefix_identifier" } } ], "responses": { "200": { "description": "Fetch BGP Prefix response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_single_response_bgp" } } } }, "4XX": { "description": "Fetch BGP Prefix response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_single_response_bgp" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management BGP Prefixes" ], "x-api-token-group": [ "Magic Transit Read", "Magic Transit Write", "IP Prefixes: Write", "IP Prefixes: Read", "IP Prefixes: BGP On Demand Write", "IP Prefixes: BGP On Demand Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes.bgp-prefixes", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "ip-address-management-prefixes-update-bgp-prefix", "summary": "Update BGP Prefix", "description": "Update the properties of a BGP Prefix, such as the on demand advertisement status (advertised or withdrawn).", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } }, { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } }, { "name": "bgp_prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_bgp_prefix_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_bgp_prefix_update_advertisement" } } } }, "responses": { "200": { "description": "Update BGP Prefix response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_single_response_bgp" } } } }, "4XX": { "description": "Update BGP Prefix response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_single_response_bgp" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management BGP Prefixes" ], "x-api-token-group": [ "Magic Transit Write", "IP Prefixes: Write", "IP Prefixes: BGP On Demand Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes.bgp-prefixes", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/prefixes/{prefix_id}/bgp/status": { "get": { "operationId": "ip-address-management-dynamic-advertisement-get-advertisement-status", "summary": "Get Advertisement Status", "description": "View the current advertisement state for a prefix.\n\n**Deprecated:** Prefer the BGP Prefixes endpoints, which additionally allow for advertising and withdrawing \nsubnets of an IP prefix.\n", "parameters": [ { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "Get Advertisement Status response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_advertised_response" } } } }, "4XX": { "description": "Get Advertisement Status response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_advertised_response" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Dynamic Advertisement" ], "x-api-token-group": [ "Magic Transit Read", "Magic Transit Write", "IP Prefixes: Write", "IP Prefixes: Read", "IP Prefixes: BGP On Demand Write", "IP Prefixes: BGP On Demand Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes.advertisement-status", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "ip-address-management-dynamic-advertisement-update-prefix-dynamic-advertisement-status", "summary": "Update Prefix Dynamic Advertisement Status", "description": "Advertise or withdraw the BGP route for a prefix.\n\n**Deprecated:** Prefer the BGP Prefixes endpoints, which additionally allow for advertising and withdrawing \nsubnets of an IP prefix.\n", "parameters": [ { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertised": { "$ref": "#/components/schemas/addressing_advertised-3" } }, "required": [ "advertised" ] } } } }, "responses": { "200": { "description": "Update Prefix Dynamic Advertisement Status response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_advertised_response" } } } }, "4XX": { "description": "Update Prefix Dynamic Advertisement Status response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_advertised_response" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Dynamic Advertisement" ], "x-api-token-group": [ "Magic Transit Write", "IP Prefixes: Write", "IP Prefixes: BGP On Demand Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes.advertisement-status", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/prefixes/{prefix_id}/bindings": { "get": { "operationId": "ip-address-management-service-bindings-list-service-bindings", "summary": "List Service Bindings", "description": "List the Cloudflare services this prefix is currently bound to. Traffic sent to an address within an IP prefix will be routed to the Cloudflare service of the most-specific Service Binding matching the address.\n**Example:** binding `192.0.2.0/24` to Cloudflare Magic Transit and `192.0.2.1/32` to the Cloudflare CDN would route traffic for `192.0.2.1` to the CDN, and traffic for all other IPs in the prefix to Cloudflare Magic Transit.\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } }, { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } } ], "responses": { "200": { "description": "Service Bindings attached to the Prefix", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/addressing_service_binding" } } }, "type": "object" } ] } } } }, "4XX": { "description": "List Service Bindings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Service Bindings" ], "x-api-token-group": [ "IP Prefixes: Write", "IP Prefixes: Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes.service-bindings", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "ip-address-management-service-bindings-create-service-binding", "summary": "Create Service Binding", "description": "Creates a new Service Binding, routing traffic to IPs within the given CIDR to a service running on Cloudflare's network.\n**NOTE:** The first Service Binding created for an IP Prefix must exactly match the IP Prefix's CIDR. Subsequent Service Bindings may be created with a more-specific CIDR. Refer to the [Service Bindings Documentation](https://developers.cloudflare.com/byoip/service-bindings/) for compatibility details.\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } }, { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_create_binding_request" } } } }, "responses": { "201": { "description": "The created Service Binding", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/addressing_service_binding" } }, "type": "object" } ] } } } }, "4XX": { "description": "Create Service Binding response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Service Bindings" ], "x-api-token-group": [ "IP Prefixes: Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes.service-bindings", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/prefixes/{prefix_id}/bindings/{binding_id}": { "delete": { "operationId": "ip-address-management-service-bindings-delete-service-binding", "summary": "Delete Service Binding", "description": "Delete a Service Binding", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } }, { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } }, { "name": "binding_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_service_binding_identifier" } } ], "responses": { "200": { "description": "Service Binding deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-common" } } } }, "4XX": { "description": "Delete Service Binding response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Service Bindings" ], "x-api-token-group": [ "IP Prefixes: Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes.service-bindings", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "ip-address-management-service-bindings-get-service-binding", "summary": "Get Service Binding", "description": "Fetch a single Service Binding", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } }, { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } }, { "name": "binding_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_service_binding_identifier" } } ], "responses": { "200": { "description": "The Service Binding with the requested ID", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/addressing_service_binding" } }, "type": "object" } ] } } } }, "4XX": { "description": "Get Service Binding response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Service Bindings" ], "x-api-token-group": [ "IP Prefixes: Write", "IP Prefixes: Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes.service-bindings", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/prefixes/{prefix_id}/delegations": { "get": { "operationId": "ip-address-management-prefix-delegation-list-prefix-delegations", "summary": "List Prefix Delegations", "description": "List all delegations for a given account IP prefix.", "parameters": [ { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "List Prefix Delegations response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_response_collection-2" } } } }, "4XX": { "description": "List Prefix Delegations response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_response_collection-2" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Prefix Delegation" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes.delegations", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "ip-address-management-prefix-delegation-create-prefix-delegation", "summary": "Create Prefix Delegation", "description": "Create a new account delegation for a given IP prefix.", "parameters": [ { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cidr": { "$ref": "#/components/schemas/addressing_cidr" }, "delegated_account_id": { "$ref": "#/components/schemas/addressing_delegated_account_identifier" } }, "required": [ "cidr", "delegated_account_id" ] } } } }, "responses": { "200": { "description": "Create Prefix Delegation response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_single_response-2" } } } }, "4XX": { "description": "Create Prefix Delegation response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_single_response-2" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Prefix Delegation" ], "x-api-token-group": [ "IP Prefixes: Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes.delegations", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/prefixes/{prefix_id}/delegations/{delegation_id}": { "delete": { "operationId": "ip-address-management-prefix-delegation-delete-prefix-delegation", "summary": "Delete Prefix Delegation", "description": "Delete an account delegation for a given IP prefix.", "parameters": [ { "name": "delegation_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_delegation_identifier" } }, { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "Delete Prefix Delegation response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_id_response" } } } }, "4XX": { "description": "Delete Prefix Delegation response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_id_response" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Prefix Delegation" ], "x-api-token-group": [ "IP Prefixes: Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes.delegations", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/prefixes/{prefix_id}/validate": { "post": { "operationId": "ip-address-management-prefixes-validate-prefix", "summary": "Validate Prefix", "description": "Triggers a new prefix validation. The checks are run asynchronously and include IRR, RPKI, and prefix ownership.", "parameters": [ { "name": "prefix_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_prefix_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "202": { "description": "Validate Prefix response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_single_response" } } } }, "4XX": { "description": "Validate Prefix response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_single_response" }, { "$ref": "#/components/schemas/addressing_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Prefixes" ], "x-api-token-group": [ "Magic Transit Write", "IP Prefixes: Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.prefixes.validate", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/regional_hostnames/regions": { "get": { "operationId": "dls-account-regional-hostnames-list-regions", "summary": "List Regions", "description": "List all Regional Services regions available for use by this account.", "parameters": [ { "$ref": "#/components/parameters/dls_account_id" } ], "responses": { "200": { "description": "List regions response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dls_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "properties": { "key": { "$ref": "#/components/schemas/dls_region_key" }, "label": { "description": "Human-readable text label for the region", "type": "string", "example": "Canada" } }, "type": "object" } } } } ] } } } }, "4XX": { "description": "Failure to list regions", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dls_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "DLS Regional Services" ], "x-api-token-group": [ "DNS Read", "DNS Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.regional_hostnames.regions", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/addressing/services": { "get": { "operationId": "ip-address-management-service-bindings-list-services", "summary": "List Services", "description": "Bring-Your-Own IP (BYOIP) prefixes onboarded to Cloudflare must be bound to a service running on the Cloudflare network to enable a Cloudflare product on the IP addresses. This endpoint can be used as a reference of available services on the Cloudflare network, and their service IDs.\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/addressing_account_identifier" } } ], "responses": { "200": { "description": "Service names and IDs", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "properties": { "id": { "$ref": "#/components/schemas/addressing_service_identifier" }, "name": { "$ref": "#/components/schemas/addressing_service_name" } }, "type": "object" } } }, "type": "object" } ] } } } }, "4XX": { "description": "List Services response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressing_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "IP Address Management Service Bindings" ], "x-api-token-group": [ "IP Prefixes: Write", "IP Prefixes: Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.services", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/agent-memory/namespaces": { "get": { "operationId": "agent-memory-namespace-list", "summary": "List namespaces", "description": "Lists all namespaces for the given account. Results are paginated.", "parameters": [ { "name": "per_page", "in": "query", "schema": { "description": "Number of results per page.", "type": "integer", "example": 20, "maximum": 1000, "minimum": 1 } }, { "name": "order", "in": "query", "schema": { "description": "Field to order the results by.", "type": "string", "example": "id", "enum": [ "id", "name" ] } }, { "name": "direction", "in": "query", "schema": { "description": "Direction to sort the results in.", "type": "string", "example": "asc", "enum": [ "asc", "desc" ] } }, { "name": "cursor", "in": "query", "schema": { "description": "Pagination cursor returned by a previous list response.", "type": "string" } } ], "responses": { "200": { "description": "A List of namespaces.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Always empty for a successful response.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "type": "array", "items": { "properties": { "created_at": { "description": "Time the namespace was created.", "type": "string", "format": "date-time", "example": "2025-09-21T14:30:00Z" }, "id": { "description": "Unique identifier of the namespace.", "type": "string", "example": "01JSGCEXAMP1E0000000000000" }, "name": { "description": "Namespace name.", "type": "string", "example": "support-agent" }, "updated_at": { "description": "Time the namespace was last updated.", "type": "string", "format": "date-time", "example": "2025-09-21T14:30:00Z" } }, "required": [ "id", "name", "created_at", "updated_at" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "description": "Number of results returned in this page.", "type": "integer", "example": 1 }, "cursor": { "description": "Opaque cursor for the next page; omitted on the last page.", "type": "string", "example": "01JSGCEXAMP1E0000000000000" }, "per_page": { "description": "Page size used for this query.", "type": "integer", "example": 20 } } }, "success": { "description": "Always true for a successful response.", "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "One or more errors describing what went wrong.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [ { "code": 1003, "message": "namespace not found" } ] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "description": "Always null for an error response.", "type": "object", "nullable": true }, "success": { "description": "Always false for an error response.", "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Namespaces" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "agent-memory", "x-fern-sdk-method-name": "list-namespaces" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID.", "required": true, "schema": { "type": "string", "minLength": 1, "pattern": "^\\d+$" } } ], "post": { "operationId": "agent-memory-namespace-create", "summary": "Create a namespace", "description": "Creates a new memory namespace owned by the account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Namespace name.", "type": "string", "example": "support-agent", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Namespace created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Always empty for a successful response.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "type": "object", "properties": { "created_at": { "description": "Time the namespace was created.", "type": "string", "format": "date-time", "example": "2025-09-21T14:30:00Z" }, "id": { "description": "Unique identifier of the namespace.", "type": "string", "example": "01JSGCEXAMP1E0000000000000" }, "name": { "description": "Namespace name.", "type": "string", "example": "support-agent" }, "updated_at": { "description": "Time the namespace was last updated.", "type": "string", "format": "date-time", "example": "2025-09-21T14:30:00Z" } }, "required": [ "id", "name", "created_at", "updated_at" ] }, "success": { "description": "Always true for a successful response.", "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "One or more errors describing what went wrong.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [ { "code": 1003, "message": "namespace not found" } ] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "description": "Always null for an error response.", "type": "object", "nullable": true }, "success": { "description": "Always false for an error response.", "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Namespaces" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "agent-memory", "x-fern-sdk-method-name": "create-namespace" } }, "/accounts/{account_id}/agent-memory/namespaces/{namespace_name}": { "delete": { "operationId": "agent-memory-namespace-delete", "summary": "Delete a namespace", "description": "Deletes a namespace.", "parameters": [ { "name": "namespace_name", "in": "path", "required": true, "schema": { "description": "Namespace name.", "type": "string", "example": "support-agent", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } } ], "responses": { "200": { "description": "Namespace deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Always empty for a successful response.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "type": "object", "nullable": true }, "success": { "description": "Always true for a successful response.", "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "One or more errors describing what went wrong.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [ { "code": 1003, "message": "namespace not found" } ] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "description": "Always null for an error response.", "type": "object", "nullable": true }, "success": { "description": "Always false for an error response.", "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Namespaces" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "agent-memory", "x-fern-sdk-method-name": "delete-namespace", "x-forge-require-confirmation": "This operation deletes the namespace along with all memory profiles, memories, and sessions it contains." }, "get": { "operationId": "agent-memory-namespace-get", "summary": "Get a namespace", "description": "Gets a namespace by name.", "parameters": [ { "name": "namespace_name", "in": "path", "required": true, "schema": { "description": "Namespace name.", "type": "string", "example": "support-agent", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } } ], "responses": { "200": { "description": "The requested namespace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Always empty for a successful response.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "type": "object", "properties": { "created_at": { "description": "Time the namespace was created.", "type": "string", "format": "date-time", "example": "2025-09-21T14:30:00Z" }, "id": { "description": "Unique identifier of the namespace.", "type": "string", "example": "01JSGCEXAMP1E0000000000000" }, "name": { "description": "Namespace name.", "type": "string", "example": "support-agent" }, "updated_at": { "description": "Time the namespace was last updated.", "type": "string", "format": "date-time", "example": "2025-09-21T14:30:00Z" } }, "required": [ "id", "name", "created_at", "updated_at" ] }, "success": { "description": "Always true for a successful response.", "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "One or more errors describing what went wrong.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [ { "code": 1003, "message": "namespace not found" } ] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "description": "Always null for an error response.", "type": "object", "nullable": true }, "success": { "description": "Always false for an error response.", "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Namespaces" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "agent-memory", "x-fern-sdk-method-name": "get-namespace" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID.", "required": true, "schema": { "type": "string", "minLength": 1, "pattern": "^\\d+$" } } ] }, "/accounts/{account_id}/agent-memory/namespaces/{namespace_name}/profiles": { "get": { "operationId": "agent-memory-profile-list", "summary": "List profiles", "description": "Lists the profiles of a namespace, ordered by name. A profile appears once it has been used.", "parameters": [ { "name": "namespace_name", "in": "path", "required": true, "schema": { "description": "Namespace name.", "type": "string", "example": "support-agent", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of results per page.", "type": "integer", "example": 20, "maximum": 500, "minimum": 1 } }, { "name": "cursor", "in": "query", "schema": { "description": "Opaque continuation cursor returned by a previous list response.", "type": "string", "example": "eyJ2IjoxLCJuIjoibXktcHJvZmlsZSJ9", "maxLength": 256, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+$" } } ], "responses": { "200": { "description": "A page of profiles.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Always empty for a successful response.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "type": "array", "items": { "properties": { "createdAt": { "description": "Time the profile was first recorded in the namespace index.", "type": "string", "format": "date-time", "example": "2025-09-21T14:30:00Z" }, "name": { "description": "Profile name.", "type": "string", "example": "my-profile" } }, "required": [ "name", "createdAt" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "description": "Number of results returned in this page.", "type": "integer", "example": 1 }, "cursor": { "description": "Opaque cursor for the next page; omitted on the last page.", "type": "string", "example": "eyJ2IjoxLCJuIjoibXktcHJvZmlsZSJ9" }, "per_page": { "description": "Page size used for this query.", "type": "integer", "example": 20 } } }, "success": { "description": "Always true for a successful response.", "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "One or more errors describing what went wrong.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [ { "code": 1003, "message": "namespace not found" } ] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "description": "Always null for an error response.", "type": "object", "nullable": true }, "success": { "description": "Always false for an error response.", "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Memory" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "agent-memory", "x-fern-sdk-method-name": "list-profiles" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID.", "required": true, "schema": { "type": "string", "minLength": 1, "pattern": "^\\d+$" } } ] }, "/accounts/{account_id}/agent-memory/namespaces/{namespace_name}/profiles/{profile_name}": { "delete": { "operationId": "agent-memory-profile-delete", "summary": "Delete a profile", "description": "Marks a profile for deletion.", "parameters": [ { "name": "namespace_name", "in": "path", "required": true, "schema": { "description": "Namespace name.", "type": "string", "example": "support-agent", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } }, { "name": "profile_name", "in": "path", "required": true, "schema": { "description": "Profile name.", "type": "string", "example": "my-profile", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } } ], "responses": { "200": { "description": "Profile deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Always empty for a successful response.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "type": "object", "nullable": true }, "success": { "description": "Always true for a successful response.", "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "One or more errors describing what went wrong.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [ { "code": 1003, "message": "namespace not found" } ] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "description": "Always null for an error response.", "type": "object", "nullable": true }, "success": { "description": "Always false for an error response.", "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Memory" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "agent-memory", "x-fern-sdk-method-name": "delete-profile", "x-forge-require-confirmation": "This operation deletes the profile along with all of its memories and messages." }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID.", "required": true, "schema": { "type": "string", "minLength": 1, "pattern": "^\\d+$" } } ] }, "/accounts/{account_id}/agent-memory/namespaces/{namespace_name}/profiles/{profile_name}/ingest": { "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID.", "required": true, "schema": { "type": "string", "minLength": 1, "pattern": "^\\d+$" } } ], "post": { "operationId": "agent-memory-ingest", "summary": "Ingest messages", "description": "Processes a conversation and extracts structured memories from it. Agent Memory identifies facts, events, instructions, and tasks automatically.", "parameters": [ { "name": "namespace_name", "in": "path", "required": true, "schema": { "description": "Namespace name.", "type": "string", "example": "support-agent", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } }, { "name": "profile_name", "in": "path", "required": true, "schema": { "description": "Profile name.", "type": "string", "example": "my-profile", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "description": "Conversation messages to extract memories from.", "type": "array", "items": { "properties": { "content": { "description": "Text content of the message.", "example": "I really prefer dark mode in the dashboard.", "minLength": 1, "type": "string" }, "role": { "description": "Author role of the message.", "type": "string", "example": "user", "enum": [ "system", "user", "assistant" ] }, "timestamp": { "description": "Message timestamp.", "type": "string", "example": "2025-09-21T14:30:00Z" } }, "required": [ "role", "content" ], "type": "object" }, "minItems": 1 }, "sessionId": { "description": "Session identifier.", "type": "string", "example": "chat-session-42", "nullable": true } }, "required": [ "messages" ] } } } }, "responses": { "200": { "description": "Conversation ingested.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Always empty for a successful response.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "type": "object", "nullable": true }, "success": { "description": "Always true for a successful response.", "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "One or more errors describing what went wrong.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [ { "code": 1003, "message": "namespace not found" } ] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "description": "Always null for an error response.", "type": "object", "nullable": true }, "success": { "description": "Always false for an error response.", "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Memory" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "agent-memory", "x-fern-sdk-method-name": "ingest" } }, "/accounts/{account_id}/agent-memory/namespaces/{namespace_name}/profiles/{profile_name}/memories": { "get": { "operationId": "agent-memory-memory-list", "summary": "List memories", "description": "List memories stored in a profile.", "parameters": [ { "name": "namespace_name", "in": "path", "required": true, "schema": { "description": "Namespace name.", "type": "string", "example": "support-agent", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } }, { "name": "profile_name", "in": "path", "required": true, "schema": { "description": "Profile name.", "type": "string", "example": "my-profile", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of results per page.", "type": "integer", "example": 20, "maximum": 500, "minimum": 1 } }, { "name": "cursor", "in": "query", "schema": { "description": "Continuation cursor for paginated results.", "type": "string", "example": "01JSGCEXAMP1E0000000000000", "maxLength": 26, "minLength": 26 } }, { "name": "session_id", "in": "query", "schema": { "description": "Session identifier for filtering.", "type": "string", "example": "chat-session-42", "maxLength": 64, "minLength": 1 } }, { "name": "type", "in": "query", "schema": { "description": "Memory type for filtering.", "type": "string", "example": "fact", "enum": [ "fact", "event", "instruction", "task" ] } } ], "responses": { "200": { "description": "A page of memory metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Always empty for a successful response.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "type": "array", "items": { "properties": { "createdAt": { "description": "Time the memory was created.", "type": "string", "format": "date-time", "example": "2025-09-21T14:30:00Z" }, "id": { "description": "Unique identifier of the memory.", "type": "string", "example": "01JSGCEXAMP1E0000000000000" }, "sessionId": { "description": "Identifier of the session this memory is associated with.", "type": "string", "example": "chat-session-42", "nullable": true }, "summary": { "description": "Short, human-readable summary of the memory.", "type": "string", "example": "User prefers dark mode in the dashboard." }, "type": { "description": "Classification of a memory: 'fact', 'event', 'instruction', or 'task'.", "type": "string", "example": "fact", "enum": [ "fact", "event", "instruction", "task" ] }, "updatedAt": { "description": "Time the memory was last updated.", "type": "string", "format": "date-time", "example": "2025-09-21T14:30:00Z" } }, "required": [ "id", "type", "summary", "sessionId", "createdAt", "updatedAt" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "description": "Number of results returned in this page.", "type": "integer", "example": 1 }, "cursor": { "description": "Opaque cursor for the next page; omitted on the last page.", "type": "string", "example": "01JSGCEXAMP1E0000000000000" }, "per_page": { "description": "Page size used for this query.", "type": "integer", "example": 20 } } }, "success": { "description": "Always true for a successful response.", "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "One or more errors describing what went wrong.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [ { "code": 1003, "message": "namespace not found" } ] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "description": "Always null for an error response.", "type": "object", "nullable": true }, "success": { "description": "Always false for an error response.", "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Memory" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "agent-memory", "x-fern-sdk-method-name": "list-memories" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID.", "required": true, "schema": { "type": "string", "minLength": 1, "pattern": "^\\d+$" } } ] }, "/accounts/{account_id}/agent-memory/namespaces/{namespace_name}/profiles/{profile_name}/memories/{memory_id}": { "delete": { "operationId": "agent-memory-memory-delete", "summary": "Delete a memory", "description": "Deletes a memory by ID. Removes the memory and any source messages linked to it. Returns the deleted memory.", "parameters": [ { "name": "namespace_name", "in": "path", "required": true, "schema": { "description": "Namespace name.", "type": "string", "example": "support-agent", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } }, { "name": "profile_name", "in": "path", "required": true, "schema": { "description": "Profile name.", "type": "string", "example": "my-profile", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } }, { "name": "memory_id", "in": "path", "required": true, "schema": { "description": "Memory Identifier.", "type": "string", "example": "01JSGCEXAMP1E0000000000000", "maxLength": 26, "minLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } ], "responses": { "200": { "description": "The deleted memory.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Always empty for a successful response.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "type": "object", "properties": { "content": { "description": "Full memory content extracted from the conversation.", "example": "The user said they prefer dark mode and find the light theme too bright.", "type": "string" }, "createdAt": { "description": "Time the memory was created.", "type": "string", "format": "date-time", "example": "2025-09-21T14:30:00Z" }, "id": { "description": "Unique identifier of the memory.", "type": "string", "example": "01JSGCEXAMP1E0000000000000" }, "sessionId": { "description": "Identifier of the session this memory is associated with.", "type": "string", "example": "chat-session-42", "nullable": true }, "summary": { "description": "Short, human-readable summary of the memory.", "type": "string", "example": "User prefers dark mode in the dashboard." }, "type": { "description": "Classification of a memory: 'fact', 'event', 'instruction', or 'task'.", "type": "string", "example": "fact", "enum": [ "fact", "event", "instruction", "task" ] }, "updatedAt": { "description": "Time the memory was last updated.", "type": "string", "format": "date-time", "example": "2025-09-21T14:30:00Z" } }, "required": [ "id", "type", "summary", "content", "sessionId", "createdAt", "updatedAt" ] }, "success": { "description": "Always true for a successful response.", "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "One or more errors describing what went wrong.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [ { "code": 1003, "message": "namespace not found" } ] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "description": "Always null for an error response.", "type": "object", "nullable": true }, "success": { "description": "Always false for an error response.", "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Memory" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "agent-memory", "x-fern-sdk-method-name": "delete-memory", "x-forge-require-confirmation": "This operation deletes the memory and any source messages linked to it." }, "get": { "operationId": "agent-memory-memory-get", "summary": "Get a memory", "description": "Retrieves a memory by ID.", "parameters": [ { "name": "namespace_name", "in": "path", "required": true, "schema": { "description": "Namespace name.", "type": "string", "example": "support-agent", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } }, { "name": "profile_name", "in": "path", "required": true, "schema": { "description": "Profile name.", "type": "string", "example": "my-profile", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } }, { "name": "memory_id", "in": "path", "required": true, "schema": { "description": "Memory Identifier.", "type": "string", "example": "01JSGCEXAMP1E0000000000000", "maxLength": 26, "minLength": 26, "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } } ], "responses": { "200": { "description": "The requested memory.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Always empty for a successful response.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "type": "object", "properties": { "content": { "description": "Full memory content extracted from the conversation.", "example": "The user said they prefer dark mode and find the light theme too bright.", "type": "string" }, "createdAt": { "description": "Time the memory was created.", "type": "string", "format": "date-time", "example": "2025-09-21T14:30:00Z" }, "id": { "description": "Unique identifier of the memory.", "type": "string", "example": "01JSGCEXAMP1E0000000000000" }, "sessionId": { "description": "Identifier of the session this memory is associated with.", "type": "string", "example": "chat-session-42", "nullable": true }, "summary": { "description": "Short, human-readable summary of the memory.", "type": "string", "example": "User prefers dark mode in the dashboard." }, "type": { "description": "Classification of a memory: 'fact', 'event', 'instruction', or 'task'.", "type": "string", "example": "fact", "enum": [ "fact", "event", "instruction", "task" ] }, "updatedAt": { "description": "Time the memory was last updated.", "type": "string", "format": "date-time", "example": "2025-09-21T14:30:00Z" } }, "required": [ "id", "type", "summary", "content", "sessionId", "createdAt", "updatedAt" ] }, "success": { "description": "Always true for a successful response.", "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "One or more errors describing what went wrong.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [ { "code": 1003, "message": "namespace not found" } ] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "description": "Always null for an error response.", "type": "object", "nullable": true }, "success": { "description": "Always false for an error response.", "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Memory" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "agent-memory", "x-fern-sdk-method-name": "get-memory" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID.", "required": true, "schema": { "type": "string", "minLength": 1, "pattern": "^\\d+$" } } ] }, "/accounts/{account_id}/agent-memory/namespaces/{namespace_name}/profiles/{profile_name}/recall": { "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID.", "required": true, "schema": { "type": "string", "minLength": 1, "pattern": "^\\d+$" } } ], "post": { "operationId": "agent-memory-recall", "summary": "Recall memories", "description": "Retrieves memories relevant to the query and returns a synthesized answer.", "parameters": [ { "name": "namespace_name", "in": "path", "required": true, "schema": { "description": "Namespace name.", "type": "string", "example": "support-agent", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } }, { "name": "profile_name", "in": "path", "required": true, "schema": { "description": "Profile name.", "type": "string", "example": "my-profile", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "description": "Natural-language query to match against stored memories.", "example": "What are my UI preferences?", "minLength": 1, "type": "string" }, "referenceDate": { "description": "Temporal anchor for relative date references in the query.", "type": "string", "example": "2025-09-21T00:00:00Z" }, "responseLength": { "description": "Verbosity of the synthesized answer. Defaults to 'medium'.", "type": "string", "example": "short", "enum": [ "short", "medium", "long" ] }, "thinkingLevel": { "description": "Recall intensity / search depth. Defaults to 'low'.", "type": "string", "example": "medium", "enum": [ "low", "medium", "high" ] } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Recall result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Always empty for a successful response.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "type": "object", "properties": { "answer": { "description": "LLM-synthesized answer to the query. Omitted when synthesis is skipped.", "type": "string", "example": "You prefer dark mode in the dashboard." }, "candidates": { "description": "Matching memories ranked by relevance (most relevant first).", "type": "array", "items": { "properties": { "id": { "description": "Unique identifier of the memory.", "type": "string", "example": "01JSGCEXAMP1E0000000000000" }, "score": { "description": "Relevance score for the query; higher is more relevant.", "type": "number", "example": 0.87 }, "sessionId": { "description": "Session the candidate memory is associated with, or null if not session-scoped.", "type": "string", "example": "chat-session-42", "nullable": true }, "summary": { "description": "Short summary of the candidate memory.", "type": "string", "example": "User prefers dark mode in the dashboard." } }, "required": [ "id", "summary", "sessionId", "score" ], "type": "object" } }, "count": { "description": "Number of matching memories returned in `candidates`.", "type": "number", "example": 1 } }, "required": [ "count", "candidates" ] }, "success": { "description": "Always true for a successful response.", "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "One or more errors describing what went wrong.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [ { "code": 1003, "message": "namespace not found" } ] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "description": "Always null for an error response.", "type": "object", "nullable": true }, "success": { "description": "Always false for an error response.", "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Memory" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "agent-memory", "x-fern-sdk-method-name": "recall" } }, "/accounts/{account_id}/agent-memory/namespaces/{namespace_name}/profiles/{profile_name}/remember": { "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID.", "required": true, "schema": { "type": "string", "minLength": 1, "pattern": "^\\d+$" } } ], "post": { "operationId": "agent-memory-remember", "summary": "Remember a memory", "description": "Stores a single memory explicitly.", "parameters": [ { "name": "namespace_name", "in": "path", "required": true, "schema": { "description": "Namespace name.", "type": "string", "example": "support-agent", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } }, { "name": "profile_name", "in": "path", "required": true, "schema": { "description": "Profile name.", "type": "string", "example": "my-profile", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "description": "Raw memory content to store.", "example": "I prefer dark mode in the dashboard.", "minLength": 1, "type": "string" }, "sessionId": { "description": "Session identifier.", "type": "string", "example": "chat-session-42", "nullable": true } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Memory stored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Always empty for a successful response.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "type": "object", "properties": { "content": { "description": "Full memory content extracted from the conversation.", "example": "The user said they prefer dark mode and find the light theme too bright.", "type": "string" }, "createdAt": { "description": "Time the memory was created.", "type": "string", "format": "date-time", "example": "2025-09-21T14:30:00Z" }, "id": { "description": "Unique identifier of the memory.", "type": "string", "example": "01JSGCEXAMP1E0000000000000" }, "sessionId": { "description": "Identifier of the session this memory is associated with.", "type": "string", "example": "chat-session-42", "nullable": true }, "summary": { "description": "Short, human-readable summary of the memory.", "type": "string", "example": "User prefers dark mode in the dashboard." }, "type": { "description": "Classification of a memory: 'fact', 'event', 'instruction', or 'task'.", "type": "string", "example": "fact", "enum": [ "fact", "event", "instruction", "task" ] }, "updatedAt": { "description": "Time the memory was last updated.", "type": "string", "format": "date-time", "example": "2025-09-21T14:30:00Z" } }, "required": [ "id", "type", "summary", "content", "sessionId", "createdAt", "updatedAt" ] }, "success": { "description": "Always true for a successful response.", "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "One or more errors describing what went wrong.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [ { "code": 1003, "message": "namespace not found" } ] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "description": "Always null for an error response.", "type": "object", "nullable": true }, "success": { "description": "Always false for an error response.", "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Memory" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "agent-memory", "x-fern-sdk-method-name": "remember" } }, "/accounts/{account_id}/agent-memory/namespaces/{namespace_name}/profiles/{profile_name}/sessions/{session_id}": { "delete": { "operationId": "agent-memory-session-delete", "summary": "Delete a session", "description": "Marks all memories and messages in a profile that are tagged with the given session ID for deletion.", "parameters": [ { "name": "namespace_name", "in": "path", "required": true, "schema": { "description": "Namespace name.", "type": "string", "example": "support-agent", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } }, { "name": "profile_name", "in": "path", "required": true, "schema": { "description": "Profile name.", "type": "string", "example": "my-profile", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } }, { "name": "session_id", "in": "path", "description": "Session identifier.", "required": true, "schema": { "description": "Session Identifier.", "type": "string", "example": "chat-session-44", "maxLength": 64, "minLength": 1 } } ], "responses": { "200": { "description": "Session deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Always empty for a successful response.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "type": "object", "nullable": true }, "success": { "description": "Always true for a successful response.", "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "One or more errors describing what went wrong.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [ { "code": 1003, "message": "namespace not found" } ] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "description": "Always null for an error response.", "type": "object", "nullable": true }, "success": { "description": "Always false for an error response.", "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Memory" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "agent-memory", "x-fern-sdk-method-name": "delete-session", "x-forge-require-confirmation": "This operation deletes all memories and messages tagged with this session ID." }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID.", "required": true, "schema": { "type": "string", "minLength": 1, "pattern": "^\\d+$" } } ] }, "/accounts/{account_id}/agent-memory/namespaces/{namespace_name}/profiles/{profile_name}/summary": { "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare Account ID.", "required": true, "schema": { "type": "string", "minLength": 1, "pattern": "^\\d+$" } } ], "post": { "operationId": "agent-memory-summary", "summary": "Get a profile summary", "description": "Generates a paste-ready prompt block summarizing everything stored in a memory profile.", "parameters": [ { "name": "namespace_name", "in": "path", "required": true, "schema": { "description": "Namespace name.", "type": "string", "example": "support-agent", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } }, { "name": "profile_name", "in": "path", "required": true, "schema": { "description": "Profile name.", "type": "string", "example": "my-profile", "maxLength": 100, "minLength": 1, "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "description": "Session identifier.", "type": "string", "example": "chat-session-42", "nullable": true } } } } } }, "responses": { "200": { "description": "Profile summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Always empty for a successful response.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "type": "object", "properties": { "summary": { "description": "Paste-ready prompt block summarizing everything stored in the profile.", "type": "string", "example": "Profile context as of 2 January 2025.\n🔴 (fact) Prefers dark mode\n🟡 (task) Finish onboarding" } }, "required": [ "summary" ] }, "success": { "description": "Always true for a successful response.", "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "One or more errors describing what went wrong.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [ { "code": 1003, "message": "namespace not found" } ] }, "messages": { "description": "Informational, non-error messages, if any.", "type": "array", "items": { "properties": { "code": { "description": "Machine-readable status code.", "type": "number", "example": 1003 }, "documentation_url": { "description": "Link to relevant documentation, when available.", "type": "string" }, "message": { "description": "Human-readable message describing the error or status.", "type": "string", "example": "namespace not found" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the request field that caused the error.", "type": "string", "example": "/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [] }, "result": { "description": "Always null for an error response.", "type": "object", "nullable": true }, "success": { "description": "Always false for an error response.", "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Memory" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "agent-memory", "x-fern-sdk-method-name": "summary" } }, "/accounts/{account_id}/ai-gateway/billing/credit-balance": { "get": { "operationId": "aig-billing-get-credit-balance", "summary": "Get credit balance", "description": "Retrieve the current credit balance, payment method info, and top-up configuration.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Credit balance retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_GetCreditBalanceResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.billing", "x-fern-sdk-method-name": "credit-balance", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/billing/invoice-history": { "get": { "operationId": "aig-billing-get-invoice-history", "summary": "Get invoice history", "description": "Retrieve a list of past invoices with pagination, optionally filtered by type.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Filter invoice type: auto, manual, or all.", "schema": { "description": "Filter invoice type: auto, manual, or all.", "type": "string", "example": "all", "default": "all", "enum": [ "auto", "all", "manual" ] } } ], "responses": { "200": { "description": "Invoice history retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_GetInvoiceHistoryResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.billing", "x-fern-sdk-method-name": "invoice-history", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/billing/invoice-preview": { "get": { "operationId": "aig-billing-get-invoice-preview", "summary": "Get invoice preview", "description": "Retrieve a preview of the upcoming invoice including line items and tax.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoice preview retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_GetInvoicePreviewResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.billing", "x-fern-sdk-method-name": "invoice-preview", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/billing/spending-limit": { "delete": { "operationId": "aig-billing-delete-spending-limit", "summary": "Delete spending limit", "description": "Remove the spending limit for the account.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Spending limit deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_DeleteSpendingLimitResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.billing.spending-limit", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "aig-billing-get-spending-limit", "summary": "Get spending limit", "description": "Retrieve the current spending limit configuration for the account.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Spending limit configuration retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_GetSpendingLimitResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.billing.spending-limit", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "aig-billing-set-spending-limit", "summary": "Set spending limit (deprecated)", "description": "Deprecated: spending limits can no longer be created, enabled, or modified and this endpoint always responds 403. Use the new AI Gateway spend limits instead: https://developers.cloudflare.com/ai-gateway/features/spend-limits/. Existing limits can be removed via DELETE /spending-limit.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "description": "Spending limit amount in cents (min 100).", "type": "integer", "example": 10000, "minimum": 100 }, "duration": { "description": "Spending limit duration.", "type": "string", "example": "monthly", "enum": [ "daily", "weekly", "monthly" ] }, "strategy": { "description": "Spending limit strategy.", "type": "string", "example": "fixed", "enum": [ "fixed", "sliding" ] } }, "additionalProperties": false, "required": [ "amount", "strategy", "duration" ] } } } }, "responses": { "201": { "description": "Spending limit created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_SetSpendingLimitResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.billing.spending-limit", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/billing/topup": { "post": { "operationId": "aig-billing-create-topup", "summary": "Create a top-up", "description": "Create a credit top-up for the given account, charged to the account's default payment method.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "description": "Top-up amount in cents (min 1000).", "type": "integer", "example": 5000, "minimum": 1000 } }, "additionalProperties": false, "required": [ "amount" ] } } } }, "responses": { "200": { "description": "Top-up initiated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_CreateTopupResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "402": { "description": "Payment required — the payment method was declined.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.billing.topup", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/billing/topup/config": { "delete": { "operationId": "aig-billing-delete-topup-config", "summary": "Delete auto top-up configuration", "description": "Remove the auto top-up configuration for the account.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Auto top-up configuration deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_DeleteTopupConfigResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.billing.topup.config", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "aig-billing-get-topup-config", "summary": "Get auto top-up configuration", "description": "Retrieve the current auto top-up threshold, amount, and any error state.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Auto top-up configuration retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_GetTopupConfigResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.billing.topup.config", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "aig-billing-set-topup-config", "summary": "Set auto top-up configuration", "description": "Configure auto top-up with a balance threshold and top-up amount.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "description": "Auto top-up amount in cents (min 1000).", "type": "integer", "example": 5000, "minimum": 1000 }, "threshold": { "description": "Balance threshold in cents that triggers auto top-up (min 500).", "type": "integer", "example": 500, "minimum": 500 } }, "additionalProperties": false, "required": [ "threshold", "amount" ] } } } }, "responses": { "200": { "description": "Auto top-up configuration saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_SetTopupConfigResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.billing.topup.config", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/billing/topup/eligibility": { "post": { "operationId": "aig-billing-topup-eligibility", "summary": "Get top-up eligibility", "description": "Determine whether an account can self-serve a credit top-up, and if not, why. The dashboard forwards the account's payment-method list in the body; the reason logic is owned here.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_methods": { "description": "Account-level payment methods, forwarded by the dashboard.", "type": "array", "items": { "properties": { "default": { "description": "Whether this is the account default payment method.", "type": "boolean", "example": true }, "last_four": { "description": "Last 4 digits, for display copy only.", "type": "string", "example": "4242" }, "type": { "description": "Payment-method type. Absent or unrecognized is treated as non-card (does not error). Known values: PAYPAL, CREDIT_CARD, APPLE_PAY, GOOGLE_PAY, ACH_DIRECT_DEBIT, SEPA_DEBIT, CASHAPP, LINK, CRYPTO.", "type": "string", "example": "CREDIT_CARD" } }, "type": "object" }, "maxItems": 100 } } } } } }, "responses": { "200": { "description": "Eligibility determined.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_GetTopupEligibilityResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "ai-gateway.billing.topup", "x-fern-sdk-method-name": "eligibility", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/billing/topup/limits": { "get": { "operationId": "aig-billing-get-topup-limits", "summary": "Get account top-up limits", "description": "Retrieve the minimum and maximum allowed top-up amounts (in cents) for this account.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Top-up limits retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_GetTopupLimitsResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.billing", "x-fern-sdk-method-name": "get-topup-limits", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/billing/topup/status": { "post": { "operationId": "aig-billing-check-topup-status", "summary": "Check top-up status", "description": "Get the payment processing status of a top-up by its invoice ID.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_intent_id": { "description": "Stripe invoice ID to check status for.", "type": "string", "example": "in_1abc" } }, "additionalProperties": false, "required": [ "payment_intent_id" ] } } } }, "responses": { "200": { "description": "Top-up status retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_TopupStatusResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.billing.topup", "x-fern-sdk-method-name": "status", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/billing/usage-history": { "get": { "operationId": "aig-billing-get-usage-history", "summary": "Get usage history", "description": "Retrieve aggregated usage meter event summaries for the given time range.", "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } }, { "name": "value_grouping_window", "in": "query", "description": "Grouping window for usage data.", "required": true, "schema": { "description": "Grouping window for usage data.", "type": "string", "example": "day", "enum": [ "day", "hour" ] } }, { "name": "start_time", "in": "query", "description": "Start time as Unix timestamp in milliseconds.", "schema": { "description": "Start time as Unix timestamp in milliseconds.", "type": "number", "example": 1700000000000, "nullable": true } }, { "name": "end_time", "in": "query", "description": "End time as Unix timestamp in milliseconds.", "schema": { "description": "End time as Unix timestamp in milliseconds.", "type": "number", "example": 1700086400000, "nullable": true } } ], "responses": { "200": { "description": "Usage history retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_GetUsageHistoryResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aig-billing_ErrorResponse" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.billing", "x-fern-sdk-method-name": "usage-history", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/custom-providers": { "get": { "operationId": "aig-config-list-account-provider", "summary": "List Account Providers", "description": "Lists all AI Gateway evaluator types configured for the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "beta", "in": "query", "schema": { "type": "boolean" } }, { "name": "enable", "in": "query", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "schema": { "description": "Search by id, name, slug", "type": "string" } } ], "responses": { "200": { "description": "List objects", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "base_url": { "type": "string", "format": "uri" }, "beta": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "curl_example": { "type": "string" }, "description": { "type": "string" }, "enable": { "type": "boolean" }, "headers": { "type": "string", "maxLength": 8192 }, "id": { "type": "string", "format": "uuid" }, "js_example": { "type": "string" }, "link": { "type": "string" }, "logo": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "position": { "type": "integer" }, "slug": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" } }, "required": [ "id", "created_at", "modified_at", "name", "slug", "base_url" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Account Providers" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.account-providers", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "aig-config-create-account-provider", "summary": "Create a new Account Provider", "description": "Creates a new AI Gateway.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "base_url": { "type": "string", "format": "uri" }, "beta": { "type": "boolean" }, "curl_example": { "type": "string" }, "description": { "type": "string" }, "enable": { "type": "boolean" }, "headers": { "type": "string", "maxLength": 8192 }, "js_example": { "type": "string" }, "link": { "type": "string" }, "name": { "type": "string" }, "position": { "type": "integer" }, "slug": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" } }, "required": [ "name", "slug", "base_url" ] } } } }, "responses": { "200": { "description": "Returns the created Object", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "base_url": { "type": "string", "format": "uri" }, "beta": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "curl_example": { "type": "string" }, "description": { "type": "string" }, "enable": { "type": "boolean" }, "headers": { "type": "string", "maxLength": 8192 }, "id": { "type": "string", "format": "uuid" }, "js_example": { "type": "string" }, "link": { "type": "string" }, "logo": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "position": { "type": "integer" }, "slug": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" } }, "required": [ "id", "created_at", "modified_at", "name", "slug", "base_url" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7001 }, "message": { "type": "string", "example": "Input Validation Error" }, "path": { "type": "array", "items": { "example": "body", "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Account Providers" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.account-providers", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/custom-providers/costs": { "get": { "operationId": "aig-config-list-account-provider-cost", "summary": "List Account Provider Costs", "description": "Lists all AI Gateway evaluator types configured for the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "enable", "in": "query", "schema": { "type": "boolean" } }, { "name": "account_provider_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "model_rule", "in": "query", "schema": { "type": "string", "default": "equals", "enum": [ "equals", "starts-with", "contains" ] } }, { "name": "cost_type", "in": "query", "schema": { "type": "string", "default": "tokens" } }, { "name": "search", "in": "query", "schema": { "description": "Search by model, changed_by", "type": "string" } } ], "responses": { "200": { "description": "List objects", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "account_provider_id": { "type": "string", "format": "uuid" }, "changed_by": { "type": "string", "default": "manual" }, "cost_in": { "type": "number" }, "cost_out": { "type": "number" }, "cost_type": { "type": "string", "default": "tokens" }, "created_at": { "type": "string", "format": "date-time" }, "enable": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "model": { "type": "string" }, "model_rule": { "type": "string", "default": "equals", "enum": [ "equals", "starts-with", "contains" ] }, "modified_at": { "type": "string", "format": "date-time" }, "token_pricing": { "type": "string" }, "weight": { "type": "integer" } }, "required": [ "account_provider_id", "model", "id", "created_at", "modified_at" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Account Provider Costs" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.account-providers.costs", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "aig-config-create-account-provider-cost", "summary": "Create a new Account Provider Cost", "description": "Creates a new AI Gateway.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "account_provider_id": { "type": "string", "format": "uuid" }, "cost_in": { "type": "number" }, "cost_out": { "type": "number" }, "cost_type": { "type": "string", "default": "tokens" }, "enable": { "type": "boolean" }, "model": { "type": "string" }, "model_rule": { "type": "string", "default": "equals", "enum": [ "equals", "starts-with", "contains" ] }, "token_pricing": { "type": "object", "properties": { "input_audio_tokens": { "type": "number" }, "input_cache_creation_tokens": { "type": "number" }, "input_cached_tokens": { "type": "number" }, "input_image_count": { "type": "number" }, "input_image_tokens": { "type": "number" }, "input_text_tokens": { "type": "number" }, "input_tokens": { "type": "number" }, "input_video_tokens": { "type": "number" }, "output_image_count": { "type": "number" }, "output_reasoning_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } } } }, "required": [ "account_provider_id", "model" ] } } } }, "responses": { "200": { "description": "Returns the created Object", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "account_provider_id": { "type": "string", "format": "uuid" }, "changed_by": { "type": "string", "default": "manual" }, "cost_in": { "type": "number" }, "cost_out": { "type": "number" }, "cost_type": { "type": "string", "default": "tokens" }, "created_at": { "type": "string", "format": "date-time" }, "enable": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "model": { "type": "string" }, "model_rule": { "type": "string", "default": "equals", "enum": [ "equals", "starts-with", "contains" ] }, "modified_at": { "type": "string", "format": "date-time" }, "token_pricing": { "type": "string" }, "weight": { "type": "integer" } }, "required": [ "account_provider_id", "model", "id", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7001 }, "message": { "type": "string", "example": "Input Validation Error" }, "path": { "type": "array", "items": { "example": "body", "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Account Provider Costs" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.account-providers.costs", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/custom-providers/costs/{id}": { "delete": { "operationId": "aig-config-delete-account-provider-cost", "summary": "Delete a Account Provider Cost", "description": "Deletes an AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Returns the Object if it was successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "account_provider_id": { "type": "string", "format": "uuid" }, "changed_by": { "type": "string", "default": "manual" }, "cost_in": { "type": "number" }, "cost_out": { "type": "number" }, "cost_type": { "type": "string", "default": "tokens" }, "created_at": { "type": "string", "format": "date-time" }, "enable": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "model": { "type": "string" }, "model_rule": { "type": "string", "default": "equals", "enum": [ "equals", "starts-with", "contains" ] }, "modified_at": { "type": "string", "format": "date-time" }, "token_pricing": { "type": "string" }, "weight": { "type": "integer" } }, "required": [ "account_provider_id", "model", "id", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Account Provider Costs" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.account-providers.costs", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "aig-config-fetch-account-provider-cost", "summary": "Fetch a Account Provider Cost", "description": "Retrieves details for a specific AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Returns a single object if found", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "account_provider_id": { "type": "string", "format": "uuid" }, "changed_by": { "type": "string", "default": "manual" }, "cost_in": { "type": "number" }, "cost_out": { "type": "number" }, "cost_type": { "type": "string", "default": "tokens" }, "created_at": { "type": "string", "format": "date-time" }, "enable": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "model": { "type": "string" }, "model_rule": { "type": "string", "default": "equals", "enum": [ "equals", "starts-with", "contains" ] }, "modified_at": { "type": "string", "format": "date-time" }, "token_pricing": { "type": "string" }, "weight": { "type": "integer" } }, "required": [ "account_provider_id", "model", "id", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Account Provider Costs" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.account-providers.costs", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "aig-config-update-account-provider-cost", "summary": "Update a Account Provider Cost", "description": "Updates an existing AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cost_in": { "type": "number" }, "cost_out": { "type": "number" }, "cost_type": { "type": "string", "default": "tokens" }, "enable": { "type": "boolean" }, "model": { "type": "string" }, "model_rule": { "type": "string", "default": "equals", "enum": [ "equals", "starts-with", "contains" ] }, "token_pricing": { "type": "object", "properties": { "input_audio_tokens": { "type": "number" }, "input_cache_creation_tokens": { "type": "number" }, "input_cached_tokens": { "type": "number" }, "input_image_count": { "type": "number" }, "input_image_tokens": { "type": "number" }, "input_text_tokens": { "type": "number" }, "input_tokens": { "type": "number" }, "input_video_tokens": { "type": "number" }, "output_image_count": { "type": "number" }, "output_reasoning_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } } } } } } } }, "responses": { "200": { "description": "Returns the updated Object", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "account_provider_id": { "type": "string", "format": "uuid" }, "changed_by": { "type": "string", "default": "manual" }, "cost_in": { "type": "number" }, "cost_out": { "type": "number" }, "cost_type": { "type": "string", "default": "tokens" }, "created_at": { "type": "string", "format": "date-time" }, "enable": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "model": { "type": "string" }, "model_rule": { "type": "string", "default": "equals", "enum": [ "equals", "starts-with", "contains" ] }, "modified_at": { "type": "string", "format": "date-time" }, "token_pricing": { "type": "string" }, "weight": { "type": "integer" } }, "required": [ "account_provider_id", "model", "id", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7001 }, "message": { "type": "string", "example": "Input Validation Error" }, "path": { "type": "array", "items": { "example": "body", "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Account Provider Costs" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.account-providers.costs", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/custom-providers/{id}": { "delete": { "operationId": "aig-config-delete-account-provider", "summary": "Delete a Account Provider", "description": "Deletes an AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Returns the Object if it was successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "base_url": { "type": "string", "format": "uri" }, "beta": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "curl_example": { "type": "string" }, "description": { "type": "string" }, "enable": { "type": "boolean" }, "headers": { "type": "string", "maxLength": 8192 }, "id": { "type": "string", "format": "uuid" }, "js_example": { "type": "string" }, "link": { "type": "string" }, "logo": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "position": { "type": "integer" }, "slug": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" } }, "required": [ "id", "created_at", "modified_at", "name", "slug", "base_url" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Account Providers" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.account-providers", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "aig-config-fetch-account-provider", "summary": "Fetch a Account Provider", "description": "Retrieves details for a specific AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Returns a single object if found", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "base_url": { "type": "string", "format": "uri" }, "beta": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "curl_example": { "type": "string" }, "description": { "type": "string" }, "enable": { "type": "boolean" }, "headers": { "type": "string", "maxLength": 8192 }, "id": { "type": "string", "format": "uuid" }, "js_example": { "type": "string" }, "link": { "type": "string" }, "logo": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "position": { "type": "integer" }, "slug": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" } }, "required": [ "id", "created_at", "modified_at", "name", "slug", "base_url" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Account Providers" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.account-providers", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "aig-config-update-account-provider", "summary": "Update a Account Provider", "description": "Updates an existing AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "base_url": { "type": "string", "format": "uri" }, "beta": { "type": "boolean" }, "curl_example": { "type": "string" }, "description": { "type": "string" }, "enable": { "type": "boolean" }, "headers": { "type": "string", "maxLength": 8192 }, "js_example": { "type": "string" }, "link": { "type": "string" }, "logo": { "type": "string" }, "name": { "type": "string" }, "position": { "type": "integer" }, "slug": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" } } } } } }, "responses": { "200": { "description": "Returns the updated Object", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "base_url": { "type": "string", "format": "uri" }, "beta": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "curl_example": { "type": "string" }, "description": { "type": "string" }, "enable": { "type": "boolean" }, "headers": { "type": "string", "maxLength": 8192 }, "id": { "type": "string", "format": "uuid" }, "js_example": { "type": "string" }, "link": { "type": "string" }, "logo": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "position": { "type": "integer" }, "slug": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" } }, "required": [ "id", "created_at", "modified_at", "name", "slug", "base_url" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7001 }, "message": { "type": "string", "example": "Input Validation Error" }, "path": { "type": "array", "items": { "example": "body", "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Account Providers" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.account-providers", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/evaluation-types": { "get": { "operationId": "aig-config-list-evaluators", "summary": "List Evaluators", "description": "Lists all available evaluator types for scoring AI gateway responses.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "order_by", "in": "query", "schema": { "type": "string", "default": "mandatory" } }, { "name": "order_by_direction", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Returns a list of Evaluators", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "enable": { "type": "boolean" }, "id": { "type": "string" }, "mandatory": { "type": "boolean" }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type", "mandatory", "description", "enable", "id", "created_at", "modified_at" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "count", "page", "per_page", "total_count" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Evaluations" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.evaluation-types", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways": { "get": { "operationId": "aig-config-list-gateway", "summary": "List Gateways", "description": "Lists all AI Gateway evaluator types configured for the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "schema": { "description": "Search by id", "type": "string" } } ], "responses": { "200": { "description": "List objects", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "authentication": { "type": "boolean", "x-auditable": true }, "byok_only": { "description": "Requires customer-provided provider credentials and prevents fallback to Unified Billing.", "type": "boolean", "x-auditable": true }, "cache_invalidate_on_update": { "type": "boolean", "x-auditable": true }, "cache_ttl": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "collect_logs": { "type": "boolean", "x-auditable": true }, "created_at": { "type": "string", "format": "date-time" }, "dlp": { "anyOf": [ { "properties": { "action": { "type": "string", "enum": [ "BLOCK", "FLAG" ] }, "enabled": { "type": "boolean" }, "profiles": { "type": "array", "items": { "type": "string" } } }, "required": [ "profiles", "enabled", "action" ], "type": "object" }, { "properties": { "enabled": { "type": "boolean" }, "policies": { "type": "array", "items": { "properties": { "action": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "check": { "type": "array", "items": { "enum": [ "REQUEST", "RESPONSE" ], "type": "string" } }, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "enabled", "action", "profiles", "check" ], "type": "object" } } }, "required": [ "enabled", "policies" ], "type": "object" } ] }, "guardrails": { "type": "object", "nullable": true, "properties": { "prompt": { "type": "object", "properties": { "P1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S10": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S11": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S12": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S13": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S2": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S3": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S4": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S5": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S6": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S7": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S8": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S9": { "type": "string", "enum": [ "FLAG", "BLOCK" ] } } }, "response": { "type": "object", "properties": { "P1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S10": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S11": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S12": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S13": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S2": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S3": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S4": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S5": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S6": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S7": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S8": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S9": { "type": "string", "enum": [ "FLAG", "BLOCK" ] } } } }, "required": [ "prompt", "response" ], "x-auditable": true }, "id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "is_default": { "type": "boolean", "x-auditable": true }, "log_classification": { "type": "boolean", "x-auditable": true }, "log_management": { "type": "integer", "maximum": 10000000, "minimum": 10000, "nullable": true, "x-auditable": true }, "log_management_strategy": { "type": "string", "enum": [ "STOP_INSERTING", "DELETE_OLDEST" ], "nullable": true, "x-auditable": true }, "logpush": { "type": "boolean", "x-auditable": true }, "logpush_public_key": { "type": "string", "maxLength": 1024, "minLength": 16, "nullable": true, "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "otel": { "type": "array", "items": { "properties": { "authorization": { "type": "string", "maxLength": 256 }, "content_type": { "type": "string", "default": "json", "enum": [ "json", "protobuf" ] }, "headers": { "type": "object", "additionalProperties": { "maxLength": 4096, "type": "string" } }, "url": { "type": "string", "format": "uri", "maxLength": 2048 } }, "required": [ "url", "headers" ], "type": "object" }, "maxItems": 5, "nullable": true, "x-auditable": true }, "rate_limiting_interval": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "rate_limiting_limit": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "rate_limiting_technique": { "type": "string", "enum": [ "fixed", "sliding" ], "nullable": true, "x-auditable": true }, "retry_backoff": { "description": "Backoff strategy for retry delays", "type": "string", "enum": [ "constant", "linear", "exponential" ], "nullable": true, "x-auditable": true }, "retry_delay": { "description": "Delay between retry attempts in milliseconds (0-60000)", "type": "integer", "maximum": 60000, "minimum": 0, "nullable": true, "x-auditable": true }, "retry_max_attempts": { "description": "Maximum number of retry attempts for failed requests (1-5)", "type": "integer", "maximum": 5, "minimum": 1, "nullable": true, "x-auditable": true }, "spend_limits": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean", "default": false }, "rules": { "type": "array", "items": { "properties": { "enabled": { "type": "boolean", "default": true }, "id": { "type": "string", "default": "906d8b20", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "limit": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "limitType": { "type": "string", "enum": [ "cost" ] }, "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "properties": { "mode": { "type": "string", "enum": [ "partition" ] } }, "required": [ "mode" ], "type": "object" }, { "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ], "type": "object" } ] } }, "model": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ] }, "provider": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ] }, "technique": { "type": "string", "default": "sliding", "enum": [ "fixed", "sliding" ] }, "window": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 } }, "required": [ "limitType", "limit", "window" ], "type": "object" }, "default": [], "maxItems": 20 } }, "x-auditable": true }, "store_id": { "type": "string", "nullable": true }, "stripe": { "type": "object", "nullable": true, "properties": { "authorization": { "type": "string" }, "usage_events": { "type": "array", "items": { "properties": { "payload": { "type": "string" } }, "required": [ "payload" ], "type": "object" } } }, "required": [ "authorization", "usage_events" ], "x-auditable": true }, "workers_ai_billing_mode": { "description": "Controls how Workers AI inference calls routed through this gateway are billed. 'postpaid' bills the account directly through Workers AI; 'unified' deducts credits via AI Gateway using neuron-based pricing and delegates billing to AI Gateway.", "type": "string", "default": "postpaid", "enum": [ "postpaid", "unified" ], "x-auditable": true }, "zdr": { "type": "boolean", "x-auditable": true } }, "required": [ "id", "rate_limiting_interval", "rate_limiting_limit", "collect_logs", "cache_ttl", "cache_invalidate_on_update", "created_at", "modified_at" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Gateways" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.gateways", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "aig-config-create-gateway", "summary": "Create a new Gateway", "description": "Creates a new AI Gateway.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "authentication": { "type": "boolean", "x-auditable": true }, "byok_only": { "description": "Requires customer-provided provider credentials and prevents fallback to Unified Billing.", "type": "boolean", "x-auditable": true }, "cache_invalidate_on_update": { "type": "boolean", "x-auditable": true }, "cache_ttl": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "collect_logs": { "type": "boolean", "x-auditable": true }, "id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "log_management": { "type": "integer", "maximum": 10000000, "minimum": 10000, "nullable": true, "x-auditable": true }, "log_management_strategy": { "type": "string", "enum": [ "STOP_INSERTING", "DELETE_OLDEST" ], "nullable": true, "x-auditable": true }, "logpush": { "type": "boolean", "x-auditable": true }, "logpush_public_key": { "type": "string", "maxLength": 1024, "minLength": 16, "nullable": true, "x-auditable": true }, "rate_limiting_interval": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "rate_limiting_limit": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "rate_limiting_technique": { "type": "string", "enum": [ "fixed", "sliding" ], "nullable": true, "x-auditable": true }, "retry_backoff": { "description": "Backoff strategy for retry delays", "type": "string", "enum": [ "constant", "linear", "exponential" ], "nullable": true, "x-auditable": true }, "retry_delay": { "description": "Delay between retry attempts in milliseconds (0-60000)", "type": "integer", "maximum": 60000, "minimum": 0, "nullable": true, "x-auditable": true }, "retry_max_attempts": { "description": "Maximum number of retry attempts for failed requests (1-5)", "type": "integer", "maximum": 5, "minimum": 1, "nullable": true, "x-auditable": true }, "store_id": { "type": "string", "nullable": true }, "workers_ai_billing_mode": { "description": "Controls how Workers AI inference calls routed through this gateway are billed. 'postpaid' bills the account directly through Workers AI; 'unified' deducts credits via AI Gateway using neuron-based pricing and delegates billing to AI Gateway.", "type": "string", "default": "postpaid", "enum": [ "postpaid", "unified" ], "x-auditable": true }, "zdr": { "type": "boolean", "x-auditable": true } }, "required": [ "id", "rate_limiting_interval", "rate_limiting_limit", "collect_logs", "cache_ttl", "cache_invalidate_on_update" ] } } } }, "responses": { "200": { "description": "Returns the created Object", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "authentication": { "type": "boolean", "x-auditable": true }, "byok_only": { "description": "Requires customer-provided provider credentials and prevents fallback to Unified Billing.", "type": "boolean", "x-auditable": true }, "cache_invalidate_on_update": { "type": "boolean", "x-auditable": true }, "cache_ttl": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "collect_logs": { "type": "boolean", "x-auditable": true }, "created_at": { "type": "string", "format": "date-time" }, "dlp": { "anyOf": [ { "properties": { "action": { "type": "string", "enum": [ "BLOCK", "FLAG" ] }, "enabled": { "type": "boolean" }, "profiles": { "type": "array", "items": { "type": "string" } } }, "required": [ "profiles", "enabled", "action" ], "type": "object" }, { "properties": { "enabled": { "type": "boolean" }, "policies": { "type": "array", "items": { "properties": { "action": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "check": { "type": "array", "items": { "enum": [ "REQUEST", "RESPONSE" ], "type": "string" } }, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "enabled", "action", "profiles", "check" ], "type": "object" } } }, "required": [ "enabled", "policies" ], "type": "object" } ] }, "guardrails": { "type": "object", "nullable": true, "properties": { "prompt": { "type": "object", "properties": { "P1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S10": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S11": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S12": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S13": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S2": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S3": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S4": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S5": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S6": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S7": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S8": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S9": { "type": "string", "enum": [ "FLAG", "BLOCK" ] } } }, "response": { "type": "object", "properties": { "P1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S10": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S11": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S12": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S13": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S2": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S3": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S4": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S5": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S6": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S7": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S8": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S9": { "type": "string", "enum": [ "FLAG", "BLOCK" ] } } } }, "required": [ "prompt", "response" ], "x-auditable": true }, "id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "is_default": { "type": "boolean", "x-auditable": true }, "log_classification": { "type": "boolean", "x-auditable": true }, "log_management": { "type": "integer", "maximum": 10000000, "minimum": 10000, "nullable": true, "x-auditable": true }, "log_management_strategy": { "type": "string", "enum": [ "STOP_INSERTING", "DELETE_OLDEST" ], "nullable": true, "x-auditable": true }, "logpush": { "type": "boolean", "x-auditable": true }, "logpush_public_key": { "type": "string", "maxLength": 1024, "minLength": 16, "nullable": true, "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "otel": { "type": "array", "items": { "properties": { "authorization": { "type": "string", "maxLength": 256 }, "content_type": { "type": "string", "default": "json", "enum": [ "json", "protobuf" ] }, "headers": { "type": "object", "additionalProperties": { "maxLength": 4096, "type": "string" } }, "url": { "type": "string", "format": "uri", "maxLength": 2048 } }, "required": [ "url", "headers" ], "type": "object" }, "maxItems": 5, "nullable": true, "x-auditable": true }, "rate_limiting_interval": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "rate_limiting_limit": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "rate_limiting_technique": { "type": "string", "enum": [ "fixed", "sliding" ], "nullable": true, "x-auditable": true }, "retry_backoff": { "description": "Backoff strategy for retry delays", "type": "string", "enum": [ "constant", "linear", "exponential" ], "nullable": true, "x-auditable": true }, "retry_delay": { "description": "Delay between retry attempts in milliseconds (0-60000)", "type": "integer", "maximum": 60000, "minimum": 0, "nullable": true, "x-auditable": true }, "retry_max_attempts": { "description": "Maximum number of retry attempts for failed requests (1-5)", "type": "integer", "maximum": 5, "minimum": 1, "nullable": true, "x-auditable": true }, "spend_limits": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean", "default": false }, "rules": { "type": "array", "items": { "properties": { "enabled": { "type": "boolean", "default": true }, "id": { "type": "string", "default": "915d6b52", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "limit": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "limitType": { "type": "string", "enum": [ "cost" ] }, "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "properties": { "mode": { "type": "string", "enum": [ "partition" ] } }, "required": [ "mode" ], "type": "object" }, { "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ], "type": "object" } ] } }, "model": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ] }, "provider": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ] }, "technique": { "type": "string", "default": "sliding", "enum": [ "fixed", "sliding" ] }, "window": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 } }, "required": [ "limitType", "limit", "window" ], "type": "object" }, "default": [], "maxItems": 20 } }, "x-auditable": true }, "store_id": { "type": "string", "nullable": true }, "stripe": { "type": "object", "nullable": true, "properties": { "authorization": { "type": "string" }, "usage_events": { "type": "array", "items": { "properties": { "payload": { "type": "string" } }, "required": [ "payload" ], "type": "object" } } }, "required": [ "authorization", "usage_events" ], "x-auditable": true }, "workers_ai_billing_mode": { "description": "Controls how Workers AI inference calls routed through this gateway are billed. 'postpaid' bills the account directly through Workers AI; 'unified' deducts credits via AI Gateway using neuron-based pricing and delegates billing to AI Gateway.", "type": "string", "default": "postpaid", "enum": [ "postpaid", "unified" ], "x-auditable": true }, "zdr": { "type": "boolean", "x-auditable": true } }, "required": [ "id", "rate_limiting_interval", "rate_limiting_limit", "collect_logs", "cache_ttl", "cache_invalidate_on_update", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7001 }, "message": { "type": "string", "example": "Input Validation Error" }, "path": { "type": "array", "items": { "example": "body", "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Gateways" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.gateways", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/custom-domains": { "get": { "operationId": "aig-config-list-custom-domain", "summary": "List Custom Domains", "description": "Lists all AI Gateway evaluator types configured for the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "initializing", "pending_dcv", "active", "blocked", "error" ], "x-auditable": true } }, { "name": "search", "in": "query", "schema": { "description": "Search by hostname", "type": "string" } } ], "responses": { "200": { "description": "List objects", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "created_at": { "description": "epoch milliseconds", "type": "integer", "example": 1717459200000 }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "hostname": { "description": "the customer-owned custom hostname", "type": "string", "example": "ai.acme.com", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$", "x-auditable": true }, "modified_at": { "description": "epoch milliseconds", "type": "integer", "example": 1717459200000 }, "ssl_hostname_id": { "type": "string", "nullable": true, "x-auditable": true }, "status": { "type": "string", "enum": [ "initializing", "pending_dcv", "active", "blocked", "error" ], "x-auditable": true } }, "required": [ "hostname", "gateway_id", "ssl_hostname_id", "status", "created_at", "modified_at" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Custom Domains" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.custom-domains", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "aig-config-create-custom-domain", "summary": "Create a custom domain for a gateway", "description": "Provisions a Cloudflare-for-SaaS custom hostname and returns the CNAME target to point DNS at.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "description": "the customer-owned custom hostname", "type": "string", "example": "ai.acme.com", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$", "x-auditable": true }, "minTLS": { "type": "string", "enum": [ "1.0", "1.1", "1.2", "1.3" ], "x-auditable": true }, "zone_id": { "description": "Cloudflare Zone ID owning the custom hostname", "type": "string", "example": "395566f4c8a5b9d2a5fc0d457b007c44", "pattern": "^[0-9a-f]{32}$", "x-auditable": true } }, "required": [ "domain", "zone_id" ] } } } }, "responses": { "200": { "description": "The created custom domain and the CNAME target to configure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "cname_target": { "type": "string" }, "created_at": { "description": "epoch milliseconds", "type": "integer", "example": 1717459200000 }, "gateway_id": { "type": "string" }, "hostname": { "type": "string" }, "modified_at": { "description": "epoch milliseconds", "type": "integer", "example": 1717459200000 }, "status": { "type": "string", "enum": [ "initializing", "pending_dcv", "active", "blocked", "error" ] } }, "required": [ "hostname", "gateway_id", "status", "cname_target", "created_at", "modified_at" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Custom Domains" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.custom-domains", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/custom-domains/{hostname}": { "delete": { "operationId": "aig-config-delete-custom-domain", "summary": "Delete a Custom Domain", "description": "Deletes an AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "hostname", "in": "path", "required": true, "schema": { "description": "the customer-owned custom hostname", "type": "string", "example": "ai.acme.com", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$", "x-auditable": true } } ], "responses": { "200": { "description": "Returns the Object if it was successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "description": "epoch milliseconds", "type": "integer", "example": 1717459200000 }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "hostname": { "description": "the customer-owned custom hostname", "type": "string", "example": "ai.acme.com", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$", "x-auditable": true }, "modified_at": { "description": "epoch milliseconds", "type": "integer", "example": 1717459200000 }, "ssl_hostname_id": { "type": "string", "nullable": true, "x-auditable": true }, "status": { "type": "string", "enum": [ "initializing", "pending_dcv", "active", "blocked", "error" ], "x-auditable": true } }, "required": [ "hostname", "gateway_id", "ssl_hostname_id", "status", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Custom Domains" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.custom-domains", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "aig-config-fetch-custom-domain", "summary": "Fetch a Custom Domain", "description": "Retrieves details for a specific AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "hostname", "in": "path", "required": true, "schema": { "description": "the customer-owned custom hostname", "type": "string", "example": "ai.acme.com", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$", "x-auditable": true } } ], "responses": { "200": { "description": "Returns a single object if found", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "description": "epoch milliseconds", "type": "integer", "example": 1717459200000 }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "hostname": { "description": "the customer-owned custom hostname", "type": "string", "example": "ai.acme.com", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$", "x-auditable": true }, "modified_at": { "description": "epoch milliseconds", "type": "integer", "example": 1717459200000 }, "ssl_hostname_id": { "type": "string", "nullable": true, "x-auditable": true }, "status": { "type": "string", "enum": [ "initializing", "pending_dcv", "active", "blocked", "error" ], "x-auditable": true } }, "required": [ "hostname", "gateway_id", "ssl_hostname_id", "status", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Custom Domains" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.custom-domains", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/datasets": { "get": { "operationId": "aig-config-list-dataset", "summary": "List Datasets", "description": "Lists all AI Gateway evaluator types configured for the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "name", "in": "query", "schema": { "type": "string", "x-auditable": true } }, { "name": "enable", "in": "query", "schema": { "type": "boolean", "x-auditable": true } }, { "name": "search", "in": "query", "schema": { "description": "Search by id, name, filters", "type": "string" } } ], "responses": { "200": { "description": "List objects", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "created_at": { "type": "string", "format": "date-time" }, "enable": { "type": "boolean", "x-auditable": true }, "filters": { "type": "array", "items": { "properties": { "key": { "type": "string", "enum": [ "created_at", "request_content_type", "response_content_type", "success", "cached", "provider", "model", "cost", "tokens", "tokens_in", "tokens_out", "duration", "feedback" ], "x-auditable": true }, "operator": { "type": "string", "enum": [ "eq", "contains", "lt", "gt" ], "x-auditable": true }, "value": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "x-auditable": true } }, "required": [ "key", "operator", "value" ], "type": "object" }, "x-auditable": true }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "x-auditable": true } }, "required": [ "gateway_id", "name", "filters", "enable", "id", "created_at", "modified_at" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Datasets" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.datasets", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "aig-config-create-dataset", "summary": "Create a new Dataset", "description": "Creates a new AI Gateway.", "parameters": [ { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enable": { "type": "boolean", "x-auditable": true }, "filters": { "type": "array", "items": { "properties": { "key": { "type": "string", "enum": [ "created_at", "request_content_type", "response_content_type", "success", "cached", "provider", "model", "cost", "tokens", "tokens_in", "tokens_out", "duration", "feedback" ], "x-auditable": true }, "operator": { "type": "string", "enum": [ "eq", "contains", "lt", "gt" ], "x-auditable": true }, "value": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "x-auditable": true } }, "required": [ "key", "operator", "value" ], "type": "object" }, "x-auditable": true }, "name": { "type": "string", "x-auditable": true } }, "required": [ "name", "filters", "enable" ] } } } }, "responses": { "200": { "description": "Returns the created Object", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "enable": { "type": "boolean", "x-auditable": true }, "filters": { "type": "array", "items": { "properties": { "key": { "type": "string", "enum": [ "created_at", "request_content_type", "response_content_type", "success", "cached", "provider", "model", "cost", "tokens", "tokens_in", "tokens_out", "duration", "feedback" ], "x-auditable": true }, "operator": { "type": "string", "enum": [ "eq", "contains", "lt", "gt" ], "x-auditable": true }, "value": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "x-auditable": true } }, "required": [ "key", "operator", "value" ], "type": "object" }, "x-auditable": true }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "x-auditable": true } }, "required": [ "gateway_id", "name", "filters", "enable", "id", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7001 }, "message": { "type": "string", "example": "Input Validation Error" }, "path": { "type": "array", "items": { "example": "body", "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Datasets" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.datasets", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/datasets/{id}": { "delete": { "operationId": "aig-config-delete-dataset", "summary": "Delete a Dataset", "description": "Deletes an AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-auditable": true } } ], "responses": { "200": { "description": "Returns the Object if it was successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "enable": { "type": "boolean", "x-auditable": true }, "filters": { "type": "array", "items": { "properties": { "key": { "type": "string", "enum": [ "created_at", "request_content_type", "response_content_type", "success", "cached", "provider", "model", "cost", "tokens", "tokens_in", "tokens_out", "duration", "feedback" ], "x-auditable": true }, "operator": { "type": "string", "enum": [ "eq", "contains", "lt", "gt" ], "x-auditable": true }, "value": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "x-auditable": true } }, "required": [ "key", "operator", "value" ], "type": "object" }, "x-auditable": true }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "x-auditable": true } }, "required": [ "gateway_id", "name", "filters", "enable", "id", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Datasets" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.datasets", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "aig-config-fetch-dataset", "summary": "Fetch a Dataset", "description": "Retrieves details for a specific AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-auditable": true } } ], "responses": { "200": { "description": "Returns a single object if found", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "enable": { "type": "boolean", "x-auditable": true }, "filters": { "type": "array", "items": { "properties": { "key": { "type": "string", "enum": [ "created_at", "request_content_type", "response_content_type", "success", "cached", "provider", "model", "cost", "tokens", "tokens_in", "tokens_out", "duration", "feedback" ], "x-auditable": true }, "operator": { "type": "string", "enum": [ "eq", "contains", "lt", "gt" ], "x-auditable": true }, "value": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "x-auditable": true } }, "required": [ "key", "operator", "value" ], "type": "object" }, "x-auditable": true }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "x-auditable": true } }, "required": [ "gateway_id", "name", "filters", "enable", "id", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Datasets" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.datasets", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "aig-config-update-dataset", "summary": "Update a Dataset", "description": "Updates an existing AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-auditable": true } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enable": { "type": "boolean", "x-auditable": true }, "filters": { "type": "array", "items": { "properties": { "key": { "type": "string", "enum": [ "created_at", "request_content_type", "response_content_type", "success", "cached", "provider", "model", "cost", "tokens", "tokens_in", "tokens_out", "duration", "feedback" ], "x-auditable": true }, "operator": { "type": "string", "enum": [ "eq", "contains", "lt", "gt" ], "x-auditable": true }, "value": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "x-auditable": true } }, "required": [ "key", "operator", "value" ], "type": "object" }, "x-auditable": true }, "name": { "type": "string", "x-auditable": true } }, "required": [ "name", "filters", "enable" ] } } } }, "responses": { "200": { "description": "Returns the updated Object", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "enable": { "type": "boolean", "x-auditable": true }, "filters": { "type": "array", "items": { "properties": { "key": { "type": "string", "enum": [ "created_at", "request_content_type", "response_content_type", "success", "cached", "provider", "model", "cost", "tokens", "tokens_in", "tokens_out", "duration", "feedback" ], "x-auditable": true }, "operator": { "type": "string", "enum": [ "eq", "contains", "lt", "gt" ], "x-auditable": true }, "value": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "x-auditable": true } }, "required": [ "key", "operator", "value" ], "type": "object" }, "x-auditable": true }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "x-auditable": true } }, "required": [ "gateway_id", "name", "filters", "enable", "id", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7001 }, "message": { "type": "string", "example": "Input Validation Error" }, "path": { "type": "array", "items": { "example": "body", "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Datasets" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.datasets", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/evaluations": { "get": { "operationId": "aig-config-list-evaluations", "summary": "List Evaluations", "description": "Lists all AI Gateway evaluator types configured for the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "name", "in": "query", "schema": { "type": "string", "x-auditable": true } }, { "name": "processed", "in": "query", "schema": { "type": "boolean", "x-auditable": true } }, { "name": "search", "in": "query", "schema": { "description": "Search by id, name", "type": "string" } } ], "responses": { "200": { "description": "List objects", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "created_at": { "type": "string", "format": "date-time" }, "datasets": { "type": "array", "items": { "properties": { "account_id": { "type": "string" }, "account_tag": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "enable": { "type": "boolean", "x-auditable": true }, "filters": { "type": "array", "items": { "properties": { "key": { "type": "string", "enum": [ "created_at", "request_content_type", "response_content_type", "success", "cached", "provider", "model", "cost", "tokens", "tokens_in", "tokens_out", "duration", "feedback" ], "x-auditable": true }, "operator": { "type": "string", "enum": [ "eq", "contains", "lt", "gt" ], "x-auditable": true }, "value": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "x-auditable": true } }, "required": [ "key", "operator", "value" ], "type": "object" }, "x-auditable": true }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "x-auditable": true } }, "required": [ "gateway_id", "name", "filters", "enable", "id", "account_id", "account_tag", "created_at", "modified_at" ], "type": "object" } }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "x-auditable": true }, "processed": { "type": "boolean", "x-auditable": true }, "results": { "type": "array", "items": { "properties": { "created_at": { "type": "string", "format": "date-time" }, "evaluation_id": { "type": "string" }, "evaluation_type_id": { "type": "string" }, "id": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "result": { "type": "string" }, "status": { "type": "number" }, "status_description": { "type": "string" }, "total_logs": { "type": "number" } }, "required": [ "evaluation_id", "evaluation_type_id", "result", "total_logs", "status", "status_description", "id", "created_at", "modified_at" ], "type": "object" } }, "total_logs": { "type": "number", "x-auditable": true } }, "required": [ "id", "gateway_id", "name", "created_at", "modified_at", "datasets", "results", "processed", "total_logs" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Evaluations" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.evaluations", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "aig-config-create-evaluations", "summary": "Create a new Evaluation", "description": "Creates a new AI Gateway.", "parameters": [ { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 5, "minItems": 1 }, "evaluation_type_ids": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string", "x-auditable": true } }, "required": [ "name", "dataset_ids", "evaluation_type_ids" ] } } } }, "responses": { "200": { "description": "Returns the created Object", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "datasets": { "type": "array", "items": { "properties": { "account_id": { "type": "string" }, "account_tag": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "enable": { "type": "boolean", "x-auditable": true }, "filters": { "type": "array", "items": { "properties": { "key": { "type": "string", "enum": [ "created_at", "request_content_type", "response_content_type", "success", "cached", "provider", "model", "cost", "tokens", "tokens_in", "tokens_out", "duration", "feedback" ], "x-auditable": true }, "operator": { "type": "string", "enum": [ "eq", "contains", "lt", "gt" ], "x-auditable": true }, "value": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "x-auditable": true } }, "required": [ "key", "operator", "value" ], "type": "object" }, "x-auditable": true }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "x-auditable": true } }, "required": [ "gateway_id", "name", "filters", "enable", "id", "account_id", "account_tag", "created_at", "modified_at" ], "type": "object" } }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "x-auditable": true }, "processed": { "type": "boolean", "x-auditable": true }, "results": { "type": "array", "items": { "properties": { "created_at": { "type": "string", "format": "date-time" }, "evaluation_id": { "type": "string" }, "evaluation_type_id": { "type": "string" }, "id": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "result": { "type": "string" }, "status": { "type": "number" }, "status_description": { "type": "string" }, "total_logs": { "type": "number" } }, "required": [ "evaluation_id", "evaluation_type_id", "result", "total_logs", "status", "status_description", "id", "created_at", "modified_at" ], "type": "object" } }, "total_logs": { "type": "number", "x-auditable": true } }, "required": [ "id", "gateway_id", "name", "created_at", "modified_at", "datasets", "results", "processed", "total_logs" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7001 }, "message": { "type": "string", "example": "Input Validation Error" }, "path": { "type": "array", "items": { "example": "body", "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Evaluations" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.evaluations", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/evaluations/{id}": { "delete": { "operationId": "aig-config-delete-evaluations", "summary": "Delete a Evaluation", "description": "Deletes an AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-auditable": true } } ], "responses": { "200": { "description": "Returns the Object if it was successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "datasets": { "type": "array", "items": { "properties": { "account_id": { "type": "string" }, "account_tag": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "enable": { "type": "boolean", "x-auditable": true }, "filters": { "type": "array", "items": { "properties": { "key": { "type": "string", "enum": [ "created_at", "request_content_type", "response_content_type", "success", "cached", "provider", "model", "cost", "tokens", "tokens_in", "tokens_out", "duration", "feedback" ], "x-auditable": true }, "operator": { "type": "string", "enum": [ "eq", "contains", "lt", "gt" ], "x-auditable": true }, "value": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "x-auditable": true } }, "required": [ "key", "operator", "value" ], "type": "object" }, "x-auditable": true }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "x-auditable": true } }, "required": [ "gateway_id", "name", "filters", "enable", "id", "account_id", "account_tag", "created_at", "modified_at" ], "type": "object" } }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "x-auditable": true }, "processed": { "type": "boolean", "x-auditable": true }, "results": { "type": "array", "items": { "properties": { "created_at": { "type": "string", "format": "date-time" }, "evaluation_id": { "type": "string" }, "evaluation_type_id": { "type": "string" }, "id": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "result": { "type": "string" }, "status": { "type": "number" }, "status_description": { "type": "string" }, "total_logs": { "type": "number" } }, "required": [ "evaluation_id", "evaluation_type_id", "result", "total_logs", "status", "status_description", "id", "created_at", "modified_at" ], "type": "object" } }, "total_logs": { "type": "number", "x-auditable": true } }, "required": [ "id", "gateway_id", "name", "created_at", "modified_at", "datasets", "results", "processed", "total_logs" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Evaluations" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.evaluations", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "aig-config-fetch-evaluations", "summary": "Fetch a Evaluation", "description": "Retrieves details for a specific AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "x-auditable": true } } ], "responses": { "200": { "description": "Returns a single object if found", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "datasets": { "type": "array", "items": { "properties": { "account_id": { "type": "string" }, "account_tag": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "enable": { "type": "boolean", "x-auditable": true }, "filters": { "type": "array", "items": { "properties": { "key": { "type": "string", "enum": [ "created_at", "request_content_type", "response_content_type", "success", "cached", "provider", "model", "cost", "tokens", "tokens_in", "tokens_out", "duration", "feedback" ], "x-auditable": true }, "operator": { "type": "string", "enum": [ "eq", "contains", "lt", "gt" ], "x-auditable": true }, "value": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "x-auditable": true } }, "required": [ "key", "operator", "value" ], "type": "object" }, "x-auditable": true }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "x-auditable": true } }, "required": [ "gateway_id", "name", "filters", "enable", "id", "account_id", "account_tag", "created_at", "modified_at" ], "type": "object" } }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "x-auditable": true }, "processed": { "type": "boolean", "x-auditable": true }, "results": { "type": "array", "items": { "properties": { "created_at": { "type": "string", "format": "date-time" }, "evaluation_id": { "type": "string" }, "evaluation_type_id": { "type": "string" }, "id": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "result": { "type": "string" }, "status": { "type": "number" }, "status_description": { "type": "string" }, "total_logs": { "type": "number" } }, "required": [ "evaluation_id", "evaluation_type_id", "result", "total_logs", "status", "status_description", "id", "created_at", "modified_at" ], "type": "object" } }, "total_logs": { "type": "number", "x-auditable": true } }, "required": [ "id", "gateway_id", "name", "created_at", "modified_at", "datasets", "results", "processed", "total_logs" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Evaluations" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.evaluations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/logs": { "delete": { "operationId": "aig-config-delete-gateway-logs", "summary": "Delete Gateway Logs", "description": "Deletes gateway log entries matching the specified criteria.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "order_by", "in": "query", "schema": { "type": "string", "default": "created_at", "enum": [ "created_at", "provider", "model", "model_type", "success", "cached", "cost", "tokens_in", "tokens_out", "duration", "feedback" ] } }, { "name": "order_by_direction", "in": "query", "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } }, { "name": "filters", "in": "query", "schema": { "type": "array", "items": { "properties": { "key": { "type": "string", "enum": [ "id", "created_at", "request_content_type", "response_content_type", "request_type", "success", "cached", "provider", "model", "model_type", "cost", "tokens", "tokens_in", "tokens_out", "duration", "feedback", "event_id", "metadata.key", "metadata.value", "authentication", "wholesale", "compatibilityMode", "dlp_action", "user_agent" ] }, "operator": { "type": "string", "enum": [ "eq", "neq", "contains", "lt", "gt" ] }, "value": { "type": "array", "items": { "anyOf": [ { "nullable": true, "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "key", "operator", "value" ], "type": "object" } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10000, "maximum": 10000, "minimum": 1 } } ], "responses": { "200": { "description": "Returns if the delete was successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Logs" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.logs", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "aig-config-list-gateway-logs", "summary": "List Gateway Logs", "description": "Lists request/response log entries for the AI gateway with filtering and pagination.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50, "minimum": 1 } }, { "name": "order_by", "in": "query", "schema": { "type": "string", "default": "created_at", "enum": [ "created_at", "provider", "model", "model_type", "success", "cached" ] } }, { "name": "order_by_direction", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "filters", "in": "query", "schema": { "type": "array", "items": { "properties": { "key": { "type": "string", "enum": [ "id", "created_at", "request_content_type", "response_content_type", "request_type", "success", "cached", "provider", "model", "model_type", "cost", "tokens", "tokens_in", "tokens_out", "duration", "feedback", "event_id", "metadata.key", "metadata.value", "authentication", "wholesale", "compatibilityMode", "dlp_action", "user_agent" ] }, "operator": { "type": "string", "enum": [ "eq", "neq", "contains", "lt", "gt" ] }, "value": { "type": "array", "items": { "anyOf": [ { "nullable": true, "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "key", "operator", "value" ], "type": "object" } } }, { "name": "meta_info", "in": "query", "schema": { "type": "boolean" } }, { "name": "direction", "in": "query", "schema": { "type": "string", "deprecated": true, "enum": [ "asc", "desc" ] } }, { "name": "start_date", "in": "query", "schema": { "type": "string", "format": "date-time", "deprecated": true } }, { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date-time", "deprecated": true } }, { "name": "min_cost", "in": "query", "schema": { "type": "number", "deprecated": true } }, { "name": "max_cost", "in": "query", "schema": { "type": "number", "deprecated": true } }, { "name": "min_tokens_in", "in": "query", "schema": { "type": "number", "deprecated": true } }, { "name": "max_tokens_in", "in": "query", "schema": { "type": "number", "deprecated": true } }, { "name": "min_tokens_out", "in": "query", "schema": { "type": "number", "deprecated": true } }, { "name": "max_tokens_out", "in": "query", "schema": { "type": "number", "deprecated": true } }, { "name": "min_total_tokens", "in": "query", "schema": { "type": "number", "deprecated": true } }, { "name": "max_total_tokens", "in": "query", "schema": { "type": "number", "deprecated": true } }, { "name": "min_duration", "in": "query", "schema": { "type": "number", "deprecated": true } }, { "name": "max_duration", "in": "query", "schema": { "type": "number", "deprecated": true } }, { "name": "feedback", "in": "query", "schema": { "anyOf": [ { "enum": [ -1 ], "type": "number" }, { "enum": [ 0 ], "type": "number" }, { "enum": [ 1 ], "type": "number" } ], "deprecated": true } }, { "name": "success", "in": "query", "schema": { "type": "boolean", "deprecated": true } }, { "name": "cached", "in": "query", "schema": { "type": "boolean", "deprecated": true } }, { "name": "model", "in": "query", "schema": { "type": "string", "deprecated": true } }, { "name": "model_type", "in": "query", "schema": { "type": "string", "deprecated": true } }, { "name": "provider", "in": "query", "schema": { "type": "string", "deprecated": true } }, { "name": "request_content_type", "in": "query", "schema": { "type": "string", "deprecated": true } }, { "name": "response_content_type", "in": "query", "schema": { "type": "string", "deprecated": true } } ], "responses": { "200": { "description": "Returns a list of Gateway Logs", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "cached": { "type": "boolean" }, "cost": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "custom_cost": { "type": "boolean" }, "duration": { "type": "integer" }, "id": { "type": "string" }, "metadata": { "type": "string" }, "model": { "type": "string" }, "model_type": { "type": "string" }, "path": { "type": "string" }, "provider": { "type": "string" }, "request_content_type": { "type": "string" }, "request_type": { "type": "string" }, "response_content_type": { "type": "string" }, "status_code": { "type": "integer" }, "step": { "type": "integer" }, "success": { "type": "boolean" }, "tokens_in": { "type": "integer", "nullable": true }, "tokens_out": { "type": "integer", "nullable": true } }, "required": [ "id", "created_at", "provider", "model", "path", "duration", "success", "cached", "tokens_in", "tokens_out" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "max_cost": { "type": "number" }, "max_duration": { "type": "number" }, "max_tokens_in": { "type": "number" }, "max_tokens_out": { "type": "number" }, "max_total_tokens": { "type": "number" }, "min_cost": { "type": "number" }, "min_duration": { "type": "number" }, "min_tokens_in": { "type": "number" }, "min_tokens_out": { "type": "number" }, "min_total_tokens": { "type": "number" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } } }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Logs" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.logs", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/logs/{id}": { "get": { "operationId": "aig-config-get-gateway-log-detail", "summary": "Get Gateway Log Detail", "description": "Retrieves detailed information for a specific AI Gateway log entry.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } } ], "responses": { "200": { "description": "Returns the log details", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "cached": { "type": "boolean" }, "cost": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "custom_cost": { "type": "boolean" }, "duration": { "type": "integer" }, "id": { "type": "string" }, "metadata": { "type": "string" }, "model": { "type": "string" }, "model_type": { "type": "string" }, "path": { "type": "string" }, "provider": { "type": "string" }, "request_content_type": { "type": "string" }, "request_head": { "type": "string" }, "request_head_complete": { "type": "boolean" }, "request_size": { "type": "integer" }, "request_type": { "type": "string" }, "response_content_type": { "type": "string" }, "response_head": { "type": "string" }, "response_head_complete": { "type": "boolean" }, "response_size": { "type": "integer" }, "status_code": { "type": "integer" }, "step": { "type": "integer" }, "success": { "type": "boolean" }, "tokens_in": { "type": "integer", "nullable": true }, "tokens_out": { "type": "integer", "nullable": true } }, "required": [ "id", "created_at", "provider", "model", "path", "duration", "success", "cached", "tokens_in", "tokens_out" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Logs" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.logs", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "aig-config-patch-gateway-log", "summary": "Patch Gateway Log", "description": "Updates metadata for an AI Gateway log entry.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "feedback": { "type": "number", "maximum": 1, "minimum": -1, "nullable": true }, "metadata": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "nullable": true }, "score": { "type": "number", "maximum": 100, "minimum": 0, "nullable": true } } } } } }, "responses": { "200": { "description": "Returns the log details", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Logs" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.logs", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/logs/{id}/request": { "get": { "operationId": "aig-config-get-gateway-log-request", "summary": "Get Gateway Log Request", "description": "Retrieves the original request payload for an AI Gateway log entry.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } } ], "responses": { "200": { "description": "Returns the request body from a specific log", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Logs" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.logs", "x-fern-sdk-method-name": "request", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/logs/{id}/response": { "get": { "operationId": "aig-config-get-gateway-log-response", "summary": "Get Gateway Log Response", "description": "Retrieves the response payload for an AI Gateway log entry.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } } ], "responses": { "200": { "description": "Returns the response body from a specific log", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Logs" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.logs", "x-fern-sdk-method-name": "response", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/provider_configs": { "get": { "operationId": "aig-config-list-providers", "summary": "List Provider Configs", "description": "Lists all AI Gateway evaluator types configured for the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "List objects", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "alias": { "type": "string" }, "default_config": { "type": "boolean" }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "provider_slug": { "type": "string" }, "rate_limit": { "type": "number" }, "rate_limit_period": { "type": "number", "default": 60 }, "secret_id": { "type": "string" }, "secret_preview": { "type": "string" } }, "required": [ "id", "provider_slug", "secret_preview", "default_config", "gateway_id", "modified_at", "alias", "secret_id" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Provider Configs" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.gateways.providers", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "aig-config-create-providers", "summary": "Create a new Provider Configs", "description": "Creates a new AI Gateway.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "alias": { "type": "string" }, "default_config": { "type": "boolean" }, "provider_slug": { "type": "string" }, "rate_limit": { "type": "number" }, "rate_limit_period": { "type": "number", "default": 60 }, "secret": { "type": "string" }, "secret_id": { "type": "string" } }, "required": [ "provider_slug", "default_config", "alias" ] } } } }, "responses": { "200": { "description": "Returns the created Object", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "alias": { "type": "string" }, "default_config": { "type": "boolean" }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "provider_slug": { "type": "string" }, "rate_limit": { "type": "number" }, "rate_limit_period": { "type": "number", "default": 60 }, "secret_id": { "type": "string" }, "secret_preview": { "type": "string" } }, "required": [ "id", "provider_slug", "secret_preview", "default_config", "gateway_id", "modified_at", "alias", "secret_id" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7001 }, "message": { "type": "string", "example": "Input Validation Error" }, "path": { "type": "array", "items": { "example": "body", "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Provider Configs" ], "x-api-token-group": [ "Secrets Store Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.gateways.providers", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/provider_configs/{id}": { "delete": { "operationId": "aig-config-delete-providers", "summary": "Delete a Provider Configs", "description": "Deletes an AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the Object if it was successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "alias": { "type": "string" }, "default_config": { "type": "boolean" }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "provider_slug": { "type": "string" }, "rate_limit": { "type": "number" }, "rate_limit_period": { "type": "number", "default": 60 }, "secret_id": { "type": "string" }, "secret_preview": { "type": "string" } }, "required": [ "id", "provider_slug", "secret_preview", "default_config", "gateway_id", "modified_at", "alias", "secret_id" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Provider Configs" ], "x-api-token-group": [ "Secrets Store Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.gateways.providers", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "put": { "operationId": "aig-config-update-providers", "summary": "Update a Provider Configs", "description": "Updates an existing AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string" } }, "required": [ "secret" ] } } } }, "responses": { "200": { "description": "Returns the updated Object", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "alias": { "type": "string" }, "default_config": { "type": "boolean" }, "gateway_id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "id": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "provider_slug": { "type": "string" }, "rate_limit": { "type": "number" }, "rate_limit_period": { "type": "number", "default": 60 }, "secret_id": { "type": "string" }, "secret_preview": { "type": "string" } }, "required": [ "id", "provider_slug", "secret_preview", "default_config", "gateway_id", "modified_at", "alias", "secret_id" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7001 }, "message": { "type": "string", "example": "Input Validation Error" }, "path": { "type": "array", "items": { "example": "body", "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Provider Configs" ], "x-api-token-group": [ "Secrets Store Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.gateways.providers", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/routes": { "get": { "operationId": "aig-config-list-gateway-dynamic-routes", "summary": "List all AI Gateway Dynamic Routes.", "description": "List all AI Gateway Dynamic Routes.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } }, { "name": "page", "in": "query", "description": "Page number", "schema": { "description": "Page number", "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of routes per page", "schema": { "description": "Number of routes per page", "type": "integer", "example": 20 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_by": { "type": "string" }, "order_by_direction": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "routes": { "type": "array", "items": { "properties": { "account_tag": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "deployment": { "type": "object", "properties": { "created_at": { "type": "string" }, "deployment_id": { "type": "string" }, "version_id": { "type": "string" } }, "required": [ "deployment_id", "version_id", "created_at" ] }, "elements": { "type": "array", "items": { "oneOf": [ { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "next": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "next" ] }, "type": { "type": "string", "enum": [ "start" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "false": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "true": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "true", "false" ] }, "properties": { "type": "object", "properties": { "conditions": { "type": "object" } } }, "type": { "type": "string", "enum": [ "conditional" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "percentage" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "key": { "type": "string" }, "limit": { "type": "number" }, "limitType": { "enum": [ "count", "cost" ], "type": "string" }, "window": { "type": "number" } }, "required": [ "limitType", "key", "limit", "window" ] }, "type": { "type": "string", "enum": [ "rate" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "retries": { "type": "number" }, "timeout": { "type": "number" } }, "required": [ "provider", "model", "timeout", "retries" ] }, "type": { "type": "string", "enum": [ "model" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "end" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" } ] } }, "gateway_id": { "type": "string" }, "id": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "version": { "type": "object", "properties": { "active": { "type": "string", "enum": [ "true", "false" ] }, "created_at": { "type": "string" }, "data": { "type": "string" }, "is_valid": { "type": "boolean" }, "version_id": { "type": "string" } }, "required": [ "version_id", "data", "active", "created_at" ] } }, "required": [ "id", "name", "elements", "created_at", "modified_at", "account_tag", "gateway_id", "version", "deployment" ], "type": "object" } } }, "required": [ "routes", "page", "per_page", "order_by", "order_by_direction" ] }, "success": { "type": "boolean" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Dynamic Routes" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "aig-config-post-gateway-dynamic-route", "summary": "Create a new AI Gateway Dynamic Route.", "description": "Create a new AI Gateway Dynamic Route.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "elements": { "type": "array", "items": { "oneOf": [ { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "next": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "next" ] }, "type": { "type": "string", "enum": [ "start" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "false": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "true": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "true", "false" ] }, "properties": { "type": "object", "properties": { "conditions": { "type": "object" } } }, "type": { "type": "string", "enum": [ "conditional" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "percentage" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "key": { "type": "string" }, "limit": { "type": "number" }, "limitType": { "enum": [ "count", "cost" ], "type": "string" }, "window": { "type": "number" } }, "required": [ "limitType", "key", "limit", "window" ] }, "type": { "type": "string", "enum": [ "rate" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "retries": { "type": "number" }, "timeout": { "type": "number" } }, "required": [ "provider", "model", "timeout", "retries" ] }, "type": { "type": "string", "enum": [ "model" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "end" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" } ] } }, "name": { "type": "string" } }, "required": [ "name", "elements" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "deployment": { "type": "object", "properties": { "created_at": { "type": "string" }, "deployment_id": { "type": "string" }, "version_id": { "type": "string" } }, "required": [ "deployment_id", "version_id", "created_at" ] }, "elements": { "type": "array", "items": { "oneOf": [ { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "next": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "next" ] }, "type": { "type": "string", "enum": [ "start" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "false": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "true": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "true", "false" ] }, "properties": { "type": "object", "properties": { "conditions": { "type": "object" } } }, "type": { "type": "string", "enum": [ "conditional" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "percentage" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "key": { "type": "string" }, "limit": { "type": "number" }, "limitType": { "enum": [ "count", "cost" ], "type": "string" }, "window": { "type": "number" } }, "required": [ "limitType", "key", "limit", "window" ] }, "type": { "type": "string", "enum": [ "rate" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "retries": { "type": "number" }, "timeout": { "type": "number" } }, "required": [ "provider", "model", "timeout", "retries" ] }, "type": { "type": "string", "enum": [ "model" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "end" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" } ] } }, "gateway_id": { "type": "string" }, "id": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "version": { "type": "object", "properties": { "active": { "type": "string", "enum": [ "true", "false" ] }, "created_at": { "type": "string" }, "data": { "type": "string" }, "is_valid": { "type": "boolean" }, "version_id": { "type": "string" } }, "required": [ "version_id", "data", "active", "created_at" ] } }, "required": [ "id", "name", "elements", "created_at", "modified_at", "gateway_id", "version", "deployment" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Dynamic Routes" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/routes/{id}": { "delete": { "operationId": "aig-config-delete-gateway-dynamic-route", "summary": "Delete an AI Gateway Dynamic Route.", "description": "Delete an AI Gateway Dynamic Route.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "elements": { "type": "array", "items": { "oneOf": [ { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "next": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "next" ] }, "type": { "type": "string", "enum": [ "start" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "false": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "true": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "true", "false" ] }, "properties": { "type": "object", "properties": { "conditions": { "type": "object" } } }, "type": { "type": "string", "enum": [ "conditional" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "percentage" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "key": { "type": "string" }, "limit": { "type": "number" }, "limitType": { "enum": [ "count", "cost" ], "type": "string" }, "window": { "type": "number" } }, "required": [ "limitType", "key", "limit", "window" ] }, "type": { "type": "string", "enum": [ "rate" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "retries": { "type": "number" }, "timeout": { "type": "number" } }, "required": [ "provider", "model", "timeout", "retries" ] }, "type": { "type": "string", "enum": [ "model" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "end" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" } ] } }, "gateway_id": { "type": "string" }, "id": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" } }, "required": [ "id", "name", "elements", "created_at", "modified_at", "gateway_id" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Dynamic Routes" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "aig-config-get-gateway-dynamic-route", "summary": "Get an AI Gateway Dynamic Route.", "description": "Get an AI Gateway Dynamic Route.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "deployment": { "type": "object", "properties": { "created_at": { "type": "string" }, "deployment_id": { "type": "string" }, "version_id": { "type": "string" } }, "required": [ "deployment_id", "version_id", "created_at" ] }, "elements": { "type": "array", "items": { "oneOf": [ { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "next": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "next" ] }, "type": { "type": "string", "enum": [ "start" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "false": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "true": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "true", "false" ] }, "properties": { "type": "object", "properties": { "conditions": { "type": "object" } } }, "type": { "type": "string", "enum": [ "conditional" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "percentage" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "key": { "type": "string" }, "limit": { "type": "number" }, "limitType": { "enum": [ "count", "cost" ], "type": "string" }, "window": { "type": "number" } }, "required": [ "limitType", "key", "limit", "window" ] }, "type": { "type": "string", "enum": [ "rate" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "retries": { "type": "number" }, "timeout": { "type": "number" } }, "required": [ "provider", "model", "timeout", "retries" ] }, "type": { "type": "string", "enum": [ "model" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "end" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" } ] } }, "gateway_id": { "type": "string" }, "id": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "version": { "type": "object", "properties": { "active": { "type": "string", "enum": [ "true", "false" ] }, "created_at": { "type": "string" }, "data": { "type": "string" }, "is_valid": { "type": "boolean" }, "version_id": { "type": "string" } }, "required": [ "version_id", "data", "active", "created_at" ] } }, "required": [ "id", "name", "elements", "created_at", "modified_at", "gateway_id", "version", "deployment" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Dynamic Routes" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "aig-config-update-gateway-dynamic-route", "summary": "Update an AI Gateway Dynamic Route.", "description": "Update an AI Gateway Dynamic Route.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Route Name" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "route": { "type": "object", "properties": { "account_tag": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "deployment": { "type": "object", "properties": { "created_at": { "type": "string" }, "deployment_id": { "type": "string" }, "version_id": { "type": "string" } }, "required": [ "deployment_id", "version_id", "created_at" ] }, "elements": { "type": "array", "items": { "oneOf": [ { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "next": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "next" ] }, "type": { "type": "string", "enum": [ "start" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "false": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "true": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "true", "false" ] }, "properties": { "type": "object", "properties": { "conditions": { "type": "object" } } }, "type": { "type": "string", "enum": [ "conditional" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "percentage" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "key": { "type": "string" }, "limit": { "type": "number" }, "limitType": { "enum": [ "count", "cost" ], "type": "string" }, "window": { "type": "number" } }, "required": [ "limitType", "key", "limit", "window" ] }, "type": { "type": "string", "enum": [ "rate" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "retries": { "type": "number" }, "timeout": { "type": "number" } }, "required": [ "provider", "model", "timeout", "retries" ] }, "type": { "type": "string", "enum": [ "model" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "end" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" } ] } }, "gateway_id": { "type": "string" }, "id": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "version": { "type": "object", "properties": { "active": { "type": "string", "enum": [ "true", "false" ] }, "created_at": { "type": "string" }, "data": { "type": "string" }, "is_valid": { "type": "boolean" }, "version_id": { "type": "string" } }, "required": [ "version_id", "data", "active", "created_at" ] } }, "required": [ "id", "name", "elements", "created_at", "modified_at", "account_tag", "gateway_id", "version", "deployment" ] }, "success": { "type": "boolean" } }, "required": [ "success", "route" ] } } } }, "400": { "description": "Input Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "route": { "type": "object", "properties": { "account_tag": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "elements": { "type": "array", "items": { "oneOf": [ { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "next": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "next" ] }, "type": { "type": "string", "enum": [ "start" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "false": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "true": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "true", "false" ] }, "properties": { "type": "object", "properties": { "conditions": { "type": "object" } } }, "type": { "type": "string", "enum": [ "conditional" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "percentage" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "key": { "type": "string" }, "limit": { "type": "number" }, "limitType": { "enum": [ "count", "cost" ], "type": "string" }, "window": { "type": "number" } }, "required": [ "limitType", "key", "limit", "window" ] }, "type": { "type": "string", "enum": [ "rate" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "retries": { "type": "number" }, "timeout": { "type": "number" } }, "required": [ "provider", "model", "timeout", "retries" ] }, "type": { "type": "string", "enum": [ "model" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "end" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" } ] } }, "gateway_id": { "type": "string" }, "id": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" } }, "required": [ "id", "name", "elements", "created_at", "modified_at", "account_tag", "gateway_id" ] }, "success": { "type": "boolean" } }, "required": [ "success", "route" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Dynamic Routes" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/routes/{id}/deployments": { "get": { "operationId": "aig-config-list-gateway-dynamic-route-deployments", "summary": "List all AI Gateway Dynamic Route Deployments.", "description": "List all AI Gateway Dynamic Route Deployments.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deployments": { "type": "array", "items": { "properties": { "created_at": { "type": "string" }, "deployment_id": { "type": "string" }, "version_id": { "type": "string" } }, "required": [ "deployment_id", "version_id", "created_at" ], "type": "object" } }, "order_by": { "type": "string" }, "order_by_direction": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" } }, "required": [ "deployments", "page", "per_page", "order_by", "order_by_direction" ] }, "success": { "type": "boolean" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Dynamic Routes" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing", "x-fern-sdk-method-name": "list-deployments", "x-forge-hidden": true }, "post": { "operationId": "aig-config-post-gateway-dynamic-route-deployment", "summary": "Create a new AI Gateway Dynamic Route Deployment.", "description": "Create a new AI Gateway Dynamic Route Deployment.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "version_id": { "type": "string", "example": "54442216" } }, "required": [ "version_id" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "elements": { "type": "array", "items": { "oneOf": [ { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "next": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "next" ] }, "type": { "type": "string", "enum": [ "start" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "false": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "true": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "true", "false" ] }, "properties": { "type": "object", "properties": { "conditions": { "type": "object" } } }, "type": { "type": "string", "enum": [ "conditional" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "percentage" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "key": { "type": "string" }, "limit": { "type": "number" }, "limitType": { "enum": [ "count", "cost" ], "type": "string" }, "window": { "type": "number" } }, "required": [ "limitType", "key", "limit", "window" ] }, "type": { "type": "string", "enum": [ "rate" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "retries": { "type": "number" }, "timeout": { "type": "number" } }, "required": [ "provider", "model", "timeout", "retries" ] }, "type": { "type": "string", "enum": [ "model" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "end" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" } ] } }, "gateway_id": { "type": "string" }, "id": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" } }, "required": [ "id", "name", "elements", "created_at", "modified_at", "gateway_id" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Dynamic Routes" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing", "x-fern-sdk-method-name": "create-deployment", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/routes/{id}/versions": { "get": { "operationId": "aig-config-list-gateway-dynamic-route-versions", "summary": "List all AI Gateway Dynamic Route Versions.", "description": "List all AI Gateway Dynamic Route Versions.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_by": { "type": "string" }, "order_by_direction": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "versions": { "type": "array", "items": { "properties": { "active": { "type": "string", "enum": [ "true", "false" ] }, "created_at": { "type": "string" }, "data": { "type": "string" }, "is_valid": { "type": "boolean" }, "version_id": { "type": "string" } }, "required": [ "version_id", "data", "active", "created_at" ], "type": "object" } } }, "required": [ "versions", "page", "per_page", "order_by", "order_by_direction" ] }, "success": { "type": "boolean" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Dynamic Routes" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing", "x-fern-sdk-method-name": "list-versions", "x-forge-hidden": true }, "post": { "operationId": "aig-config-post-gateway-dynamic-route-version", "summary": "Create a new AI Gateway Dynamic Route Version.", "description": "Create a new AI Gateway Dynamic Route Version.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "elements": { "type": "array", "items": { "oneOf": [ { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "next": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "next" ] }, "type": { "type": "string", "enum": [ "start" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "false": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "true": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "true", "false" ] }, "properties": { "type": "object", "properties": { "conditions": { "type": "object" } } }, "type": { "type": "string", "enum": [ "conditional" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "percentage" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "key": { "type": "string" }, "limit": { "type": "number" }, "limitType": { "enum": [ "count", "cost" ], "type": "string" }, "window": { "type": "number" } }, "required": [ "limitType", "key", "limit", "window" ] }, "type": { "type": "string", "enum": [ "rate" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "retries": { "type": "number" }, "timeout": { "type": "number" } }, "required": [ "provider", "model", "timeout", "retries" ] }, "type": { "type": "string", "enum": [ "model" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "end" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" } ] } } }, "required": [ "elements" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "elements": { "type": "array", "items": { "oneOf": [ { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "next": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "next" ] }, "type": { "type": "string", "enum": [ "start" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "false": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "true": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "true", "false" ] }, "properties": { "type": "object", "properties": { "conditions": { "type": "object" } } }, "type": { "type": "string", "enum": [ "conditional" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "percentage" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "key": { "type": "string" }, "limit": { "type": "number" }, "limitType": { "enum": [ "count", "cost" ], "type": "string" }, "window": { "type": "number" } }, "required": [ "limitType", "key", "limit", "window" ] }, "type": { "type": "string", "enum": [ "rate" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "retries": { "type": "number" }, "timeout": { "type": "number" } }, "required": [ "provider", "model", "timeout", "retries" ] }, "type": { "type": "string", "enum": [ "model" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "end" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" } ] } }, "gateway_id": { "type": "string" }, "id": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" } }, "required": [ "id", "name", "elements", "created_at", "modified_at", "gateway_id" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Dynamic Routes" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing", "x-fern-sdk-method-name": "create-version", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/routes/{id}/versions/{version_id}": { "get": { "operationId": "aig-config-get-gateway-dynamic-route-version", "summary": "Get an AI Gateway Dynamic Route Version.", "description": "Get an AI Gateway Dynamic Route Version.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } }, { "name": "gateway_id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "example": "54442216" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "active": { "type": "string", "enum": [ "true", "false" ] }, "created_at": { "type": "string" }, "data": { "type": "string" }, "elements": { "type": "array", "items": { "oneOf": [ { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "next": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "next" ] }, "type": { "type": "string", "enum": [ "start" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "false": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "true": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "true", "false" ] }, "properties": { "type": "object", "properties": { "conditions": { "type": "object" } } }, "type": { "type": "string", "enum": [ "conditional" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "percentage" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "key": { "type": "string" }, "limit": { "type": "number" }, "limitType": { "enum": [ "count", "cost" ], "type": "string" }, "window": { "type": "number" } }, "required": [ "limitType", "key", "limit", "window" ] }, "type": { "type": "string", "enum": [ "rate" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "properties": { "fallback": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] }, "success": { "type": "object", "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ] } }, "required": [ "success", "fallback" ] }, "properties": { "type": "object", "properties": { "model": { "type": "string" }, "provider": { "type": "string" }, "retries": { "type": "number" }, "timeout": { "type": "number" } }, "required": [ "provider", "model", "timeout", "retries" ] }, "type": { "type": "string", "enum": [ "model" ] } }, "required": [ "id", "outputs", "type", "properties" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "outputs": { "type": "object", "additionalProperties": { "properties": { "elementId": { "type": "string" } }, "required": [ "elementId" ], "type": "object" } }, "type": { "type": "string", "enum": [ "end" ] } }, "required": [ "id", "outputs", "type" ], "type": "object" } ] } }, "gateway_id": { "type": "string" }, "id": { "type": "string" }, "is_valid": { "type": "boolean" }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "version_id": { "type": "string" } }, "required": [ "id", "name", "elements", "created_at", "modified_at", "gateway_id", "version_id", "data", "active" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Dynamic Routes" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.dynamic-routing", "x-fern-sdk-method-name": "get-version", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/url/{provider}": { "get": { "operationId": "aig-config-get-gateway-url", "summary": "Get Gateway URL", "description": "Retrieves the endpoint URL for an AI Gateway.", "parameters": [ { "name": "gateway_id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "0d37909e38d3e99c29fa2cd343ac421a" } }, { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "example": "workers-ai" } } ], "responses": { "200": { "description": "Returns the log details", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string" }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Gateways" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.urls", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/gateways/{id}": { "delete": { "operationId": "aig-config-delete-gateway", "summary": "Delete a Gateway", "description": "Deletes an AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } } ], "responses": { "200": { "description": "Returns the Object if it was successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "authentication": { "type": "boolean", "x-auditable": true }, "byok_only": { "description": "Requires customer-provided provider credentials and prevents fallback to Unified Billing.", "type": "boolean", "x-auditable": true }, "cache_invalidate_on_update": { "type": "boolean", "x-auditable": true }, "cache_ttl": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "collect_logs": { "type": "boolean", "x-auditable": true }, "created_at": { "type": "string", "format": "date-time" }, "dlp": { "anyOf": [ { "properties": { "action": { "type": "string", "enum": [ "BLOCK", "FLAG" ] }, "enabled": { "type": "boolean" }, "profiles": { "type": "array", "items": { "type": "string" } } }, "required": [ "profiles", "enabled", "action" ], "type": "object" }, { "properties": { "enabled": { "type": "boolean" }, "policies": { "type": "array", "items": { "properties": { "action": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "check": { "type": "array", "items": { "enum": [ "REQUEST", "RESPONSE" ], "type": "string" } }, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "enabled", "action", "profiles", "check" ], "type": "object" } } }, "required": [ "enabled", "policies" ], "type": "object" } ] }, "guardrails": { "type": "object", "nullable": true, "properties": { "prompt": { "type": "object", "properties": { "P1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S10": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S11": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S12": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S13": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S2": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S3": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S4": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S5": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S6": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S7": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S8": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S9": { "type": "string", "enum": [ "FLAG", "BLOCK" ] } } }, "response": { "type": "object", "properties": { "P1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S10": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S11": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S12": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S13": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S2": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S3": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S4": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S5": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S6": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S7": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S8": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S9": { "type": "string", "enum": [ "FLAG", "BLOCK" ] } } } }, "required": [ "prompt", "response" ], "x-auditable": true }, "id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "is_default": { "type": "boolean", "x-auditable": true }, "log_classification": { "type": "boolean", "x-auditable": true }, "log_management": { "type": "integer", "maximum": 10000000, "minimum": 10000, "nullable": true, "x-auditable": true }, "log_management_strategy": { "type": "string", "enum": [ "STOP_INSERTING", "DELETE_OLDEST" ], "nullable": true, "x-auditable": true }, "logpush": { "type": "boolean", "x-auditable": true }, "logpush_public_key": { "type": "string", "maxLength": 1024, "minLength": 16, "nullable": true, "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "otel": { "type": "array", "items": { "properties": { "authorization": { "type": "string", "maxLength": 256 }, "content_type": { "type": "string", "default": "json", "enum": [ "json", "protobuf" ] }, "headers": { "type": "object", "additionalProperties": { "maxLength": 4096, "type": "string" } }, "url": { "type": "string", "format": "uri", "maxLength": 2048 } }, "required": [ "url", "headers" ], "type": "object" }, "maxItems": 5, "nullable": true, "x-auditable": true }, "rate_limiting_interval": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "rate_limiting_limit": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "rate_limiting_technique": { "type": "string", "enum": [ "fixed", "sliding" ], "nullable": true, "x-auditable": true }, "retry_backoff": { "description": "Backoff strategy for retry delays", "type": "string", "enum": [ "constant", "linear", "exponential" ], "nullable": true, "x-auditable": true }, "retry_delay": { "description": "Delay between retry attempts in milliseconds (0-60000)", "type": "integer", "maximum": 60000, "minimum": 0, "nullable": true, "x-auditable": true }, "retry_max_attempts": { "description": "Maximum number of retry attempts for failed requests (1-5)", "type": "integer", "maximum": 5, "minimum": 1, "nullable": true, "x-auditable": true }, "spend_limits": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean", "default": false }, "rules": { "type": "array", "items": { "properties": { "enabled": { "type": "boolean", "default": true }, "id": { "type": "string", "default": "606973a2", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "limit": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "limitType": { "type": "string", "enum": [ "cost" ] }, "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "properties": { "mode": { "type": "string", "enum": [ "partition" ] } }, "required": [ "mode" ], "type": "object" }, { "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ], "type": "object" } ] } }, "model": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ] }, "provider": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ] }, "technique": { "type": "string", "default": "sliding", "enum": [ "fixed", "sliding" ] }, "window": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 } }, "required": [ "limitType", "limit", "window" ], "type": "object" }, "default": [], "maxItems": 20 } }, "x-auditable": true }, "store_id": { "type": "string", "nullable": true }, "stripe": { "type": "object", "nullable": true, "properties": { "authorization": { "type": "string" }, "usage_events": { "type": "array", "items": { "properties": { "payload": { "type": "string" } }, "required": [ "payload" ], "type": "object" } } }, "required": [ "authorization", "usage_events" ], "x-auditable": true }, "workers_ai_billing_mode": { "description": "Controls how Workers AI inference calls routed through this gateway are billed. 'postpaid' bills the account directly through Workers AI; 'unified' deducts credits via AI Gateway using neuron-based pricing and delegates billing to AI Gateway.", "type": "string", "default": "postpaid", "enum": [ "postpaid", "unified" ], "x-auditable": true }, "zdr": { "type": "boolean", "x-auditable": true } }, "required": [ "id", "rate_limiting_interval", "rate_limiting_limit", "collect_logs", "cache_ttl", "cache_invalidate_on_update", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Gateways" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.gateways", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "aig-config-fetch-gateway", "summary": "Fetch a Gateway", "description": "Retrieves details for a specific AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } } ], "responses": { "200": { "description": "Returns a single object if found", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "authentication": { "type": "boolean", "x-auditable": true }, "byok_only": { "description": "Requires customer-provided provider credentials and prevents fallback to Unified Billing.", "type": "boolean", "x-auditable": true }, "cache_invalidate_on_update": { "type": "boolean", "x-auditable": true }, "cache_ttl": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "collect_logs": { "type": "boolean", "x-auditable": true }, "created_at": { "type": "string", "format": "date-time" }, "dlp": { "anyOf": [ { "properties": { "action": { "type": "string", "enum": [ "BLOCK", "FLAG" ] }, "enabled": { "type": "boolean" }, "profiles": { "type": "array", "items": { "type": "string" } } }, "required": [ "profiles", "enabled", "action" ], "type": "object" }, { "properties": { "enabled": { "type": "boolean" }, "policies": { "type": "array", "items": { "properties": { "action": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "check": { "type": "array", "items": { "enum": [ "REQUEST", "RESPONSE" ], "type": "string" } }, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "enabled", "action", "profiles", "check" ], "type": "object" } } }, "required": [ "enabled", "policies" ], "type": "object" } ] }, "guardrails": { "type": "object", "nullable": true, "properties": { "prompt": { "type": "object", "properties": { "P1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S10": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S11": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S12": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S13": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S2": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S3": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S4": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S5": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S6": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S7": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S8": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S9": { "type": "string", "enum": [ "FLAG", "BLOCK" ] } } }, "response": { "type": "object", "properties": { "P1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S10": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S11": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S12": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S13": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S2": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S3": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S4": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S5": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S6": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S7": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S8": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S9": { "type": "string", "enum": [ "FLAG", "BLOCK" ] } } } }, "required": [ "prompt", "response" ], "x-auditable": true }, "id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "is_default": { "type": "boolean", "x-auditable": true }, "log_classification": { "type": "boolean", "x-auditable": true }, "log_management": { "type": "integer", "maximum": 10000000, "minimum": 10000, "nullable": true, "x-auditable": true }, "log_management_strategy": { "type": "string", "enum": [ "STOP_INSERTING", "DELETE_OLDEST" ], "nullable": true, "x-auditable": true }, "logpush": { "type": "boolean", "x-auditable": true }, "logpush_public_key": { "type": "string", "maxLength": 1024, "minLength": 16, "nullable": true, "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "otel": { "type": "array", "items": { "properties": { "authorization": { "type": "string", "maxLength": 256 }, "content_type": { "type": "string", "default": "json", "enum": [ "json", "protobuf" ] }, "headers": { "type": "object", "additionalProperties": { "maxLength": 4096, "type": "string" } }, "url": { "type": "string", "format": "uri", "maxLength": 2048 } }, "required": [ "url", "headers" ], "type": "object" }, "maxItems": 5, "nullable": true, "x-auditable": true }, "rate_limiting_interval": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "rate_limiting_limit": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "rate_limiting_technique": { "type": "string", "enum": [ "fixed", "sliding" ], "nullable": true, "x-auditable": true }, "retry_backoff": { "description": "Backoff strategy for retry delays", "type": "string", "enum": [ "constant", "linear", "exponential" ], "nullable": true, "x-auditable": true }, "retry_delay": { "description": "Delay between retry attempts in milliseconds (0-60000)", "type": "integer", "maximum": 60000, "minimum": 0, "nullable": true, "x-auditable": true }, "retry_max_attempts": { "description": "Maximum number of retry attempts for failed requests (1-5)", "type": "integer", "maximum": 5, "minimum": 1, "nullable": true, "x-auditable": true }, "spend_limits": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean", "default": false }, "rules": { "type": "array", "items": { "properties": { "enabled": { "type": "boolean", "default": true }, "id": { "type": "string", "default": "0621f3c6", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "limit": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "limitType": { "type": "string", "enum": [ "cost" ] }, "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "properties": { "mode": { "type": "string", "enum": [ "partition" ] } }, "required": [ "mode" ], "type": "object" }, { "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ], "type": "object" } ] } }, "model": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ] }, "provider": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ] }, "technique": { "type": "string", "default": "sliding", "enum": [ "fixed", "sliding" ] }, "window": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 } }, "required": [ "limitType", "limit", "window" ], "type": "object" }, "default": [], "maxItems": 20 } }, "x-auditable": true }, "store_id": { "type": "string", "nullable": true }, "stripe": { "type": "object", "nullable": true, "properties": { "authorization": { "type": "string" }, "usage_events": { "type": "array", "items": { "properties": { "payload": { "type": "string" } }, "required": [ "payload" ], "type": "object" } } }, "required": [ "authorization", "usage_events" ], "x-auditable": true }, "workers_ai_billing_mode": { "description": "Controls how Workers AI inference calls routed through this gateway are billed. 'postpaid' bills the account directly through Workers AI; 'unified' deducts credits via AI Gateway using neuron-based pricing and delegates billing to AI Gateway.", "type": "string", "default": "postpaid", "enum": [ "postpaid", "unified" ], "x-auditable": true }, "zdr": { "type": "boolean", "x-auditable": true } }, "required": [ "id", "rate_limiting_interval", "rate_limiting_limit", "collect_logs", "cache_ttl", "cache_invalidate_on_update", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Gateways" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.gateways", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "aig-config-update-gateway", "summary": "Update a Gateway", "description": "Updates an existing AI Gateway dataset.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "3ebbcb006d4d46d7bb6a8c7f14676cb0" } }, { "name": "id", "in": "path", "required": true, "schema": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "authentication": { "type": "boolean", "x-auditable": true }, "byok_only": { "description": "Requires customer-provided provider credentials and prevents fallback to Unified Billing.", "type": "boolean", "x-auditable": true }, "cache_invalidate_on_update": { "type": "boolean", "x-auditable": true }, "cache_ttl": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "collect_logs": { "type": "boolean", "x-auditable": true }, "dlp": { "anyOf": [ { "properties": { "action": { "type": "string", "enum": [ "BLOCK", "FLAG" ] }, "enabled": { "type": "boolean" }, "profiles": { "type": "array", "items": { "type": "string" } } }, "required": [ "profiles", "enabled", "action" ], "type": "object" }, { "properties": { "enabled": { "type": "boolean" }, "policies": { "type": "array", "items": { "properties": { "action": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "check": { "type": "array", "items": { "enum": [ "REQUEST", "RESPONSE" ], "type": "string" } }, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "enabled", "action", "profiles", "check" ], "type": "object" } } }, "required": [ "enabled", "policies" ], "type": "object" } ] }, "guardrails": { "type": "object", "nullable": true, "properties": { "prompt": { "type": "object", "properties": { "P1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S10": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S11": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S12": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S13": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S2": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S3": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S4": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S5": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S6": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S7": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S8": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S9": { "type": "string", "enum": [ "FLAG", "BLOCK" ] } } }, "response": { "type": "object", "properties": { "P1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S10": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S11": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S12": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S13": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S2": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S3": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S4": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S5": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S6": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S7": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S8": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S9": { "type": "string", "enum": [ "FLAG", "BLOCK" ] } } } }, "required": [ "prompt", "response" ], "x-auditable": true }, "log_classification": { "type": "boolean", "x-auditable": true }, "log_management": { "type": "integer", "maximum": 10000000, "minimum": 10000, "nullable": true, "x-auditable": true }, "log_management_strategy": { "type": "string", "enum": [ "STOP_INSERTING", "DELETE_OLDEST" ], "nullable": true, "x-auditable": true }, "logpush": { "type": "boolean", "x-auditable": true }, "logpush_public_key": { "type": "string", "maxLength": 1024, "minLength": 16, "nullable": true, "x-auditable": true }, "otel": { "type": "array", "items": { "properties": { "authorization": { "type": "string", "maxLength": 256 }, "content_type": { "type": "string", "default": "json", "enum": [ "json", "protobuf" ] }, "headers": { "type": "object", "additionalProperties": { "maxLength": 4096, "type": "string" } }, "url": { "type": "string", "format": "uri", "maxLength": 2048 } }, "required": [ "url", "headers" ], "type": "object" }, "maxItems": 5, "nullable": true, "x-auditable": true }, "rate_limiting_interval": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "rate_limiting_limit": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "rate_limiting_technique": { "type": "string", "enum": [ "fixed", "sliding" ], "nullable": true, "x-auditable": true }, "retry_backoff": { "description": "Backoff strategy for retry delays", "type": "string", "enum": [ "constant", "linear", "exponential" ], "nullable": true, "x-auditable": true }, "retry_delay": { "description": "Delay between retry attempts in milliseconds (0-60000)", "type": "integer", "maximum": 60000, "minimum": 0, "nullable": true, "x-auditable": true }, "retry_max_attempts": { "description": "Maximum number of retry attempts for failed requests (1-5)", "type": "integer", "maximum": 5, "minimum": 1, "nullable": true, "x-auditable": true }, "spend_limits": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean", "default": false }, "rules": { "type": "array", "items": { "properties": { "enabled": { "type": "boolean", "default": true }, "id": { "type": "string", "default": "91caa4d5", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "limit": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "limitType": { "type": "string", "enum": [ "cost" ] }, "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "properties": { "mode": { "type": "string", "enum": [ "partition" ] } }, "required": [ "mode" ], "type": "object" }, { "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ], "type": "object" } ] } }, "model": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ] }, "provider": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ] }, "technique": { "type": "string", "default": "sliding", "enum": [ "fixed", "sliding" ] }, "window": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 } }, "required": [ "limitType", "limit", "window" ], "type": "object" }, "default": [], "maxItems": 20 } }, "x-auditable": true }, "store_id": { "type": "string", "nullable": true }, "stripe": { "type": "object", "nullable": true, "properties": { "authorization": { "type": "string" }, "usage_events": { "type": "array", "items": { "properties": { "payload": { "type": "string" } }, "required": [ "payload" ], "type": "object" } } }, "required": [ "authorization", "usage_events" ], "x-auditable": true }, "workers_ai_billing_mode": { "description": "Controls how Workers AI inference calls routed through this gateway are billed. 'postpaid' bills the account directly through Workers AI; 'unified' deducts credits via AI Gateway using neuron-based pricing and delegates billing to AI Gateway.", "type": "string", "default": "postpaid", "enum": [ "postpaid", "unified" ], "x-auditable": true }, "zdr": { "type": "boolean", "x-auditable": true } }, "required": [ "rate_limiting_interval", "rate_limiting_limit", "collect_logs", "cache_ttl", "cache_invalidate_on_update" ] } } } }, "responses": { "200": { "description": "Returns the updated Object", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "authentication": { "type": "boolean", "x-auditable": true }, "byok_only": { "description": "Requires customer-provided provider credentials and prevents fallback to Unified Billing.", "type": "boolean", "x-auditable": true }, "cache_invalidate_on_update": { "type": "boolean", "x-auditable": true }, "cache_ttl": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "collect_logs": { "type": "boolean", "x-auditable": true }, "created_at": { "type": "string", "format": "date-time" }, "dlp": { "anyOf": [ { "properties": { "action": { "type": "string", "enum": [ "BLOCK", "FLAG" ] }, "enabled": { "type": "boolean" }, "profiles": { "type": "array", "items": { "type": "string" } } }, "required": [ "profiles", "enabled", "action" ], "type": "object" }, { "properties": { "enabled": { "type": "boolean" }, "policies": { "type": "array", "items": { "properties": { "action": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "check": { "type": "array", "items": { "enum": [ "REQUEST", "RESPONSE" ], "type": "string" } }, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "enabled", "action", "profiles", "check" ], "type": "object" } } }, "required": [ "enabled", "policies" ], "type": "object" } ] }, "guardrails": { "type": "object", "nullable": true, "properties": { "prompt": { "type": "object", "properties": { "P1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S10": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S11": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S12": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S13": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S2": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S3": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S4": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S5": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S6": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S7": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S8": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S9": { "type": "string", "enum": [ "FLAG", "BLOCK" ] } } }, "response": { "type": "object", "properties": { "P1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S1": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S10": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S11": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S12": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S13": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S2": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S3": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S4": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S5": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S6": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S7": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S8": { "type": "string", "enum": [ "FLAG", "BLOCK" ] }, "S9": { "type": "string", "enum": [ "FLAG", "BLOCK" ] } } } }, "required": [ "prompt", "response" ], "x-auditable": true }, "id": { "description": "gateway id", "type": "string", "example": "my-gateway", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "is_default": { "type": "boolean", "x-auditable": true }, "log_classification": { "type": "boolean", "x-auditable": true }, "log_management": { "type": "integer", "maximum": 10000000, "minimum": 10000, "nullable": true, "x-auditable": true }, "log_management_strategy": { "type": "string", "enum": [ "STOP_INSERTING", "DELETE_OLDEST" ], "nullable": true, "x-auditable": true }, "logpush": { "type": "boolean", "x-auditable": true }, "logpush_public_key": { "type": "string", "maxLength": 1024, "minLength": 16, "nullable": true, "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "otel": { "type": "array", "items": { "properties": { "authorization": { "type": "string", "maxLength": 256 }, "content_type": { "type": "string", "default": "json", "enum": [ "json", "protobuf" ] }, "headers": { "type": "object", "additionalProperties": { "maxLength": 4096, "type": "string" } }, "url": { "type": "string", "format": "uri", "maxLength": 2048 } }, "required": [ "url", "headers" ], "type": "object" }, "maxItems": 5, "nullable": true, "x-auditable": true }, "rate_limiting_interval": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "rate_limiting_limit": { "type": "integer", "minimum": 0, "nullable": true, "x-auditable": true }, "rate_limiting_technique": { "type": "string", "enum": [ "fixed", "sliding" ], "nullable": true, "x-auditable": true }, "retry_backoff": { "description": "Backoff strategy for retry delays", "type": "string", "enum": [ "constant", "linear", "exponential" ], "nullable": true, "x-auditable": true }, "retry_delay": { "description": "Delay between retry attempts in milliseconds (0-60000)", "type": "integer", "maximum": 60000, "minimum": 0, "nullable": true, "x-auditable": true }, "retry_max_attempts": { "description": "Maximum number of retry attempts for failed requests (1-5)", "type": "integer", "maximum": 5, "minimum": 1, "nullable": true, "x-auditable": true }, "spend_limits": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean", "default": false }, "rules": { "type": "array", "items": { "properties": { "enabled": { "type": "boolean", "default": true }, "id": { "type": "string", "default": "e5855234", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "limit": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "limitType": { "type": "string", "enum": [ "cost" ] }, "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "properties": { "mode": { "type": "string", "enum": [ "partition" ] } }, "required": [ "mode" ], "type": "object" }, { "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ], "type": "object" } ] } }, "model": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ] }, "provider": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "filter" ] }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "values" ] }, "technique": { "type": "string", "default": "sliding", "enum": [ "fixed", "sliding" ] }, "window": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 } }, "required": [ "limitType", "limit", "window" ], "type": "object" }, "default": [], "maxItems": 20 } }, "x-auditable": true }, "store_id": { "type": "string", "nullable": true }, "stripe": { "type": "object", "nullable": true, "properties": { "authorization": { "type": "string" }, "usage_events": { "type": "array", "items": { "properties": { "payload": { "type": "string" } }, "required": [ "payload" ], "type": "object" } } }, "required": [ "authorization", "usage_events" ], "x-auditable": true }, "workers_ai_billing_mode": { "description": "Controls how Workers AI inference calls routed through this gateway are billed. 'postpaid' bills the account directly through Workers AI; 'unified' deducts credits via AI Gateway using neuron-based pricing and delegates billing to AI Gateway.", "type": "string", "default": "postpaid", "enum": [ "postpaid", "unified" ], "x-auditable": true }, "zdr": { "type": "boolean", "x-auditable": true } }, "required": [ "id", "rate_limiting_interval", "rate_limiting_limit", "collect_logs", "cache_ttl", "cache_invalidate_on_update", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7001 }, "message": { "type": "string", "example": "Input Validation Error" }, "path": { "type": "array", "items": { "example": "body", "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Gateway Gateways" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-gateway.gateways", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/ai-gateway/logging-state": { "get": { "operationId": "aig-config-get-logging-state", "summary": "Get AI Gateway logging state", "description": "Returns the canonical logging platform and migration availability for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the account logging state", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "migrated_at": { "type": "integer", "minimum": 0, "nullable": true }, "migration_available": { "type": "boolean" }, "platform": { "type": "string", "enum": [ "legacy", "workers_observability" ] } }, "required": [ "platform", "migrated_at", "migration_available" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } }, "503": { "description": "Logging state is temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "result", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Account" ], "x-api-token-group": [ "AI Gateway Write", "AI Gateway Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "ai-gateway.logging-state", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "aig-config-patch-logging-state", "summary": "Migrate AI Gateway logging to Workers Observability", "description": "Irreversibly migrates an eligible account to Workers Observability logging.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the migrated account logging state", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "migrated_at": { "type": "integer", "minimum": 0, "nullable": true }, "migration_available": { "type": "boolean" }, "platform": { "type": "string", "enum": [ "legacy", "workers_observability" ] } }, "required": [ "platform", "migrated_at", "migration_available" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "409": { "description": "Migration is not available for this account", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "result", "errors" ] } } } }, "503": { "description": "Logging state is temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "result", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Account" ], "x-api-token-group": [ "AI Gateway Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.aig" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "ai-gateway.logging-state", "x-fern-sdk-method-name": "update" } }, "/accounts/{account_id}/ai-search/instances": { "get": { "operationId": "ai-search-list-instances", "summary": "List AI Search instances.", "description": "List all AI Search instances in the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "page", "in": "query", "description": "Page number (1-indexed).", "schema": { "description": "Page number (1-indexed).", "type": "integer", "example": 1, "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "description": "Number of results per page.", "type": "integer", "example": 20, "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Filter instances whose id contains this string (case-insensitive).", "schema": { "description": "Filter instances whose id contains this string (case-insensitive).", "type": "string", "maxLength": 64 } }, { "name": "namespace", "in": "query", "description": "Filter by namespace.", "schema": { "description": "Filter by namespace.", "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$" } }, { "name": "order_by", "in": "query", "description": "Field to order results by.", "schema": { "description": "Field to order results by.", "type": "string", "default": "created_at", "enum": [ "created_at" ] } }, { "name": "order_by_direction", "in": "query", "description": "Order direction.", "schema": { "description": "Order direction.", "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "List of instances.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "additionalProperties": false, "properties": { "ai_gateway_id": { "type": "string", "nullable": true }, "ai_search_model": { "type": "string", "nullable": true }, "cache": { "type": "boolean" }, "cache_threshold": { "type": "string", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes", null ], "nullable": true }, "cache_ttl": { "anyOf": [ { "enum": [ 600 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" }, { "enum": [ 172800 ], "type": "number" }, { "enum": [ 259200 ], "type": "number" }, { "enum": [ 518400 ], "type": "number" } ] }, "chunk": { "type": "boolean" }, "chunk_overlap": { "type": "number", "nullable": true }, "chunk_size": { "type": "number", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "nullable": true }, "custom_metadata": { "type": "array", "items": { "additionalProperties": false, "properties": { "data_type": { "type": "string", "enum": [ "text", "number", "boolean", "datetime" ] }, "field_name": { "type": "string" } }, "required": [ "field_name", "data_type" ], "type": "object" }, "nullable": true }, "embedding_model": { "type": "string", "nullable": true }, "enable": { "type": "boolean" }, "engine_version": { "type": "number" }, "fusion_method": { "type": "string", "enum": [ "max", "rrf" ] }, "hybrid_search_enabled": { "type": "boolean" }, "id": { "type": "string" }, "index_method": { "type": "object", "additionalProperties": true, "properties": { "keyword": { "type": "boolean" }, "vector": { "type": "boolean" } }, "required": [ "vector", "keyword" ] }, "indexing_options": { "type": "object", "additionalProperties": true, "nullable": true, "properties": { "keyword_tokenizer": { "type": "string", "enum": [ "porter", "trigram" ] }, "use_ocr": { "type": "boolean" } } }, "last_activity": { "type": "string", "format": "date-time", "nullable": true }, "max_num_results": { "type": "number", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "worker_domain": { "type": "string" } } }, "modified_at": { "type": "string", "format": "date-time" }, "modified_by": { "type": "string", "nullable": true }, "namespace": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$" }, "paused": { "type": "boolean" }, "public_endpoint_id": { "type": "string", "nullable": true }, "public_endpoint_params": { "type": "object", "additionalProperties": true, "nullable": true, "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "additionalProperties": true, "properties": { "disabled": { "type": "boolean" } } }, "custom_domains": { "type": "array", "items": { "maxLength": 253, "minLength": 1, "pattern": "^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "type": "string" }, "maxItems": 1, "nullable": true }, "default_domain_enabled": { "type": "boolean" }, "enabled": { "type": "boolean" }, "mcp": { "type": "object", "additionalProperties": true, "properties": { "description": { "type": "string" }, "disabled": { "type": "boolean" } } }, "rate_limit": { "type": "object", "additionalProperties": true, "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "additionalProperties": true, "properties": { "disabled": { "type": "boolean" } } } } }, "reranking": { "type": "boolean" }, "reranking_model": { "type": "string", "nullable": true }, "retrieval_options": { "type": "object", "additionalProperties": true, "nullable": true, "properties": { "boost_by": { "type": "array", "items": { "additionalProperties": true, "properties": { "dataType": { "type": "string", "enum": [ "number", "datetime", "text", "boolean" ] }, "direction": { "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "type": "string", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "maxItems": 3 }, "keyword_match_mode": { "type": "string", "enum": [ "and", "or" ] } } }, "rewrite_model": { "type": "string", "nullable": true }, "rewrite_query": { "type": "boolean" }, "score_threshold": { "type": "number", "nullable": true }, "source": { "type": "string", "nullable": true }, "source_params": { "type": "object", "additionalProperties": true, "nullable": true, "properties": { "exclude_items": { "type": "array", "items": { "type": "string" } }, "include_items": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "string" }, "r2_jurisdiction": { "type": "string" }, "web_crawler": { "type": "object", "additionalProperties": true, "properties": { "discover_options": { "type": "object", "additionalProperties": true, "properties": { "depth": { "type": "number", "maximum": 100000, "minimum": 1 }, "include_external_links": { "type": "boolean" }, "include_subdomains": { "type": "boolean" }, "limit": { "description": "Maximum number of pages to crawl. New values are capped at 100000; instances configured before that cap may report a higher stored value, which the crawler clamps at run time.", "type": "number", "maximum": 100000, "minimum": 1 }, "max_age": { "type": "number", "maximum": 604800, "minimum": 0 }, "source": { "type": "string", "enum": [ "all", "sitemaps", "links" ] } } }, "parse_options": { "type": "object", "additionalProperties": true, "properties": { "content_selector": { "type": "array", "items": { "additionalProperties": true, "properties": { "path": { "type": "string", "maxLength": 200, "minLength": 1 }, "selector": { "type": "string", "maxLength": 200, "minLength": 1 } }, "required": [ "path", "selector" ], "type": "object" }, "maxItems": 10 }, "include_headers": { "type": "object", "additionalProperties": { "maxLength": 8192, "pattern": "^[\\t\\x20-\\x7E]*$", "type": "string" } }, "include_images": { "type": "boolean" }, "specific_sitemaps": { "type": "array", "items": { "format": "uri", "type": "string" }, "maxItems": 10 }, "use_browser_rendering": { "type": "boolean" } } }, "parse_type": { "type": "string", "enum": [ "sitemap", "discover" ] } } } } }, "status": { "type": "string" }, "summarization": { "type": "boolean" }, "summarization_model": { "type": "string", "nullable": true }, "sync_interval": { "anyOf": [ { "enum": [ 900 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 14400 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" } ] }, "system_prompt_ai_search": { "type": "string", "nullable": true }, "system_prompt_index_summarization": { "type": "string", "nullable": true }, "system_prompt_rewrite_query": { "type": "string", "nullable": true }, "token_id": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true } }, "required": [ "id", "engine_version", "enable", "type", "source", "source_params", "ai_gateway_id", "token_id", "cache", "cache_threshold", "cache_ttl", "summarization", "rewrite_query", "reranking", "index_method", "hybrid_search_enabled", "fusion_method", "indexing_options", "retrieval_options", "summarization_model", "embedding_model", "rewrite_model", "ai_search_model", "reranking_model", "system_prompt_ai_search", "system_prompt_index_summarization", "system_prompt_rewrite_query", "chunk", "chunk_size", "chunk_overlap", "score_threshold", "max_num_results", "public_endpoint_id", "public_endpoint_params", "paused", "status", "metadata", "custom_metadata", "sync_interval", "created_at", "created_by", "modified_at", "modified_by", "last_activity", "namespace" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "page", "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "result_info" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "list" }, "post": { "operationId": "ai-search-create-instance", "summary": "Create an AI Search instance.", "description": "Create a new AI Search instance with the given configuration.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_gateway_id": { "type": "string", "nullable": true, "x-auditable": true }, "ai_search_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "cache": { "type": "boolean", "default": true, "x-auditable": true }, "cache_threshold": { "type": "string", "default": "close_enough", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ], "x-auditable": true }, "cache_ttl": { "description": "Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).", "default": 172800, "anyOf": [ { "enum": [ 600 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" }, { "enum": [ 172800 ], "type": "number" }, { "enum": [ 259200 ], "type": "number" }, { "enum": [ 518400 ], "type": "number" } ], "x-auditable": true }, "chunk": { "type": "boolean", "default": true, "x-auditable": true }, "chunk_overlap": { "type": "integer", "default": 10, "maximum": 30, "minimum": 0, "x-auditable": true }, "chunk_size": { "type": "integer", "minimum": 64, "x-auditable": true }, "custom_metadata": { "type": "array", "items": { "properties": { "data_type": { "type": "string", "enum": [ "text", "number", "boolean", "datetime" ] }, "field_name": { "type": "string", "maxLength": 64, "minLength": 1 } }, "required": [ "field_name", "data_type" ], "type": "object" }, "maxItems": 5, "x-auditable": true }, "embedding_model": { "type": "string", "nullable": true, "x-auditable": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead.", "type": "boolean", "default": false, "deprecated": true, "x-auditable": true }, "id": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "index_method": { "description": "Controls which storage backends are used during indexing. Defaults to vector-only.", "type": "object", "default": { "keyword": false, "vector": true }, "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean" } }, "required": [ "vector", "keyword" ], "x-auditable": true }, "indexing_options": { "type": "object", "nullable": true, "properties": { "keyword_tokenizer": { "description": "Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.", "type": "string", "default": "porter", "enum": [ "porter", "trigram" ] }, "use_ocr": { "description": "Enables OCR ingestion for PDFs and images. Changing this triggers a full re-index. Defaults to false.", "type": "boolean", "default": false } }, "x-auditable": true }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1, "x-auditable": true }, "metadata": { "type": "object", "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "worker_domain": { "type": "string" } }, "x-auditable": true }, "public_endpoint_params": { "type": "object", "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } }, "x-auditable": true }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true }, "retrieval_options": { "type": "object", "nullable": true, "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ] } }, "x-auditable": true }, "rewrite_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0, "x-auditable": true }, "source": { "type": "string", "nullable": true, "x-auditable": true }, "source_params": { "type": "object", "nullable": true, "properties": { "exclude_items": { "description": "List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/admin/**", "/private/**", "**\\temp\\**" ], "maxItems": 10 }, "include_items": { "description": "List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/blog/**", "/docs/**/*.html", "**\\blog\\**.html" ], "maxItems": 10 }, "prefix": { "type": "string" }, "r2_jurisdiction": { "type": "string", "default": "default" }, "web_crawler": { "type": "object", "default": { "parse_type": "sitemap" }, "properties": { "discover_options": { "description": "Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'.", "type": "object", "properties": { "depth": { "description": "Maximum link-follow depth from the seed URL.", "type": "number", "example": 5, "default": 5, "maximum": 100000, "minimum": 1 }, "include_external_links": { "description": "Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own.", "type": "boolean", "example": false, "default": false }, "include_subdomains": { "description": "Follow links to subdomains of the source host.", "type": "boolean", "example": false, "default": false }, "limit": { "description": "Maximum number of pages to crawl (1-100000).", "type": "number", "example": 10000, "default": 100000, "maximum": 100000, "minimum": 1 }, "max_age": { "description": "Maximum content age in seconds to accept (0–604800).", "type": "number", "example": 86400, "default": 86400, "maximum": 604800, "minimum": 0 }, "source": { "description": "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both.", "type": "string", "example": "all", "default": "all", "enum": [ "all", "sitemaps", "links" ] } } }, "parse_options": { "type": "object", "properties": { "content_selector": { "description": "List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected.", "type": "array", "items": { "properties": { "path": { "description": "Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.", "type": "string", "example": "**/article/**", "maxLength": 200, "minLength": 1 }, "selector": { "description": "CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \\). Must target a single element; if multiple elements match, the selector is ignored and the full page is used.", "type": "string", "example": "article div.post-body", "maxLength": 200, "minLength": 1 } }, "required": [ "path", "selector" ], "type": "object" }, "example": [ { "path": "**/blog/**", "selector": "article div.post-body" }, { "path": "**/docs/**", "selector": "main" } ], "maxItems": 10, "minItems": 1 }, "include_headers": { "description": "Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF).", "type": "object", "example": { "cache-control": "no-cache, no-store" }, "additionalProperties": { "maxLength": 8192, "pattern": "^[\\t\\x20-\\x7E]*$", "type": "string" } }, "include_images": { "type": "boolean", "default": false }, "specific_sitemaps": { "description": "List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.", "type": "array", "items": { "format": "uri", "type": "string" }, "example": [ "https://example.com/sitemap.xml", "https://example.com/blog-sitemap.xml" ], "maxItems": 10 }, "use_browser_rendering": { "type": "boolean", "default": true } } }, "parse_type": { "description": "How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true }, "sync_interval": { "description": "Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).", "default": 21600, "anyOf": [ { "enum": [ 900 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 14400 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" } ], "x-auditable": true }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true }, "type": { "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true } }, "required": [ "id" ] } } } }, "responses": { "201": { "description": "Returns the new instance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "ai_gateway_id": { "type": "string", "nullable": true, "x-auditable": true }, "ai_search_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "cache": { "type": "boolean", "default": true, "x-auditable": true }, "cache_threshold": { "type": "string", "default": "close_enough", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ], "x-auditable": true }, "cache_ttl": { "description": "Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).", "default": 172800, "anyOf": [ { "enum": [ 600 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" }, { "enum": [ 172800 ], "type": "number" }, { "enum": [ 259200 ], "type": "number" }, { "enum": [ 518400 ], "type": "number" } ], "x-auditable": true }, "chunk_overlap": { "type": "integer", "default": 10, "maximum": 30, "minimum": 0, "x-auditable": true }, "chunk_size": { "type": "integer", "minimum": 64, "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "nullable": true, "readOnly": true }, "custom_metadata": { "type": "array", "items": { "properties": { "data_type": { "type": "string", "enum": [ "text", "number", "boolean", "datetime" ] }, "field_name": { "type": "string", "maxLength": 64, "minLength": 1 } }, "required": [ "field_name", "data_type" ], "type": "object" }, "maxItems": 5, "x-auditable": true }, "embedding_model": { "type": "string", "nullable": true, "x-auditable": true }, "enable": { "type": "boolean", "default": true, "x-auditable": true }, "engine_version": { "type": "number", "default": 3, "readOnly": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead.", "type": "boolean", "default": false, "deprecated": true, "x-auditable": true }, "id": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "index_method": { "description": "Controls which storage backends are used during indexing. Defaults to vector-only.", "type": "object", "default": { "keyword": false, "vector": true }, "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean" } }, "required": [ "vector", "keyword" ], "x-auditable": true }, "indexing_options": { "type": "object", "nullable": true, "properties": { "keyword_tokenizer": { "description": "Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.", "type": "string", "default": "porter", "enum": [ "porter", "trigram" ] }, "use_ocr": { "description": "Enables OCR ingestion for PDFs and images. Changing this triggers a full re-index. Defaults to false.", "type": "boolean", "default": false } }, "x-auditable": true }, "last_activity": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1, "x-auditable": true }, "metadata": { "type": "object", "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "worker_domain": { "type": "string" } }, "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "nullable": true, "readOnly": true }, "namespace": { "type": "string", "nullable": true, "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$", "readOnly": true }, "paused": { "type": "boolean", "default": false, "x-auditable": true }, "public_endpoint_id": { "type": "string", "nullable": true, "readOnly": true }, "public_endpoint_params": { "type": "object", "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } }, "x-auditable": true }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true }, "retrieval_options": { "type": "object", "nullable": true, "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ] } }, "x-auditable": true }, "rewrite_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0, "x-auditable": true }, "source": { "type": "string", "nullable": true, "x-auditable": true }, "source_params": { "type": "object", "nullable": true, "properties": { "exclude_items": { "description": "List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/admin/**", "/private/**", "**\\temp\\**" ], "maxItems": 10 }, "include_items": { "description": "List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/blog/**", "/docs/**/*.html", "**\\blog\\**.html" ], "maxItems": 10 }, "prefix": { "type": "string" }, "r2_jurisdiction": { "type": "string", "default": "default" }, "web_crawler": { "type": "object", "default": { "parse_type": "sitemap" }, "properties": { "discover_options": { "description": "Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'.", "type": "object", "properties": { "depth": { "description": "Maximum link-follow depth from the seed URL.", "type": "number", "example": 5, "default": 5, "maximum": 100000, "minimum": 1 }, "include_external_links": { "description": "Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own.", "type": "boolean", "example": false, "default": false }, "include_subdomains": { "description": "Follow links to subdomains of the source host.", "type": "boolean", "example": false, "default": false }, "limit": { "description": "Maximum number of pages to crawl (1-100000).", "type": "number", "example": 10000, "default": 100000, "maximum": 100000, "minimum": 1 }, "max_age": { "description": "Maximum content age in seconds to accept (0–604800).", "type": "number", "example": 86400, "default": 86400, "maximum": 604800, "minimum": 0 }, "source": { "description": "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both.", "type": "string", "example": "all", "default": "all", "enum": [ "all", "sitemaps", "links" ] } } }, "parse_options": { "type": "object", "properties": { "content_selector": { "description": "List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected.", "type": "array", "items": { "properties": { "path": { "description": "Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.", "type": "string", "example": "**/article/**", "maxLength": 200, "minLength": 1 }, "selector": { "description": "CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \\). Must target a single element; if multiple elements match, the selector is ignored and the full page is used.", "type": "string", "example": "article div.post-body", "maxLength": 200, "minLength": 1 } }, "required": [ "path", "selector" ], "type": "object" }, "example": [ { "path": "**/blog/**", "selector": "article div.post-body" }, { "path": "**/docs/**", "selector": "main" } ], "maxItems": 10, "minItems": 1 }, "include_headers": { "description": "Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF).", "type": "object", "example": { "cache-control": "no-cache, no-store" }, "additionalProperties": { "maxLength": 8192, "pattern": "^[\\t\\x20-\\x7E]*$", "type": "string" } }, "include_images": { "type": "boolean", "default": false }, "specific_sitemaps": { "description": "List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.", "type": "array", "items": { "format": "uri", "type": "string" }, "example": [ "https://example.com/sitemap.xml", "https://example.com/blog-sitemap.xml" ], "maxItems": 10 }, "use_browser_rendering": { "type": "boolean", "default": true } } }, "parse_type": { "description": "How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true }, "status": { "type": "string", "default": "waiting", "readOnly": true }, "sync_interval": { "description": "Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).", "default": 21600, "anyOf": [ { "enum": [ 900 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 14400 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" } ], "x-auditable": true }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true }, "type": { "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true } }, "required": [ "id", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Ai search instance invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "403": { "description": "Max instances reached.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "create" } }, "/accounts/{account_id}/ai-search/instances/{id}": { "delete": { "operationId": "ai-search-delete-instance", "summary": "Delete an AI Search instance.", "description": "Permanently delete an AI Search instance and all its indexed data.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "my-ai-search" } } ], "responses": { "200": { "description": "Returns the deleted instance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "ai_gateway_id": { "type": "string", "nullable": true, "x-auditable": true }, "ai_search_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "cache": { "type": "boolean", "default": true, "x-auditable": true }, "cache_threshold": { "type": "string", "default": "close_enough", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ], "x-auditable": true }, "cache_ttl": { "description": "Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).", "default": 172800, "anyOf": [ { "enum": [ 600 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" }, { "enum": [ 172800 ], "type": "number" }, { "enum": [ 259200 ], "type": "number" }, { "enum": [ 518400 ], "type": "number" } ], "x-auditable": true }, "chunk_overlap": { "type": "integer", "default": 10, "maximum": 30, "minimum": 0, "x-auditable": true }, "chunk_size": { "type": "integer", "minimum": 64, "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "nullable": true, "readOnly": true }, "custom_metadata": { "type": "array", "items": { "properties": { "data_type": { "type": "string", "enum": [ "text", "number", "boolean", "datetime" ] }, "field_name": { "type": "string", "maxLength": 64, "minLength": 1 } }, "required": [ "field_name", "data_type" ], "type": "object" }, "maxItems": 5, "x-auditable": true }, "embedding_model": { "type": "string", "nullable": true, "x-auditable": true }, "enable": { "type": "boolean", "default": true, "x-auditable": true }, "engine_version": { "type": "number", "default": 3, "readOnly": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead.", "type": "boolean", "default": false, "deprecated": true, "x-auditable": true }, "id": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "index_method": { "description": "Controls which storage backends are used during indexing. Defaults to vector-only.", "type": "object", "default": { "keyword": false, "vector": true }, "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean" } }, "required": [ "vector", "keyword" ], "x-auditable": true }, "indexing_options": { "type": "object", "nullable": true, "properties": { "keyword_tokenizer": { "description": "Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.", "type": "string", "default": "porter", "enum": [ "porter", "trigram" ] }, "use_ocr": { "description": "Enables OCR ingestion for PDFs and images. Changing this triggers a full re-index. Defaults to false.", "type": "boolean", "default": false } }, "x-auditable": true }, "last_activity": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1, "x-auditable": true }, "metadata": { "type": "object", "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "worker_domain": { "type": "string" } }, "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "nullable": true, "readOnly": true }, "namespace": { "type": "string", "nullable": true, "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$", "readOnly": true }, "paused": { "type": "boolean", "default": false, "x-auditable": true }, "public_endpoint_id": { "type": "string", "nullable": true, "readOnly": true }, "public_endpoint_params": { "type": "object", "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } }, "x-auditable": true }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true }, "retrieval_options": { "type": "object", "nullable": true, "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ] } }, "x-auditable": true }, "rewrite_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0, "x-auditable": true }, "source": { "type": "string", "nullable": true, "x-auditable": true }, "source_params": { "type": "object", "nullable": true, "properties": { "exclude_items": { "description": "List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/admin/**", "/private/**", "**\\temp\\**" ], "maxItems": 10 }, "include_items": { "description": "List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/blog/**", "/docs/**/*.html", "**\\blog\\**.html" ], "maxItems": 10 }, "prefix": { "type": "string" }, "r2_jurisdiction": { "type": "string", "default": "default" }, "web_crawler": { "type": "object", "default": { "parse_type": "sitemap" }, "properties": { "discover_options": { "description": "Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'.", "type": "object", "properties": { "depth": { "description": "Maximum link-follow depth from the seed URL.", "type": "number", "example": 5, "default": 5, "maximum": 100000, "minimum": 1 }, "include_external_links": { "description": "Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own.", "type": "boolean", "example": false, "default": false }, "include_subdomains": { "description": "Follow links to subdomains of the source host.", "type": "boolean", "example": false, "default": false }, "limit": { "description": "Maximum number of pages to crawl (1-100000).", "type": "number", "example": 10000, "default": 100000, "maximum": 100000, "minimum": 1 }, "max_age": { "description": "Maximum content age in seconds to accept (0–604800).", "type": "number", "example": 86400, "default": 86400, "maximum": 604800, "minimum": 0 }, "source": { "description": "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both.", "type": "string", "example": "all", "default": "all", "enum": [ "all", "sitemaps", "links" ] } } }, "parse_options": { "type": "object", "properties": { "content_selector": { "description": "List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected.", "type": "array", "items": { "properties": { "path": { "description": "Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.", "type": "string", "example": "**/article/**", "maxLength": 200, "minLength": 1 }, "selector": { "description": "CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \\). Must target a single element; if multiple elements match, the selector is ignored and the full page is used.", "type": "string", "example": "article div.post-body", "maxLength": 200, "minLength": 1 } }, "required": [ "path", "selector" ], "type": "object" }, "example": [ { "path": "**/blog/**", "selector": "article div.post-body" }, { "path": "**/docs/**", "selector": "main" } ], "maxItems": 10, "minItems": 1 }, "include_headers": { "description": "Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF).", "type": "object", "example": { "cache-control": "no-cache, no-store" }, "additionalProperties": { "maxLength": 8192, "pattern": "^[\\t\\x20-\\x7E]*$", "type": "string" } }, "include_images": { "type": "boolean", "default": false }, "specific_sitemaps": { "description": "List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.", "type": "array", "items": { "format": "uri", "type": "string" }, "example": [ "https://example.com/sitemap.xml", "https://example.com/blog-sitemap.xml" ], "maxItems": 10 }, "use_browser_rendering": { "type": "boolean", "default": true } } }, "parse_type": { "description": "How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true }, "status": { "type": "string", "default": "waiting", "readOnly": true }, "sync_interval": { "description": "Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).", "default": 21600, "anyOf": [ { "enum": [ 900 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 14400 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" } ], "x-auditable": true }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true }, "type": { "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true } }, "required": [ "id", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "409": { "description": "Instance status modified concurrently please retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "delete", "x-forge-require-confirmation": "This operation permanently deletes the AI Search instance and all its indexed data." }, "get": { "operationId": "ai-search-fetch-instance", "summary": "Get an AI Search instance.", "description": "Retrieve the configuration and status of an AI Search instance.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "my-ai-search" } } ], "responses": { "200": { "description": "Returns the instance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "ai_gateway_id": { "type": "string", "nullable": true, "x-auditable": true }, "ai_search_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "cache": { "type": "boolean", "default": true, "x-auditable": true }, "cache_threshold": { "type": "string", "default": "close_enough", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ], "x-auditable": true }, "cache_ttl": { "description": "Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).", "default": 172800, "anyOf": [ { "enum": [ 600 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" }, { "enum": [ 172800 ], "type": "number" }, { "enum": [ 259200 ], "type": "number" }, { "enum": [ 518400 ], "type": "number" } ], "x-auditable": true }, "chunk_overlap": { "type": "integer", "default": 10, "maximum": 30, "minimum": 0, "x-auditable": true }, "chunk_size": { "type": "integer", "minimum": 64, "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "nullable": true, "readOnly": true }, "custom_metadata": { "type": "array", "items": { "properties": { "data_type": { "type": "string", "enum": [ "text", "number", "boolean", "datetime" ] }, "field_name": { "type": "string", "maxLength": 64, "minLength": 1 } }, "required": [ "field_name", "data_type" ], "type": "object" }, "maxItems": 5, "x-auditable": true }, "embedding_model": { "type": "string", "nullable": true, "x-auditable": true }, "enable": { "type": "boolean", "default": true, "x-auditable": true }, "engine_version": { "type": "number", "default": 3, "readOnly": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead.", "type": "boolean", "default": false, "deprecated": true, "x-auditable": true }, "id": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "index_method": { "description": "Controls which storage backends are used during indexing. Defaults to vector-only.", "type": "object", "default": { "keyword": false, "vector": true }, "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean" } }, "required": [ "vector", "keyword" ], "x-auditable": true }, "indexing_options": { "type": "object", "nullable": true, "properties": { "keyword_tokenizer": { "description": "Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.", "type": "string", "default": "porter", "enum": [ "porter", "trigram" ] }, "use_ocr": { "description": "Enables OCR ingestion for PDFs and images. Changing this triggers a full re-index. Defaults to false.", "type": "boolean", "default": false } }, "x-auditable": true }, "last_activity": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1, "x-auditable": true }, "metadata": { "type": "object", "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "worker_domain": { "type": "string" } }, "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "nullable": true, "readOnly": true }, "namespace": { "type": "string", "nullable": true, "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$", "readOnly": true }, "paused": { "type": "boolean", "default": false, "x-auditable": true }, "public_endpoint_id": { "type": "string", "nullable": true, "readOnly": true }, "public_endpoint_params": { "type": "object", "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } }, "x-auditable": true }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true }, "retrieval_options": { "type": "object", "nullable": true, "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ] } }, "x-auditable": true }, "rewrite_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0, "x-auditable": true }, "source": { "type": "string", "nullable": true, "x-auditable": true }, "source_params": { "type": "object", "nullable": true, "properties": { "exclude_items": { "description": "List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/admin/**", "/private/**", "**\\temp\\**" ], "maxItems": 10 }, "include_items": { "description": "List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/blog/**", "/docs/**/*.html", "**\\blog\\**.html" ], "maxItems": 10 }, "prefix": { "type": "string" }, "r2_jurisdiction": { "type": "string", "default": "default" }, "web_crawler": { "type": "object", "default": { "parse_type": "sitemap" }, "properties": { "discover_options": { "description": "Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'.", "type": "object", "properties": { "depth": { "description": "Maximum link-follow depth from the seed URL.", "type": "number", "example": 5, "default": 5, "maximum": 100000, "minimum": 1 }, "include_external_links": { "description": "Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own.", "type": "boolean", "example": false, "default": false }, "include_subdomains": { "description": "Follow links to subdomains of the source host.", "type": "boolean", "example": false, "default": false }, "limit": { "description": "Maximum number of pages to crawl (1-100000).", "type": "number", "example": 10000, "default": 100000, "maximum": 100000, "minimum": 1 }, "max_age": { "description": "Maximum content age in seconds to accept (0–604800).", "type": "number", "example": 86400, "default": 86400, "maximum": 604800, "minimum": 0 }, "source": { "description": "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both.", "type": "string", "example": "all", "default": "all", "enum": [ "all", "sitemaps", "links" ] } } }, "parse_options": { "type": "object", "properties": { "content_selector": { "description": "List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected.", "type": "array", "items": { "properties": { "path": { "description": "Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.", "type": "string", "example": "**/article/**", "maxLength": 200, "minLength": 1 }, "selector": { "description": "CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \\). Must target a single element; if multiple elements match, the selector is ignored and the full page is used.", "type": "string", "example": "article div.post-body", "maxLength": 200, "minLength": 1 } }, "required": [ "path", "selector" ], "type": "object" }, "example": [ { "path": "**/blog/**", "selector": "article div.post-body" }, { "path": "**/docs/**", "selector": "main" } ], "maxItems": 10, "minItems": 1 }, "include_headers": { "description": "Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF).", "type": "object", "example": { "cache-control": "no-cache, no-store" }, "additionalProperties": { "maxLength": 8192, "pattern": "^[\\t\\x20-\\x7E]*$", "type": "string" } }, "include_images": { "type": "boolean", "default": false }, "specific_sitemaps": { "description": "List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.", "type": "array", "items": { "format": "uri", "type": "string" }, "example": [ "https://example.com/sitemap.xml", "https://example.com/blog-sitemap.xml" ], "maxItems": 10 }, "use_browser_rendering": { "type": "boolean", "default": true } } }, "parse_type": { "description": "How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true }, "status": { "type": "string", "default": "waiting", "readOnly": true }, "sync_interval": { "description": "Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).", "default": 21600, "anyOf": [ { "enum": [ 900 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 14400 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" } ], "x-auditable": true }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true }, "type": { "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true } }, "required": [ "id", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "get" }, "put": { "operationId": "ai-search-update-instance", "summary": "Update an AI Search instance.", "description": "Update the configuration of an AI Search instance.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "my-ai-search" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_gateway_id": { "type": "string", "nullable": true, "x-auditable": true }, "ai_search_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "cache": { "type": "boolean", "default": true, "x-auditable": true }, "cache_threshold": { "type": "string", "default": "close_enough", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ], "x-auditable": true }, "cache_ttl": { "description": "Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).", "default": 172800, "anyOf": [ { "enum": [ 600 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" }, { "enum": [ 172800 ], "type": "number" }, { "enum": [ 259200 ], "type": "number" }, { "enum": [ 518400 ], "type": "number" } ], "x-auditable": true }, "chunk": { "type": "boolean", "default": true, "x-auditable": true }, "chunk_overlap": { "type": "integer", "default": 10, "maximum": 30, "minimum": 0, "x-auditable": true }, "chunk_size": { "type": "integer", "minimum": 64, "x-auditable": true }, "custom_metadata": { "type": "array", "items": { "properties": { "data_type": { "type": "string", "enum": [ "text", "number", "boolean", "datetime" ] }, "field_name": { "type": "string", "maxLength": 64, "minLength": 1 } }, "required": [ "field_name", "data_type" ], "type": "object" }, "maxItems": 5, "x-auditable": true }, "embedding_model": { "type": "string", "nullable": true, "x-auditable": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "index_method": { "description": "Controls which storage backends are used during indexing. Defaults to vector-only.", "type": "object", "default": { "keyword": false, "vector": true }, "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean" } }, "required": [ "vector", "keyword" ], "x-auditable": true }, "indexing_options": { "type": "object", "nullable": true, "properties": { "keyword_tokenizer": { "description": "Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.", "type": "string", "default": "porter", "enum": [ "porter", "trigram" ] }, "use_ocr": { "description": "Enables OCR ingestion for PDFs and images. Changing this triggers a full re-index. Defaults to false.", "type": "boolean", "default": false } }, "x-auditable": true }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1, "x-auditable": true }, "metadata": { "type": "object", "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "worker_domain": { "type": "string" } }, "x-auditable": true }, "paused": { "type": "boolean", "default": false, "x-auditable": true }, "public_endpoint_params": { "type": "object", "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } }, "x-auditable": true }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true }, "retrieval_options": { "type": "object", "nullable": true, "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ] } }, "x-auditable": true }, "rewrite_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0, "x-auditable": true }, "source": { "type": "string", "nullable": true, "x-auditable": true }, "source_params": { "type": "object", "nullable": true, "properties": { "exclude_items": { "description": "List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/admin/**", "/private/**", "**\\temp\\**" ], "maxItems": 10 }, "include_items": { "description": "List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/blog/**", "/docs/**/*.html", "**\\blog\\**.html" ], "maxItems": 10 }, "prefix": { "type": "string" }, "r2_jurisdiction": { "type": "string", "default": "default" }, "web_crawler": { "type": "object", "default": { "parse_type": "sitemap" }, "properties": { "discover_options": { "description": "Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'.", "type": "object", "properties": { "depth": { "description": "Maximum link-follow depth from the seed URL.", "type": "number", "example": 5, "default": 5, "maximum": 100000, "minimum": 1 }, "include_external_links": { "description": "Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own.", "type": "boolean", "example": false, "default": false }, "include_subdomains": { "description": "Follow links to subdomains of the source host.", "type": "boolean", "example": false, "default": false }, "limit": { "description": "Maximum number of pages to crawl (1-100000).", "type": "number", "example": 10000, "default": 100000, "maximum": 100000, "minimum": 1 }, "max_age": { "description": "Maximum content age in seconds to accept (0–604800).", "type": "number", "example": 86400, "default": 86400, "maximum": 604800, "minimum": 0 }, "source": { "description": "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both.", "type": "string", "example": "all", "default": "all", "enum": [ "all", "sitemaps", "links" ] } } }, "parse_options": { "type": "object", "properties": { "content_selector": { "description": "List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected.", "type": "array", "items": { "properties": { "path": { "description": "Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.", "type": "string", "example": "**/article/**", "maxLength": 200, "minLength": 1 }, "selector": { "description": "CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \\). Must target a single element; if multiple elements match, the selector is ignored and the full page is used.", "type": "string", "example": "article div.post-body", "maxLength": 200, "minLength": 1 } }, "required": [ "path", "selector" ], "type": "object" }, "example": [ { "path": "**/blog/**", "selector": "article div.post-body" }, { "path": "**/docs/**", "selector": "main" } ], "maxItems": 10, "minItems": 1 }, "include_headers": { "description": "Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF).", "type": "object", "example": { "cache-control": "no-cache, no-store" }, "additionalProperties": { "maxLength": 8192, "pattern": "^[\\t\\x20-\\x7E]*$", "type": "string" } }, "include_images": { "type": "boolean", "default": false }, "specific_sitemaps": { "description": "List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.", "type": "array", "items": { "format": "uri", "type": "string" }, "example": [ "https://example.com/sitemap.xml", "https://example.com/blog-sitemap.xml" ], "maxItems": 10 }, "use_browser_rendering": { "type": "boolean", "default": true } } }, "parse_type": { "description": "How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true }, "summarization": { "type": "boolean", "default": false, "x-auditable": true }, "summarization_model": { "type": "string", "nullable": true, "x-auditable": true }, "sync_interval": { "description": "Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).", "default": 21600, "anyOf": [ { "enum": [ 900 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 14400 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" } ], "x-auditable": true }, "system_prompt_ai_search": { "type": "string", "nullable": true, "x-auditable": true }, "system_prompt_index_summarization": { "type": "string", "nullable": true, "x-auditable": true }, "system_prompt_rewrite_query": { "type": "string", "nullable": true, "x-auditable": true }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true } } } } } }, "responses": { "200": { "description": "Returns the updated instance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "ai_gateway_id": { "type": "string", "nullable": true, "x-auditable": true }, "ai_search_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "cache": { "type": "boolean", "default": true, "x-auditable": true }, "cache_threshold": { "type": "string", "default": "close_enough", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ], "x-auditable": true }, "cache_ttl": { "description": "Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).", "default": 172800, "anyOf": [ { "enum": [ 600 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" }, { "enum": [ 172800 ], "type": "number" }, { "enum": [ 259200 ], "type": "number" }, { "enum": [ 518400 ], "type": "number" } ], "x-auditable": true }, "chunk_overlap": { "type": "integer", "default": 10, "maximum": 30, "minimum": 0, "x-auditable": true }, "chunk_size": { "type": "integer", "minimum": 64, "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "nullable": true, "readOnly": true }, "custom_metadata": { "type": "array", "items": { "properties": { "data_type": { "type": "string", "enum": [ "text", "number", "boolean", "datetime" ] }, "field_name": { "type": "string", "maxLength": 64, "minLength": 1 } }, "required": [ "field_name", "data_type" ], "type": "object" }, "maxItems": 5, "x-auditable": true }, "embedding_model": { "type": "string", "nullable": true, "x-auditable": true }, "enable": { "type": "boolean", "default": true, "x-auditable": true }, "engine_version": { "type": "number", "default": 3, "readOnly": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead.", "type": "boolean", "default": false, "deprecated": true, "x-auditable": true }, "id": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "index_method": { "description": "Controls which storage backends are used during indexing. Defaults to vector-only.", "type": "object", "default": { "keyword": false, "vector": true }, "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean" } }, "required": [ "vector", "keyword" ], "x-auditable": true }, "indexing_options": { "type": "object", "nullable": true, "properties": { "keyword_tokenizer": { "description": "Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.", "type": "string", "default": "porter", "enum": [ "porter", "trigram" ] }, "use_ocr": { "description": "Enables OCR ingestion for PDFs and images. Changing this triggers a full re-index. Defaults to false.", "type": "boolean", "default": false } }, "x-auditable": true }, "last_activity": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1, "x-auditable": true }, "metadata": { "type": "object", "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "worker_domain": { "type": "string" } }, "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "nullable": true, "readOnly": true }, "namespace": { "type": "string", "nullable": true, "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$", "readOnly": true }, "paused": { "type": "boolean", "default": false, "x-auditable": true }, "public_endpoint_id": { "type": "string", "nullable": true, "readOnly": true }, "public_endpoint_params": { "type": "object", "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } }, "x-auditable": true }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true }, "retrieval_options": { "type": "object", "nullable": true, "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ] } }, "x-auditable": true }, "rewrite_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0, "x-auditable": true }, "source": { "type": "string", "nullable": true, "x-auditable": true }, "source_params": { "type": "object", "nullable": true, "properties": { "exclude_items": { "description": "List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/admin/**", "/private/**", "**\\temp\\**" ], "maxItems": 10 }, "include_items": { "description": "List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/blog/**", "/docs/**/*.html", "**\\blog\\**.html" ], "maxItems": 10 }, "prefix": { "type": "string" }, "r2_jurisdiction": { "type": "string", "default": "default" }, "web_crawler": { "type": "object", "default": { "parse_type": "sitemap" }, "properties": { "discover_options": { "description": "Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'.", "type": "object", "properties": { "depth": { "description": "Maximum link-follow depth from the seed URL.", "type": "number", "example": 5, "default": 5, "maximum": 100000, "minimum": 1 }, "include_external_links": { "description": "Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own.", "type": "boolean", "example": false, "default": false }, "include_subdomains": { "description": "Follow links to subdomains of the source host.", "type": "boolean", "example": false, "default": false }, "limit": { "description": "Maximum number of pages to crawl (1-100000).", "type": "number", "example": 10000, "default": 100000, "maximum": 100000, "minimum": 1 }, "max_age": { "description": "Maximum content age in seconds to accept (0–604800).", "type": "number", "example": 86400, "default": 86400, "maximum": 604800, "minimum": 0 }, "source": { "description": "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both.", "type": "string", "example": "all", "default": "all", "enum": [ "all", "sitemaps", "links" ] } } }, "parse_options": { "type": "object", "properties": { "content_selector": { "description": "List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected.", "type": "array", "items": { "properties": { "path": { "description": "Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.", "type": "string", "example": "**/article/**", "maxLength": 200, "minLength": 1 }, "selector": { "description": "CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \\). Must target a single element; if multiple elements match, the selector is ignored and the full page is used.", "type": "string", "example": "article div.post-body", "maxLength": 200, "minLength": 1 } }, "required": [ "path", "selector" ], "type": "object" }, "example": [ { "path": "**/blog/**", "selector": "article div.post-body" }, { "path": "**/docs/**", "selector": "main" } ], "maxItems": 10, "minItems": 1 }, "include_headers": { "description": "Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF).", "type": "object", "example": { "cache-control": "no-cache, no-store" }, "additionalProperties": { "maxLength": 8192, "pattern": "^[\\t\\x20-\\x7E]*$", "type": "string" } }, "include_images": { "type": "boolean", "default": false }, "specific_sitemaps": { "description": "List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.", "type": "array", "items": { "format": "uri", "type": "string" }, "example": [ "https://example.com/sitemap.xml", "https://example.com/blog-sitemap.xml" ], "maxItems": 10 }, "use_browser_rendering": { "type": "boolean", "default": true } } }, "parse_type": { "description": "How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true }, "status": { "type": "string", "default": "waiting", "readOnly": true }, "sync_interval": { "description": "Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).", "default": 21600, "anyOf": [ { "enum": [ 900 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 14400 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" } ], "x-auditable": true }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true }, "type": { "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true } }, "required": [ "id", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Ai search instance invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "409": { "description": "Instance status modified concurrently please retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "update" } }, "/accounts/{account_id}/ai-search/instances/{id}/chat/completions": { "post": { "operationId": "ai-search-instance-chat-completion", "summary": "Chat Completions", "description": "Performs a chat completion request against an AI Search instance, using indexed content as context for generating responses.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_search_options": { "type": "object", "properties": { "cache": { "type": "object", "properties": { "cache_threshold": { "type": "string", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ] }, "enabled": { "type": "boolean" } } }, "custom_metadata": { "description": "Metadata added to AI Gateway logs for requests triggered by this operation. Accepts up to 2 string, number, or boolean entries. Keys 'ai-search', 'task', 'origin', and keys beginning with 'cf.' are reserved.", "type": "object", "example": { "test": true, "user_id": "user-123" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "maxProperties": 2 }, "query_rewrite": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string" }, "rewrite_prompt": { "type": "string" } } }, "reranking": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "match_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0 }, "model": { "type": "string" } } }, "retrieval": { "type": "object", "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Overrides the instance-level boost_by config. Direction defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "context_expansion": { "type": "integer", "default": 0, "maximum": 3, "minimum": 0 }, "filters": { "type": "object", "additionalProperties": true }, "fusion_method": { "type": "string", "enum": [ "max", "rrf" ] }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted, falls back to the instance-level retrieval_options.keyword_match_mode, then to 'and'.", "type": "string", "enum": [ "and", "or" ] }, "match_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0 }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1 }, "retrieval_type": { "type": "string", "enum": [ "vector", "keyword", "hybrid" ] }, "return_on_failure": { "type": "boolean", "default": true } } } } }, "messages": { "type": "array", "items": { "additionalProperties": true, "properties": { "content": { "anyOf": [ { "type": "string" }, { "items": { "oneOf": [ { "properties": { "text": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type", "text" ], "type": "object" }, { "properties": { "image_url": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 20971520, "minLength": 1 } }, "required": [ "url" ] }, "type": { "type": "string", "enum": [ "image_url" ] } }, "required": [ "type", "image_url" ], "type": "object" }, { "properties": { "file": { "type": "object", "properties": { "file_data": { "type": "string", "maxLength": 13981144, "minLength": 1 }, "file_id": { "type": "string" }, "filename": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "filename" ] }, "type": { "type": "string", "enum": [ "file" ] } }, "required": [ "type", "file" ], "type": "object" } ] }, "minItems": 1, "type": "array" }, { "enum": [ null ], "nullable": true, "type": "string" } ] }, "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool" ] } }, "required": [ "role", "content" ], "type": "object" }, "minItems": 1 }, "model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string" }, "stream": { "type": "boolean" } }, "additionalProperties": true, "required": [ "messages" ] } } } }, "responses": { "200": { "description": "Returns the chat completions results with retrieved files.", "content": { "application/json": { "schema": { "type": "object", "properties": { "choices": { "type": "array", "items": { "properties": { "index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "properties": { "content": { "anyOf": [ { "type": "string" }, { "items": { "oneOf": [ { "properties": { "text": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type", "text" ], "type": "object" }, { "properties": { "image_url": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 20971520, "minLength": 1 } }, "required": [ "url" ] }, "type": { "type": "string", "enum": [ "image_url" ] } }, "required": [ "type", "image_url" ], "type": "object" }, { "properties": { "file": { "type": "object", "properties": { "file_data": { "type": "string", "maxLength": 13981144, "minLength": 1 }, "file_id": { "type": "string" }, "filename": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "filename" ] }, "type": { "type": "string", "enum": [ "file" ] } }, "required": [ "type", "file" ], "type": "object" } ] }, "minItems": 1, "type": "array" }, { "enum": [ null ], "nullable": true, "type": "string" } ] }, "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool" ] } }, "required": [ "role", "content" ] } }, "required": [ "message" ], "type": "object" } }, "chunks": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "item": { "type": "object", "properties": { "key": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "number" } }, "required": [ "key" ] }, "score": { "type": "number", "maximum": 1, "minimum": 0 }, "scoring_details": { "type": "object", "properties": { "fusion_method": { "type": "string", "enum": [ "rrf", "max" ] }, "keyword_rank": { "type": "number" }, "keyword_score": { "type": "number", "minimum": 0 }, "reranking_score": { "type": "number", "maximum": 1, "minimum": 0 }, "vector_rank": { "type": "number" }, "vector_score": { "type": "number", "maximum": 1, "minimum": 0 } } }, "text": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type", "score", "text" ], "type": "object" } }, "id": { "type": "string" }, "model": { "type": "string" }, "object": { "type": "string" } }, "additionalProperties": true, "required": [ "choices", "chunks" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "chat-completions" } }, "/accounts/{account_id}/ai-search/instances/{id}/jobs": { "get": { "operationId": "ai-search-instance-list-jobs", "summary": "List Jobs", "description": "Lists indexing jobs for an AI Search instance.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50, "minimum": 0 } } ], "responses": { "200": { "description": "Returns a list of AI Search Jobs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "description": { "type": "string" }, "end_reason": { "type": "string" }, "ended_at": { "type": "string" }, "id": { "type": "string", "x-auditable": true }, "last_seen_at": { "type": "string" }, "source": { "type": "string", "enum": [ "user", "schedule" ], "x-auditable": true }, "started_at": { "type": "string" } }, "required": [ "id", "source" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" } }, "required": [ "count", "page", "per_page", "total_count" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Jobs" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-search.jobs", "x-fern-sdk-method-name": "list" }, "post": { "operationId": "ai-search-instance-create-job", "summary": "Create new job", "description": "Creates a new indexing job for an AI Search instance.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "Returns the AI Search job id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "description": { "type": "string" }, "end_reason": { "type": "string" }, "ended_at": { "type": "string" }, "id": { "type": "string", "x-auditable": true }, "last_seen_at": { "type": "string" }, "source": { "type": "string", "enum": [ "user", "schedule" ], "x-auditable": true }, "started_at": { "type": "string" } }, "required": [ "id", "source" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "429": { "description": "Sync in cooldown.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Jobs" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-search.jobs", "x-fern-sdk-method-name": "create" } }, "/accounts/{account_id}/ai-search/instances/{id}/jobs/{job_id}": { "get": { "operationId": "ai-search-instance-get-job", "summary": "Get a Job Details", "description": "Retrieves details for a specific AI Search indexing job.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "responses": { "200": { "description": "Returns a AI Search Job Details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "description": { "type": "string" }, "end_reason": { "type": "string" }, "ended_at": { "type": "string" }, "id": { "type": "string", "x-auditable": true }, "last_seen_at": { "type": "string" }, "source": { "type": "string", "enum": [ "user", "schedule" ], "x-auditable": true }, "started_at": { "type": "string" } }, "required": [ "id", "source" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Job not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Jobs" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-search.jobs", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "ai-search-instance-change-job-status", "summary": "Cancel an indexing job.", "description": "Cancel an in-progress indexing job for an AI Search instance.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "cancel" ] } }, "required": [ "action" ] } } } }, "responses": { "200": { "description": "Returns the updated AI Search Job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "description": { "type": "string" }, "end_reason": { "type": "string" }, "ended_at": { "type": "string" }, "id": { "type": "string", "x-auditable": true }, "last_seen_at": { "type": "string" }, "source": { "type": "string", "enum": [ "user", "schedule" ], "x-auditable": true }, "started_at": { "type": "string" } }, "required": [ "id", "source" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Job cannot be cancelled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Job not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Jobs" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-search.jobs", "x-fern-sdk-method-name": "cancel", "x-forge-require-confirmation": "This operation cancels the running indexing job." } }, "/accounts/{account_id}/ai-search/instances/{id}/jobs/{job_id}/logs": { "get": { "operationId": "ai-search-instance-list-job-logs", "summary": "List Job Logs", "description": "Lists log entries for an AI Search indexing job.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 500, "minimum": 0 } } ], "responses": { "200": { "description": "Returns a list of AI Search Job Logs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "created_at": { "type": "number" }, "id": { "type": "integer" }, "message": { "type": "string" }, "message_type": { "type": "integer" } }, "required": [ "id", "message", "message_type", "created_at" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" } }, "required": [ "count", "page", "per_page", "total_count" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Jobs" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-search.jobs", "x-fern-sdk-method-name": "logs" } }, "/accounts/{account_id}/ai-search/instances/{id}/search": { "post": { "operationId": "ai-search-instance-search", "summary": "Search", "description": "Executes a semantic search query against an AI Search instance to find relevant indexed content.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_search_options": { "type": "object", "properties": { "cache": { "type": "object", "properties": { "cache_threshold": { "type": "string", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ] }, "enabled": { "type": "boolean" } } }, "custom_metadata": { "description": "Metadata added to AI Gateway logs for requests triggered by this operation. Accepts up to 2 string, number, or boolean entries. Keys 'ai-search', 'task', 'origin', and keys beginning with 'cf.' are reserved.", "type": "object", "example": { "test": true, "user_id": "user-123" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "maxProperties": 2 }, "query_rewrite": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string" }, "rewrite_prompt": { "type": "string" } } }, "reranking": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "match_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0 }, "model": { "type": "string" } } }, "retrieval": { "type": "object", "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Overrides the instance-level boost_by config. Direction defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "context_expansion": { "type": "integer", "default": 0, "maximum": 3, "minimum": 0 }, "filters": { "type": "object", "additionalProperties": true }, "fusion_method": { "type": "string", "enum": [ "max", "rrf" ] }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted, falls back to the instance-level retrieval_options.keyword_match_mode, then to 'and'.", "type": "string", "enum": [ "and", "or" ] }, "match_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0 }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1 }, "retrieval_type": { "type": "string", "enum": [ "vector", "keyword", "hybrid" ] }, "return_on_failure": { "type": "boolean", "default": true } } } } }, "messages": { "description": "OpenAI-compatible message array. For multimodal queries, set the last user message's `content` to an array of typed parts: `[{type:'text', text:'…'}, {type:'image_url', image_url:{url:'…'}}]`. Image inputs require the RAG's embedding_model to declare 'image' in supported_modalities.", "type": "array", "items": { "additionalProperties": true, "properties": { "content": { "anyOf": [ { "type": "string" }, { "items": { "oneOf": [ { "properties": { "text": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type", "text" ], "type": "object" }, { "properties": { "image_url": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 20971520, "minLength": 1 } }, "required": [ "url" ] }, "type": { "type": "string", "enum": [ "image_url" ] } }, "required": [ "type", "image_url" ], "type": "object" }, { "properties": { "file": { "type": "object", "properties": { "file_data": { "type": "string", "maxLength": 13981144, "minLength": 1 }, "file_id": { "type": "string" }, "filename": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "filename" ] }, "type": { "type": "string", "enum": [ "file" ] } }, "required": [ "type", "file" ], "type": "object" } ] }, "minItems": 1, "type": "array" }, { "enum": [ null ], "nullable": true, "type": "string" } ] }, "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool" ] } }, "required": [ "role", "content" ], "type": "object" }, "minItems": 1 }, "query": { "description": "A simple text query string. Alternative to 'messages' — provide either this or 'messages', not both.", "minLength": 1, "type": "string" } } } } } }, "responses": { "200": { "description": "Returns the search results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "chunks": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "item": { "type": "object", "properties": { "key": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "number" } }, "required": [ "key" ] }, "score": { "type": "number", "maximum": 1, "minimum": 0 }, "scoring_details": { "type": "object", "properties": { "fusion_method": { "type": "string", "enum": [ "rrf", "max" ] }, "keyword_rank": { "type": "number" }, "keyword_score": { "type": "number", "minimum": 0 }, "reranking_score": { "type": "number", "maximum": 1, "minimum": 0 }, "vector_rank": { "type": "number" }, "vector_score": { "type": "number", "maximum": 1, "minimum": 0 } } }, "text": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type", "score", "text" ], "type": "object" } }, "query_kind": { "type": "string", "enum": [ "text", "image", "multimodal" ] }, "search_query": { "type": "string" } }, "required": [ "query_kind", "chunks" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "search" } }, "/accounts/{account_id}/ai-search/instances/{id}/stats": { "get": { "operationId": "ai-search-stats", "summary": "Get instance statistics.", "description": "Retrieve usage and indexing statistics for an AI Search instance.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "responses": { "200": { "description": "Returns the AI Search stats.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "completed": { "type": "integer" }, "degraded": { "description": "True when status counts are unavailable (e.g. legacy stats query exceeded D1 statement-size limit). Counts are omitted in this case.", "type": "boolean" }, "engine": { "description": "Engine-specific metadata. Present only for managed (v3) instances.", "type": "object", "properties": { "r2": { "description": "R2 bucket storage usage in bytes.", "type": "object", "properties": { "metadataSizeBytes": { "type": "integer" }, "objectCount": { "type": "integer" }, "payloadSizeBytes": { "type": "integer" } }, "required": [ "payloadSizeBytes", "metadataSizeBytes", "objectCount" ] }, "vectorize": { "description": "Vectorize index metadata (dimensions, vector count).", "type": "object", "properties": { "dimensions": { "type": "integer" }, "vectorsCount": { "type": "integer" } }, "required": [ "vectorsCount", "dimensions" ] } } }, "error": { "type": "integer" }, "file_embed_errors": { "type": "object", "additionalProperties": true }, "index_source_errors": { "type": "object", "additionalProperties": true }, "last_activity": { "type": "string", "format": "date-time" }, "outdated": { "type": "integer" }, "queued": { "type": "integer" }, "running": { "type": "integer" }, "skipped": { "type": "integer" } } }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-ignore": true, "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "stats" } }, "/accounts/{account_id}/ai-search/namespaces": { "get": { "operationId": "ai-search-list-namespaces", "summary": "List namespaces", "description": "List namespaces in the account, including their descriptions and creation times.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "page", "in": "query", "description": "Page number (1-indexed).", "schema": { "description": "Page number (1-indexed).", "type": "integer", "example": 1, "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "description": "Number of results per page.", "type": "integer", "example": 20, "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Filter namespaces whose name or description contains this string (case-insensitive).", "schema": { "description": "Filter namespaces whose name or description contains this string (case-insensitive).", "type": "string", "example": "prod", "maxLength": 256 } } ], "responses": { "200": { "description": "List of namespaces.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "description": { "description": "Optional description for the namespace. Max 256 characters.", "type": "string", "example": "Production environment", "maxLength": 256, "nullable": true }, "name": { "type": "string", "example": "production", "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$" }, "public_endpoint_id": { "type": "string", "nullable": true, "readOnly": true }, "public_endpoint_params": { "type": "object", "nullable": true, "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "instances_allowed": { "description": "Instance IDs exposed through the namespace public endpoint. Empty means nothing is searchable. Every ID must be an existing instance in this namespace, and the list cannot exceed the account's multi-instance search limit.", "type": "array", "items": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "type": "string", "x-auditable": true }, "example": [ "docs", "blog" ], "default": [], "maxItems": 10, "x-auditable": true }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } }, "x-auditable": true } }, "required": [ "name", "created_at" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "page", "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "result_info" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Namespaces" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.namespace", "x-fern-sdk-method-name": "list" }, "post": { "operationId": "ai-search-create-namespace", "summary": "Create a namespace", "description": "Create a namespace for organizing AI Search instances.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "description": "Optional description for the namespace. Max 256 characters.", "type": "string", "example": "Production environment", "maxLength": 256, "nullable": true }, "name": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$" }, "public_endpoint_params": { "type": "object", "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "instances_allowed": { "description": "Instance IDs exposed through the namespace public endpoint. Empty means nothing is searchable. Every ID must be an existing instance in this namespace, and the list cannot exceed the account's multi-instance search limit.", "type": "array", "items": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "type": "string", "x-auditable": true }, "example": [ "docs", "blog" ], "default": [], "maxItems": 10, "x-auditable": true }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } } } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Namespace created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "description": { "description": "Optional description for the namespace. Max 256 characters.", "type": "string", "example": "Production environment", "maxLength": 256, "nullable": true }, "name": { "type": "string", "example": "production", "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$" }, "public_endpoint_id": { "type": "string", "nullable": true, "readOnly": true }, "public_endpoint_params": { "type": "object", "nullable": true, "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "instances_allowed": { "description": "Instance IDs exposed through the namespace public endpoint. Empty means nothing is searchable. Every ID must be an existing instance in this namespace, and the list cannot exceed the account's multi-instance search limit.", "type": "array", "items": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "type": "string", "x-auditable": true }, "example": [ "docs", "blog" ], "default": [], "maxItems": 10, "x-auditable": true }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } }, "x-auditable": true } }, "required": [ "name", "created_at" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Instances allowed contains unknown instances.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "403": { "description": "Max namespaces reached.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "409": { "description": "Namespace already exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Namespaces" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.namespace", "x-fern-sdk-method-name": "create", "x-forge-params": { "name": { "description": "Name for the new namespace.", "flagName": "namespace", "positional": true } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}": { "delete": { "operationId": "ai-search-delete-namespace", "summary": "Delete a namespace", "description": "Permanently delete a namespace. The namespace must be empty (no instances), and the default namespace cannot be deleted.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "example": "production" } } ], "responses": { "200": { "description": "Namespace deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "additionalProperties": false }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Namespace not empty.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Namespace not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Namespaces" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.namespace", "x-fern-sdk-method-name": "delete", "x-forge-params": { "name": { "description": "Namespace to delete.", "flagName": "namespace" } }, "x-forge-require-confirmation": "This operation permanently deletes the namespace." }, "get": { "operationId": "ai-search-fetch-namespace", "summary": "Get a namespace", "description": "Retrieve a namespace and its description.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "example": "production" } } ], "responses": { "200": { "description": "Namespace details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "description": { "description": "Optional description for the namespace. Max 256 characters.", "type": "string", "example": "Production environment", "maxLength": 256, "nullable": true }, "name": { "type": "string", "example": "production", "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$" }, "public_endpoint_id": { "type": "string", "nullable": true, "readOnly": true }, "public_endpoint_params": { "type": "object", "nullable": true, "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "instances_allowed": { "description": "Instance IDs exposed through the namespace public endpoint. Empty means nothing is searchable. Every ID must be an existing instance in this namespace, and the list cannot exceed the account's multi-instance search limit.", "type": "array", "items": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "type": "string", "x-auditable": true }, "example": [ "docs", "blog" ], "default": [], "maxItems": 10, "x-auditable": true }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } }, "x-auditable": true } }, "required": [ "name", "created_at" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Namespace not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Namespaces" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.namespace", "x-fern-sdk-method-name": "get", "x-forge-params": { "name": { "description": "Namespace to retrieve.", "flagName": "namespace" } } }, "put": { "operationId": "ai-search-update-namespace", "summary": "Update a namespace", "description": "Update the description and/or the public endpoint configuration of an existing namespace. The default namespace's description cannot be modified, but its public endpoint can.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "example": "production" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "description": "Optional description for the namespace. Max 256 characters.", "type": "string", "example": "Production environment", "maxLength": 256, "nullable": true }, "public_endpoint_params": { "type": "object", "nullable": true, "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "instances_allowed": { "description": "Instance IDs exposed through the namespace public endpoint. Empty means nothing is searchable. Every ID must be an existing instance in this namespace, and the list cannot exceed the account's multi-instance search limit.", "type": "array", "items": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "type": "string", "x-auditable": true }, "example": [ "docs", "blog" ], "default": [], "maxItems": 10, "x-auditable": true }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } } } } } } } }, "responses": { "200": { "description": "Returns the updated namespace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "description": { "description": "Optional description for the namespace. Max 256 characters.", "type": "string", "example": "Production environment", "maxLength": 256, "nullable": true }, "name": { "type": "string", "example": "production", "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$" }, "public_endpoint_id": { "type": "string", "nullable": true, "readOnly": true }, "public_endpoint_params": { "type": "object", "nullable": true, "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "instances_allowed": { "description": "Instance IDs exposed through the namespace public endpoint. Empty means nothing is searchable. Every ID must be an existing instance in this namespace, and the list cannot exceed the account's multi-instance search limit.", "type": "array", "items": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "type": "string", "x-auditable": true }, "example": [ "docs", "blog" ], "default": [], "maxItems": 10, "x-auditable": true }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } }, "x-auditable": true } }, "required": [ "name", "created_at" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Instances allowed contains unknown instances.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Namespace not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "409": { "description": "Namespace modified concurrently please retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Namespaces" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.namespace", "x-fern-sdk-method-name": "update", "x-forge-params": { "name": { "description": "Namespace to update.", "flagName": "namespace" } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}/chat/completions": { "post": { "operationId": "ai-search-namespace-multi-instance-chat-completion", "summary": "Multi-Instance Chat Completions", "description": "Performs a chat completion request against multiple AI Search instances in parallel, merging retrieved content as context for generating a response.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_search_options": { "type": "object", "properties": { "cache": { "type": "object", "properties": { "cache_threshold": { "type": "string", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ] }, "enabled": { "type": "boolean" } } }, "custom_metadata": { "description": "Metadata added to AI Gateway logs for requests triggered by this operation. Accepts up to 2 string, number, or boolean entries. Keys 'ai-search', 'task', 'origin', and keys beginning with 'cf.' are reserved.", "type": "object", "example": { "test": true, "user_id": "user-123" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "maxProperties": 2 }, "instance_ids": { "type": "array", "items": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "type": "string", "x-auditable": true }, "minItems": 1 }, "query_rewrite": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string" }, "rewrite_prompt": { "type": "string" } } }, "reranking": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "match_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0 }, "model": { "type": "string" } } }, "retrieval": { "type": "object", "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Overrides the instance-level boost_by config. Direction defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "context_expansion": { "type": "integer", "default": 0, "maximum": 3, "minimum": 0 }, "filters": { "type": "object", "additionalProperties": true }, "fusion_method": { "type": "string", "enum": [ "max", "rrf" ] }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted, falls back to the instance-level retrieval_options.keyword_match_mode, then to 'and'.", "type": "string", "enum": [ "and", "or" ] }, "match_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0 }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1 }, "retrieval_type": { "type": "string", "enum": [ "vector", "keyword", "hybrid" ] }, "return_on_failure": { "type": "boolean", "default": true } } } }, "required": [ "instance_ids" ] }, "messages": { "type": "array", "items": { "additionalProperties": true, "properties": { "content": { "anyOf": [ { "type": "string" }, { "items": { "oneOf": [ { "properties": { "text": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type", "text" ], "type": "object" }, { "properties": { "image_url": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 20971520, "minLength": 1 } }, "required": [ "url" ] }, "type": { "type": "string", "enum": [ "image_url" ] } }, "required": [ "type", "image_url" ], "type": "object" }, { "properties": { "file": { "type": "object", "properties": { "file_data": { "type": "string", "maxLength": 13981144, "minLength": 1 }, "file_id": { "type": "string" }, "filename": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "filename" ] }, "type": { "type": "string", "enum": [ "file" ] } }, "required": [ "type", "file" ], "type": "object" } ] }, "minItems": 1, "type": "array" }, { "enum": [ null ], "nullable": true, "type": "string" } ] }, "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool" ] } }, "required": [ "role", "content" ], "type": "object" }, "minItems": 1 }, "model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string" }, "stream": { "type": "boolean" } }, "additionalProperties": true, "required": [ "messages", "ai_search_options" ] } } } }, "responses": { "200": { "description": "Returns the chat completion result with merged chunks from all instances.", "content": { "application/json": { "schema": { "type": "object", "properties": { "choices": { "type": "array", "items": { "properties": { "index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "properties": { "content": { "anyOf": [ { "type": "string" }, { "items": { "oneOf": [ { "properties": { "text": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type", "text" ], "type": "object" }, { "properties": { "image_url": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 20971520, "minLength": 1 } }, "required": [ "url" ] }, "type": { "type": "string", "enum": [ "image_url" ] } }, "required": [ "type", "image_url" ], "type": "object" }, { "properties": { "file": { "type": "object", "properties": { "file_data": { "type": "string", "maxLength": 13981144, "minLength": 1 }, "file_id": { "type": "string" }, "filename": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "filename" ] }, "type": { "type": "string", "enum": [ "file" ] } }, "required": [ "type", "file" ], "type": "object" } ] }, "minItems": 1, "type": "array" }, { "enum": [ null ], "nullable": true, "type": "string" } ] }, "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool" ] } }, "required": [ "role", "content" ] } }, "required": [ "message" ], "type": "object" } }, "chunks": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "instance_id": { "type": "string" }, "item": { "type": "object", "properties": { "key": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "number" } }, "required": [ "key" ] }, "score": { "type": "number", "maximum": 1, "minimum": 0 }, "scoring_details": { "type": "object", "properties": { "fusion_method": { "type": "string", "enum": [ "rrf", "max" ] }, "keyword_rank": { "type": "number" }, "keyword_score": { "type": "number", "minimum": 0 }, "reranking_score": { "type": "number", "maximum": 1, "minimum": 0 }, "vector_rank": { "type": "number" }, "vector_score": { "type": "number", "maximum": 1, "minimum": 0 } } }, "text": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type", "score", "text", "instance_id" ], "type": "object" } }, "errors": { "type": "array", "items": { "properties": { "instance_id": { "type": "string" }, "message": { "type": "string" } }, "required": [ "instance_id", "message" ], "type": "object" } }, "id": { "type": "string" }, "model": { "type": "string" }, "object": { "type": "string" } }, "additionalProperties": true, "required": [ "choices", "chunks" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Account Search" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "multi-chat-completions", "x-forge-params": { "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}/instances": { "get": { "operationId": "ai-search-namespace-list-instances", "summary": "List AI Search instances.", "description": "List all AI Search instances in the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "page", "in": "query", "description": "Page number (1-indexed).", "schema": { "description": "Page number (1-indexed).", "type": "integer", "example": 1, "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "description": "Number of results per page.", "type": "integer", "example": 20, "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Filter instances whose id contains this string (case-insensitive).", "schema": { "description": "Filter instances whose id contains this string (case-insensitive).", "type": "string", "maxLength": 64 } }, { "name": "namespace", "in": "query", "description": "Filter by namespace.", "schema": { "description": "Filter by namespace.", "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$" } }, { "name": "order_by", "in": "query", "description": "Field to order results by.", "schema": { "description": "Field to order results by.", "type": "string", "default": "created_at", "enum": [ "created_at" ] } }, { "name": "order_by_direction", "in": "query", "description": "Order direction.", "schema": { "description": "Order direction.", "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "responses": { "200": { "description": "List of instances.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "additionalProperties": false, "properties": { "ai_gateway_id": { "type": "string", "nullable": true }, "ai_search_model": { "type": "string", "nullable": true }, "cache": { "type": "boolean" }, "cache_threshold": { "type": "string", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes", null ], "nullable": true }, "cache_ttl": { "anyOf": [ { "enum": [ 600 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" }, { "enum": [ 172800 ], "type": "number" }, { "enum": [ 259200 ], "type": "number" }, { "enum": [ 518400 ], "type": "number" } ] }, "chunk": { "type": "boolean" }, "chunk_overlap": { "type": "number", "nullable": true }, "chunk_size": { "type": "number", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "nullable": true }, "custom_metadata": { "type": "array", "items": { "additionalProperties": false, "properties": { "data_type": { "type": "string", "enum": [ "text", "number", "boolean", "datetime" ] }, "field_name": { "type": "string" } }, "required": [ "field_name", "data_type" ], "type": "object" }, "nullable": true }, "embedding_model": { "type": "string", "nullable": true }, "enable": { "type": "boolean" }, "engine_version": { "type": "number" }, "fusion_method": { "type": "string", "enum": [ "max", "rrf" ] }, "hybrid_search_enabled": { "type": "boolean" }, "id": { "type": "string" }, "index_method": { "type": "object", "additionalProperties": true, "properties": { "keyword": { "type": "boolean" }, "vector": { "type": "boolean" } }, "required": [ "vector", "keyword" ] }, "indexing_options": { "type": "object", "additionalProperties": true, "nullable": true, "properties": { "keyword_tokenizer": { "type": "string", "enum": [ "porter", "trigram" ] }, "use_ocr": { "type": "boolean" } } }, "last_activity": { "type": "string", "format": "date-time", "nullable": true }, "max_num_results": { "type": "number", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "worker_domain": { "type": "string" } } }, "modified_at": { "type": "string", "format": "date-time" }, "modified_by": { "type": "string", "nullable": true }, "namespace": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$" }, "paused": { "type": "boolean" }, "public_endpoint_id": { "type": "string", "nullable": true }, "public_endpoint_params": { "type": "object", "additionalProperties": true, "nullable": true, "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "additionalProperties": true, "properties": { "disabled": { "type": "boolean" } } }, "custom_domains": { "type": "array", "items": { "maxLength": 253, "minLength": 1, "pattern": "^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$", "type": "string" }, "maxItems": 1, "nullable": true }, "default_domain_enabled": { "type": "boolean" }, "enabled": { "type": "boolean" }, "mcp": { "type": "object", "additionalProperties": true, "properties": { "description": { "type": "string" }, "disabled": { "type": "boolean" } } }, "rate_limit": { "type": "object", "additionalProperties": true, "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "additionalProperties": true, "properties": { "disabled": { "type": "boolean" } } } } }, "reranking": { "type": "boolean" }, "reranking_model": { "type": "string", "nullable": true }, "retrieval_options": { "type": "object", "additionalProperties": true, "nullable": true, "properties": { "boost_by": { "type": "array", "items": { "additionalProperties": true, "properties": { "dataType": { "type": "string", "enum": [ "number", "datetime", "text", "boolean" ] }, "direction": { "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "type": "string", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "maxItems": 3 }, "keyword_match_mode": { "type": "string", "enum": [ "and", "or" ] } } }, "rewrite_model": { "type": "string", "nullable": true }, "rewrite_query": { "type": "boolean" }, "score_threshold": { "type": "number", "nullable": true }, "source": { "type": "string", "nullable": true }, "source_params": { "type": "object", "additionalProperties": true, "nullable": true, "properties": { "exclude_items": { "type": "array", "items": { "type": "string" } }, "include_items": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "string" }, "r2_jurisdiction": { "type": "string" }, "web_crawler": { "type": "object", "additionalProperties": true, "properties": { "discover_options": { "type": "object", "additionalProperties": true, "properties": { "depth": { "type": "number", "maximum": 100000, "minimum": 1 }, "include_external_links": { "type": "boolean" }, "include_subdomains": { "type": "boolean" }, "limit": { "description": "Maximum number of pages to crawl. New values are capped at 100000; instances configured before that cap may report a higher stored value, which the crawler clamps at run time.", "type": "number", "maximum": 100000, "minimum": 1 }, "max_age": { "type": "number", "maximum": 604800, "minimum": 0 }, "source": { "type": "string", "enum": [ "all", "sitemaps", "links" ] } } }, "parse_options": { "type": "object", "additionalProperties": true, "properties": { "content_selector": { "type": "array", "items": { "additionalProperties": true, "properties": { "path": { "type": "string", "maxLength": 200, "minLength": 1 }, "selector": { "type": "string", "maxLength": 200, "minLength": 1 } }, "required": [ "path", "selector" ], "type": "object" }, "maxItems": 10 }, "include_headers": { "type": "object", "additionalProperties": { "maxLength": 8192, "pattern": "^[\\t\\x20-\\x7E]*$", "type": "string" } }, "include_images": { "type": "boolean" }, "specific_sitemaps": { "type": "array", "items": { "format": "uri", "type": "string" }, "maxItems": 10 }, "use_browser_rendering": { "type": "boolean" } } }, "parse_type": { "type": "string", "enum": [ "sitemap", "discover" ] } } } } }, "status": { "type": "string" }, "summarization": { "type": "boolean" }, "summarization_model": { "type": "string", "nullable": true }, "sync_interval": { "anyOf": [ { "enum": [ 900 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 14400 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" } ] }, "system_prompt_ai_search": { "type": "string", "nullable": true }, "system_prompt_index_summarization": { "type": "string", "nullable": true }, "system_prompt_rewrite_query": { "type": "string", "nullable": true }, "token_id": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true } }, "required": [ "id", "engine_version", "enable", "type", "source", "source_params", "ai_gateway_id", "token_id", "cache", "cache_threshold", "cache_ttl", "summarization", "rewrite_query", "reranking", "index_method", "hybrid_search_enabled", "fusion_method", "indexing_options", "retrieval_options", "summarization_model", "embedding_model", "rewrite_model", "ai_search_model", "reranking_model", "system_prompt_ai_search", "system_prompt_index_summarization", "system_prompt_rewrite_query", "chunk", "chunk_size", "chunk_overlap", "score_threshold", "max_num_results", "public_endpoint_id", "public_endpoint_params", "paused", "status", "metadata", "custom_metadata", "sync_interval", "created_at", "created_by", "modified_at", "modified_by", "last_activity", "namespace" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "page", "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "result_info" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "list", "x-forge-params": { "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" }, "namespace": { "hidden": true } } }, "post": { "operationId": "ai-search-namespace-create-instance", "summary": "Create an AI Search instance.", "description": "Create a new AI Search instance with the given configuration.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_gateway_id": { "type": "string", "nullable": true, "x-auditable": true }, "ai_search_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "cache": { "type": "boolean", "default": true, "x-auditable": true }, "cache_threshold": { "type": "string", "default": "close_enough", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ], "x-auditable": true }, "cache_ttl": { "description": "Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).", "default": 172800, "anyOf": [ { "enum": [ 600 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" }, { "enum": [ 172800 ], "type": "number" }, { "enum": [ 259200 ], "type": "number" }, { "enum": [ 518400 ], "type": "number" } ], "x-auditable": true }, "chunk": { "type": "boolean", "default": true, "x-auditable": true }, "chunk_overlap": { "type": "integer", "default": 10, "maximum": 30, "minimum": 0, "x-auditable": true }, "chunk_size": { "type": "integer", "minimum": 64, "x-auditable": true }, "custom_metadata": { "type": "array", "items": { "properties": { "data_type": { "type": "string", "enum": [ "text", "number", "boolean", "datetime" ] }, "field_name": { "type": "string", "maxLength": 64, "minLength": 1 } }, "required": [ "field_name", "data_type" ], "type": "object" }, "maxItems": 5, "x-auditable": true }, "embedding_model": { "type": "string", "nullable": true, "x-auditable": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead.", "type": "boolean", "default": false, "deprecated": true, "x-auditable": true }, "id": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "index_method": { "description": "Controls which storage backends are used during indexing. Defaults to vector-only.", "type": "object", "default": { "keyword": false, "vector": true }, "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean" } }, "required": [ "vector", "keyword" ], "x-auditable": true }, "indexing_options": { "type": "object", "nullable": true, "properties": { "keyword_tokenizer": { "description": "Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.", "type": "string", "default": "porter", "enum": [ "porter", "trigram" ] }, "use_ocr": { "description": "Enables OCR ingestion for PDFs and images. Changing this triggers a full re-index. Defaults to false.", "type": "boolean", "default": false } }, "x-auditable": true }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1, "x-auditable": true }, "metadata": { "type": "object", "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "worker_domain": { "type": "string" } }, "x-auditable": true }, "public_endpoint_params": { "type": "object", "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } }, "x-auditable": true }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true }, "retrieval_options": { "type": "object", "nullable": true, "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ] } }, "x-auditable": true }, "rewrite_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0, "x-auditable": true }, "source": { "type": "string", "nullable": true, "x-auditable": true }, "source_params": { "type": "object", "nullable": true, "properties": { "exclude_items": { "description": "List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/admin/**", "/private/**", "**\\temp\\**" ], "maxItems": 10 }, "include_items": { "description": "List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/blog/**", "/docs/**/*.html", "**\\blog\\**.html" ], "maxItems": 10 }, "prefix": { "type": "string" }, "r2_jurisdiction": { "type": "string", "default": "default" }, "web_crawler": { "type": "object", "default": { "parse_type": "sitemap" }, "properties": { "discover_options": { "description": "Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'.", "type": "object", "properties": { "depth": { "description": "Maximum link-follow depth from the seed URL.", "type": "number", "example": 5, "default": 5, "maximum": 100000, "minimum": 1 }, "include_external_links": { "description": "Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own.", "type": "boolean", "example": false, "default": false }, "include_subdomains": { "description": "Follow links to subdomains of the source host.", "type": "boolean", "example": false, "default": false }, "limit": { "description": "Maximum number of pages to crawl (1-100000).", "type": "number", "example": 10000, "default": 100000, "maximum": 100000, "minimum": 1 }, "max_age": { "description": "Maximum content age in seconds to accept (0–604800).", "type": "number", "example": 86400, "default": 86400, "maximum": 604800, "minimum": 0 }, "source": { "description": "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both.", "type": "string", "example": "all", "default": "all", "enum": [ "all", "sitemaps", "links" ] } } }, "parse_options": { "type": "object", "properties": { "content_selector": { "description": "List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected.", "type": "array", "items": { "properties": { "path": { "description": "Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.", "type": "string", "example": "**/article/**", "maxLength": 200, "minLength": 1 }, "selector": { "description": "CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \\). Must target a single element; if multiple elements match, the selector is ignored and the full page is used.", "type": "string", "example": "article div.post-body", "maxLength": 200, "minLength": 1 } }, "required": [ "path", "selector" ], "type": "object" }, "example": [ { "path": "**/blog/**", "selector": "article div.post-body" }, { "path": "**/docs/**", "selector": "main" } ], "maxItems": 10, "minItems": 1 }, "include_headers": { "description": "Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF).", "type": "object", "example": { "cache-control": "no-cache, no-store" }, "additionalProperties": { "maxLength": 8192, "pattern": "^[\\t\\x20-\\x7E]*$", "type": "string" } }, "include_images": { "type": "boolean", "default": false }, "specific_sitemaps": { "description": "List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.", "type": "array", "items": { "format": "uri", "type": "string" }, "example": [ "https://example.com/sitemap.xml", "https://example.com/blog-sitemap.xml" ], "maxItems": 10 }, "use_browser_rendering": { "type": "boolean", "default": true } } }, "parse_type": { "description": "How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true }, "sync_interval": { "description": "Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).", "default": 21600, "anyOf": [ { "enum": [ 900 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 14400 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" } ], "x-auditable": true }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true }, "type": { "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true } }, "required": [ "id" ] } } } }, "responses": { "201": { "description": "Returns the new instance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "ai_gateway_id": { "type": "string", "nullable": true, "x-auditable": true }, "ai_search_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "cache": { "type": "boolean", "default": true, "x-auditable": true }, "cache_threshold": { "type": "string", "default": "close_enough", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ], "x-auditable": true }, "cache_ttl": { "description": "Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).", "default": 172800, "anyOf": [ { "enum": [ 600 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" }, { "enum": [ 172800 ], "type": "number" }, { "enum": [ 259200 ], "type": "number" }, { "enum": [ 518400 ], "type": "number" } ], "x-auditable": true }, "chunk_overlap": { "type": "integer", "default": 10, "maximum": 30, "minimum": 0, "x-auditable": true }, "chunk_size": { "type": "integer", "minimum": 64, "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "nullable": true, "readOnly": true }, "custom_metadata": { "type": "array", "items": { "properties": { "data_type": { "type": "string", "enum": [ "text", "number", "boolean", "datetime" ] }, "field_name": { "type": "string", "maxLength": 64, "minLength": 1 } }, "required": [ "field_name", "data_type" ], "type": "object" }, "maxItems": 5, "x-auditable": true }, "embedding_model": { "type": "string", "nullable": true, "x-auditable": true }, "enable": { "type": "boolean", "default": true, "x-auditable": true }, "engine_version": { "type": "number", "default": 3, "readOnly": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead.", "type": "boolean", "default": false, "deprecated": true, "x-auditable": true }, "id": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "index_method": { "description": "Controls which storage backends are used during indexing. Defaults to vector-only.", "type": "object", "default": { "keyword": false, "vector": true }, "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean" } }, "required": [ "vector", "keyword" ], "x-auditable": true }, "indexing_options": { "type": "object", "nullable": true, "properties": { "keyword_tokenizer": { "description": "Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.", "type": "string", "default": "porter", "enum": [ "porter", "trigram" ] }, "use_ocr": { "description": "Enables OCR ingestion for PDFs and images. Changing this triggers a full re-index. Defaults to false.", "type": "boolean", "default": false } }, "x-auditable": true }, "last_activity": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1, "x-auditable": true }, "metadata": { "type": "object", "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "worker_domain": { "type": "string" } }, "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "nullable": true, "readOnly": true }, "namespace": { "type": "string", "nullable": true, "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$", "readOnly": true }, "paused": { "type": "boolean", "default": false, "x-auditable": true }, "public_endpoint_id": { "type": "string", "nullable": true, "readOnly": true }, "public_endpoint_params": { "type": "object", "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } }, "x-auditable": true }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true }, "retrieval_options": { "type": "object", "nullable": true, "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ] } }, "x-auditable": true }, "rewrite_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0, "x-auditable": true }, "source": { "type": "string", "nullable": true, "x-auditable": true }, "source_params": { "type": "object", "nullable": true, "properties": { "exclude_items": { "description": "List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/admin/**", "/private/**", "**\\temp\\**" ], "maxItems": 10 }, "include_items": { "description": "List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/blog/**", "/docs/**/*.html", "**\\blog\\**.html" ], "maxItems": 10 }, "prefix": { "type": "string" }, "r2_jurisdiction": { "type": "string", "default": "default" }, "web_crawler": { "type": "object", "default": { "parse_type": "sitemap" }, "properties": { "discover_options": { "description": "Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'.", "type": "object", "properties": { "depth": { "description": "Maximum link-follow depth from the seed URL.", "type": "number", "example": 5, "default": 5, "maximum": 100000, "minimum": 1 }, "include_external_links": { "description": "Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own.", "type": "boolean", "example": false, "default": false }, "include_subdomains": { "description": "Follow links to subdomains of the source host.", "type": "boolean", "example": false, "default": false }, "limit": { "description": "Maximum number of pages to crawl (1-100000).", "type": "number", "example": 10000, "default": 100000, "maximum": 100000, "minimum": 1 }, "max_age": { "description": "Maximum content age in seconds to accept (0–604800).", "type": "number", "example": 86400, "default": 86400, "maximum": 604800, "minimum": 0 }, "source": { "description": "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both.", "type": "string", "example": "all", "default": "all", "enum": [ "all", "sitemaps", "links" ] } } }, "parse_options": { "type": "object", "properties": { "content_selector": { "description": "List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected.", "type": "array", "items": { "properties": { "path": { "description": "Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.", "type": "string", "example": "**/article/**", "maxLength": 200, "minLength": 1 }, "selector": { "description": "CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \\). Must target a single element; if multiple elements match, the selector is ignored and the full page is used.", "type": "string", "example": "article div.post-body", "maxLength": 200, "minLength": 1 } }, "required": [ "path", "selector" ], "type": "object" }, "example": [ { "path": "**/blog/**", "selector": "article div.post-body" }, { "path": "**/docs/**", "selector": "main" } ], "maxItems": 10, "minItems": 1 }, "include_headers": { "description": "Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF).", "type": "object", "example": { "cache-control": "no-cache, no-store" }, "additionalProperties": { "maxLength": 8192, "pattern": "^[\\t\\x20-\\x7E]*$", "type": "string" } }, "include_images": { "type": "boolean", "default": false }, "specific_sitemaps": { "description": "List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.", "type": "array", "items": { "format": "uri", "type": "string" }, "example": [ "https://example.com/sitemap.xml", "https://example.com/blog-sitemap.xml" ], "maxItems": 10 }, "use_browser_rendering": { "type": "boolean", "default": true } } }, "parse_type": { "description": "How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true }, "status": { "type": "string", "default": "waiting", "readOnly": true }, "sync_interval": { "description": "Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).", "default": 21600, "anyOf": [ { "enum": [ 900 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 14400 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" } ], "x-auditable": true }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true }, "type": { "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true } }, "required": [ "id", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Ai search instance invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "403": { "description": "Max instances reached.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "create", "x-forge-params": { "id": { "description": "Unique ID for the new AI Search instance.", "positional": true }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" }, "source": { "description": "R2 bucket name or root website URL to index." }, "source_params": { "description": "Optional data source settings as a JSON object." }, "type": { "description": "Data source type: r2 or web-crawler." } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}": { "delete": { "operationId": "ai-search-namespace-delete-instance", "summary": "Delete an AI Search instance.", "description": "Permanently delete an AI Search instance and all its indexed data.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "my-ai-search" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "responses": { "200": { "description": "Returns the deleted instance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "ai_gateway_id": { "type": "string", "nullable": true, "x-auditable": true }, "ai_search_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "cache": { "type": "boolean", "default": true, "x-auditable": true }, "cache_threshold": { "type": "string", "default": "close_enough", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ], "x-auditable": true }, "cache_ttl": { "description": "Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).", "default": 172800, "anyOf": [ { "enum": [ 600 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" }, { "enum": [ 172800 ], "type": "number" }, { "enum": [ 259200 ], "type": "number" }, { "enum": [ 518400 ], "type": "number" } ], "x-auditable": true }, "chunk_overlap": { "type": "integer", "default": 10, "maximum": 30, "minimum": 0, "x-auditable": true }, "chunk_size": { "type": "integer", "minimum": 64, "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "nullable": true, "readOnly": true }, "custom_metadata": { "type": "array", "items": { "properties": { "data_type": { "type": "string", "enum": [ "text", "number", "boolean", "datetime" ] }, "field_name": { "type": "string", "maxLength": 64, "minLength": 1 } }, "required": [ "field_name", "data_type" ], "type": "object" }, "maxItems": 5, "x-auditable": true }, "embedding_model": { "type": "string", "nullable": true, "x-auditable": true }, "enable": { "type": "boolean", "default": true, "x-auditable": true }, "engine_version": { "type": "number", "default": 3, "readOnly": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead.", "type": "boolean", "default": false, "deprecated": true, "x-auditable": true }, "id": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "index_method": { "description": "Controls which storage backends are used during indexing. Defaults to vector-only.", "type": "object", "default": { "keyword": false, "vector": true }, "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean" } }, "required": [ "vector", "keyword" ], "x-auditable": true }, "indexing_options": { "type": "object", "nullable": true, "properties": { "keyword_tokenizer": { "description": "Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.", "type": "string", "default": "porter", "enum": [ "porter", "trigram" ] }, "use_ocr": { "description": "Enables OCR ingestion for PDFs and images. Changing this triggers a full re-index. Defaults to false.", "type": "boolean", "default": false } }, "x-auditable": true }, "last_activity": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1, "x-auditable": true }, "metadata": { "type": "object", "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "worker_domain": { "type": "string" } }, "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "nullable": true, "readOnly": true }, "namespace": { "type": "string", "nullable": true, "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$", "readOnly": true }, "paused": { "type": "boolean", "default": false, "x-auditable": true }, "public_endpoint_id": { "type": "string", "nullable": true, "readOnly": true }, "public_endpoint_params": { "type": "object", "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } }, "x-auditable": true }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true }, "retrieval_options": { "type": "object", "nullable": true, "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ] } }, "x-auditable": true }, "rewrite_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0, "x-auditable": true }, "source": { "type": "string", "nullable": true, "x-auditable": true }, "source_params": { "type": "object", "nullable": true, "properties": { "exclude_items": { "description": "List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/admin/**", "/private/**", "**\\temp\\**" ], "maxItems": 10 }, "include_items": { "description": "List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/blog/**", "/docs/**/*.html", "**\\blog\\**.html" ], "maxItems": 10 }, "prefix": { "type": "string" }, "r2_jurisdiction": { "type": "string", "default": "default" }, "web_crawler": { "type": "object", "default": { "parse_type": "sitemap" }, "properties": { "discover_options": { "description": "Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'.", "type": "object", "properties": { "depth": { "description": "Maximum link-follow depth from the seed URL.", "type": "number", "example": 5, "default": 5, "maximum": 100000, "minimum": 1 }, "include_external_links": { "description": "Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own.", "type": "boolean", "example": false, "default": false }, "include_subdomains": { "description": "Follow links to subdomains of the source host.", "type": "boolean", "example": false, "default": false }, "limit": { "description": "Maximum number of pages to crawl (1-100000).", "type": "number", "example": 10000, "default": 100000, "maximum": 100000, "minimum": 1 }, "max_age": { "description": "Maximum content age in seconds to accept (0–604800).", "type": "number", "example": 86400, "default": 86400, "maximum": 604800, "minimum": 0 }, "source": { "description": "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both.", "type": "string", "example": "all", "default": "all", "enum": [ "all", "sitemaps", "links" ] } } }, "parse_options": { "type": "object", "properties": { "content_selector": { "description": "List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected.", "type": "array", "items": { "properties": { "path": { "description": "Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.", "type": "string", "example": "**/article/**", "maxLength": 200, "minLength": 1 }, "selector": { "description": "CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \\). Must target a single element; if multiple elements match, the selector is ignored and the full page is used.", "type": "string", "example": "article div.post-body", "maxLength": 200, "minLength": 1 } }, "required": [ "path", "selector" ], "type": "object" }, "example": [ { "path": "**/blog/**", "selector": "article div.post-body" }, { "path": "**/docs/**", "selector": "main" } ], "maxItems": 10, "minItems": 1 }, "include_headers": { "description": "Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF).", "type": "object", "example": { "cache-control": "no-cache, no-store" }, "additionalProperties": { "maxLength": 8192, "pattern": "^[\\t\\x20-\\x7E]*$", "type": "string" } }, "include_images": { "type": "boolean", "default": false }, "specific_sitemaps": { "description": "List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.", "type": "array", "items": { "format": "uri", "type": "string" }, "example": [ "https://example.com/sitemap.xml", "https://example.com/blog-sitemap.xml" ], "maxItems": 10 }, "use_browser_rendering": { "type": "boolean", "default": true } } }, "parse_type": { "description": "How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true }, "status": { "type": "string", "default": "waiting", "readOnly": true }, "sync_interval": { "description": "Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).", "default": 21600, "anyOf": [ { "enum": [ 900 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 14400 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" } ], "x-auditable": true }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true }, "type": { "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true } }, "required": [ "id", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "409": { "description": "Instance status modified concurrently please retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "delete", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } }, "x-forge-require-confirmation": "This operation permanently deletes the AI Search instance and all its indexed data." }, "get": { "operationId": "ai-search-namespace-fetch-instance", "summary": "Get an AI Search instance.", "description": "Retrieve the configuration and status of an AI Search instance.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "my-ai-search" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "responses": { "200": { "description": "Returns the instance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "ai_gateway_id": { "type": "string", "nullable": true, "x-auditable": true }, "ai_search_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "cache": { "type": "boolean", "default": true, "x-auditable": true }, "cache_threshold": { "type": "string", "default": "close_enough", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ], "x-auditable": true }, "cache_ttl": { "description": "Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).", "default": 172800, "anyOf": [ { "enum": [ 600 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" }, { "enum": [ 172800 ], "type": "number" }, { "enum": [ 259200 ], "type": "number" }, { "enum": [ 518400 ], "type": "number" } ], "x-auditable": true }, "chunk_overlap": { "type": "integer", "default": 10, "maximum": 30, "minimum": 0, "x-auditable": true }, "chunk_size": { "type": "integer", "minimum": 64, "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "nullable": true, "readOnly": true }, "custom_metadata": { "type": "array", "items": { "properties": { "data_type": { "type": "string", "enum": [ "text", "number", "boolean", "datetime" ] }, "field_name": { "type": "string", "maxLength": 64, "minLength": 1 } }, "required": [ "field_name", "data_type" ], "type": "object" }, "maxItems": 5, "x-auditable": true }, "embedding_model": { "type": "string", "nullable": true, "x-auditable": true }, "enable": { "type": "boolean", "default": true, "x-auditable": true }, "engine_version": { "type": "number", "default": 3, "readOnly": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead.", "type": "boolean", "default": false, "deprecated": true, "x-auditable": true }, "id": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "index_method": { "description": "Controls which storage backends are used during indexing. Defaults to vector-only.", "type": "object", "default": { "keyword": false, "vector": true }, "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean" } }, "required": [ "vector", "keyword" ], "x-auditable": true }, "indexing_options": { "type": "object", "nullable": true, "properties": { "keyword_tokenizer": { "description": "Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.", "type": "string", "default": "porter", "enum": [ "porter", "trigram" ] }, "use_ocr": { "description": "Enables OCR ingestion for PDFs and images. Changing this triggers a full re-index. Defaults to false.", "type": "boolean", "default": false } }, "x-auditable": true }, "last_activity": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1, "x-auditable": true }, "metadata": { "type": "object", "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "worker_domain": { "type": "string" } }, "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "nullable": true, "readOnly": true }, "namespace": { "type": "string", "nullable": true, "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$", "readOnly": true }, "paused": { "type": "boolean", "default": false, "x-auditable": true }, "public_endpoint_id": { "type": "string", "nullable": true, "readOnly": true }, "public_endpoint_params": { "type": "object", "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } }, "x-auditable": true }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true }, "retrieval_options": { "type": "object", "nullable": true, "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ] } }, "x-auditable": true }, "rewrite_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0, "x-auditable": true }, "source": { "type": "string", "nullable": true, "x-auditable": true }, "source_params": { "type": "object", "nullable": true, "properties": { "exclude_items": { "description": "List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/admin/**", "/private/**", "**\\temp\\**" ], "maxItems": 10 }, "include_items": { "description": "List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/blog/**", "/docs/**/*.html", "**\\blog\\**.html" ], "maxItems": 10 }, "prefix": { "type": "string" }, "r2_jurisdiction": { "type": "string", "default": "default" }, "web_crawler": { "type": "object", "default": { "parse_type": "sitemap" }, "properties": { "discover_options": { "description": "Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'.", "type": "object", "properties": { "depth": { "description": "Maximum link-follow depth from the seed URL.", "type": "number", "example": 5, "default": 5, "maximum": 100000, "minimum": 1 }, "include_external_links": { "description": "Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own.", "type": "boolean", "example": false, "default": false }, "include_subdomains": { "description": "Follow links to subdomains of the source host.", "type": "boolean", "example": false, "default": false }, "limit": { "description": "Maximum number of pages to crawl (1-100000).", "type": "number", "example": 10000, "default": 100000, "maximum": 100000, "minimum": 1 }, "max_age": { "description": "Maximum content age in seconds to accept (0–604800).", "type": "number", "example": 86400, "default": 86400, "maximum": 604800, "minimum": 0 }, "source": { "description": "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both.", "type": "string", "example": "all", "default": "all", "enum": [ "all", "sitemaps", "links" ] } } }, "parse_options": { "type": "object", "properties": { "content_selector": { "description": "List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected.", "type": "array", "items": { "properties": { "path": { "description": "Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.", "type": "string", "example": "**/article/**", "maxLength": 200, "minLength": 1 }, "selector": { "description": "CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \\). Must target a single element; if multiple elements match, the selector is ignored and the full page is used.", "type": "string", "example": "article div.post-body", "maxLength": 200, "minLength": 1 } }, "required": [ "path", "selector" ], "type": "object" }, "example": [ { "path": "**/blog/**", "selector": "article div.post-body" }, { "path": "**/docs/**", "selector": "main" } ], "maxItems": 10, "minItems": 1 }, "include_headers": { "description": "Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF).", "type": "object", "example": { "cache-control": "no-cache, no-store" }, "additionalProperties": { "maxLength": 8192, "pattern": "^[\\t\\x20-\\x7E]*$", "type": "string" } }, "include_images": { "type": "boolean", "default": false }, "specific_sitemaps": { "description": "List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.", "type": "array", "items": { "format": "uri", "type": "string" }, "example": [ "https://example.com/sitemap.xml", "https://example.com/blog-sitemap.xml" ], "maxItems": 10 }, "use_browser_rendering": { "type": "boolean", "default": true } } }, "parse_type": { "description": "How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true }, "status": { "type": "string", "default": "waiting", "readOnly": true }, "sync_interval": { "description": "Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).", "default": 21600, "anyOf": [ { "enum": [ 900 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 14400 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" } ], "x-auditable": true }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true }, "type": { "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true } }, "required": [ "id", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "get", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } } }, "patch": { "operationId": "ai-search-move-instance", "summary": "Move an instance to a different namespace.", "description": "Moves an instance from its current namespace to the specified target namespace. Use 'default' with --destination-namespace to move the instance back to the default namespace. Fails with 400 if the target namespace already has an instance with the same id (ids must be unique within a namespace — the same id can exist in different namespaces).", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "description": "Current namespace of the instance.", "required": true, "schema": { "description": "Current namespace of the instance.", "type": "string", "example": "production" } }, { "name": "id", "in": "path", "description": "Instance id.", "required": true, "schema": { "description": "Instance id.", "type": "string", "example": "my-blog" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "new_namespace": { "description": "Target namespace to move the instance into.", "type": "string", "example": "staging", "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$" } }, "required": [ "new_namespace" ] } } } }, "responses": { "200": { "description": "Instance moved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "additionalProperties": false }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Ai search with this name already exist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Namespaces" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "move", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "name": { "default": "default", "description": "Namespace currently containing the instance.", "flagName": "source-namespace" }, "new_namespace": { "description": "Namespace to move the instance into.", "flagName": "destination-namespace" } } }, "put": { "operationId": "ai-search-namespace-update-instance", "summary": "Update an AI Search instance.", "description": "Update the configuration of an AI Search instance.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "my-ai-search" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_gateway_id": { "type": "string", "nullable": true, "x-auditable": true }, "ai_search_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "cache": { "type": "boolean", "default": true, "x-auditable": true }, "cache_threshold": { "type": "string", "default": "close_enough", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ], "x-auditable": true }, "cache_ttl": { "description": "Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).", "default": 172800, "anyOf": [ { "enum": [ 600 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" }, { "enum": [ 172800 ], "type": "number" }, { "enum": [ 259200 ], "type": "number" }, { "enum": [ 518400 ], "type": "number" } ], "x-auditable": true }, "chunk": { "type": "boolean", "default": true, "x-auditable": true }, "chunk_overlap": { "type": "integer", "default": 10, "maximum": 30, "minimum": 0, "x-auditable": true }, "chunk_size": { "type": "integer", "minimum": 64, "x-auditable": true }, "custom_metadata": { "type": "array", "items": { "properties": { "data_type": { "type": "string", "enum": [ "text", "number", "boolean", "datetime" ] }, "field_name": { "type": "string", "maxLength": 64, "minLength": 1 } }, "required": [ "field_name", "data_type" ], "type": "object" }, "maxItems": 5, "x-auditable": true }, "embedding_model": { "type": "string", "nullable": true, "x-auditable": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "index_method": { "description": "Controls which storage backends are used during indexing. Defaults to vector-only.", "type": "object", "default": { "keyword": false, "vector": true }, "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean" } }, "required": [ "vector", "keyword" ], "x-auditable": true }, "indexing_options": { "type": "object", "nullable": true, "properties": { "keyword_tokenizer": { "description": "Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.", "type": "string", "default": "porter", "enum": [ "porter", "trigram" ] }, "use_ocr": { "description": "Enables OCR ingestion for PDFs and images. Changing this triggers a full re-index. Defaults to false.", "type": "boolean", "default": false } }, "x-auditable": true }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1, "x-auditable": true }, "metadata": { "type": "object", "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "worker_domain": { "type": "string" } }, "x-auditable": true }, "paused": { "type": "boolean", "default": false, "x-auditable": true }, "public_endpoint_params": { "type": "object", "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } }, "x-auditable": true }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true }, "retrieval_options": { "type": "object", "nullable": true, "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ] } }, "x-auditable": true }, "rewrite_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0, "x-auditable": true }, "source": { "type": "string", "nullable": true, "x-auditable": true }, "source_params": { "type": "object", "nullable": true, "properties": { "exclude_items": { "description": "List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/admin/**", "/private/**", "**\\temp\\**" ], "maxItems": 10 }, "include_items": { "description": "List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/blog/**", "/docs/**/*.html", "**\\blog\\**.html" ], "maxItems": 10 }, "prefix": { "type": "string" }, "r2_jurisdiction": { "type": "string", "default": "default" }, "web_crawler": { "type": "object", "default": { "parse_type": "sitemap" }, "properties": { "discover_options": { "description": "Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'.", "type": "object", "properties": { "depth": { "description": "Maximum link-follow depth from the seed URL.", "type": "number", "example": 5, "default": 5, "maximum": 100000, "minimum": 1 }, "include_external_links": { "description": "Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own.", "type": "boolean", "example": false, "default": false }, "include_subdomains": { "description": "Follow links to subdomains of the source host.", "type": "boolean", "example": false, "default": false }, "limit": { "description": "Maximum number of pages to crawl (1-100000).", "type": "number", "example": 10000, "default": 100000, "maximum": 100000, "minimum": 1 }, "max_age": { "description": "Maximum content age in seconds to accept (0–604800).", "type": "number", "example": 86400, "default": 86400, "maximum": 604800, "minimum": 0 }, "source": { "description": "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both.", "type": "string", "example": "all", "default": "all", "enum": [ "all", "sitemaps", "links" ] } } }, "parse_options": { "type": "object", "properties": { "content_selector": { "description": "List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected.", "type": "array", "items": { "properties": { "path": { "description": "Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.", "type": "string", "example": "**/article/**", "maxLength": 200, "minLength": 1 }, "selector": { "description": "CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \\). Must target a single element; if multiple elements match, the selector is ignored and the full page is used.", "type": "string", "example": "article div.post-body", "maxLength": 200, "minLength": 1 } }, "required": [ "path", "selector" ], "type": "object" }, "example": [ { "path": "**/blog/**", "selector": "article div.post-body" }, { "path": "**/docs/**", "selector": "main" } ], "maxItems": 10, "minItems": 1 }, "include_headers": { "description": "Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF).", "type": "object", "example": { "cache-control": "no-cache, no-store" }, "additionalProperties": { "maxLength": 8192, "pattern": "^[\\t\\x20-\\x7E]*$", "type": "string" } }, "include_images": { "type": "boolean", "default": false }, "specific_sitemaps": { "description": "List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.", "type": "array", "items": { "format": "uri", "type": "string" }, "example": [ "https://example.com/sitemap.xml", "https://example.com/blog-sitemap.xml" ], "maxItems": 10 }, "use_browser_rendering": { "type": "boolean", "default": true } } }, "parse_type": { "description": "How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true }, "summarization": { "type": "boolean", "default": false, "x-auditable": true }, "summarization_model": { "type": "string", "nullable": true, "x-auditable": true }, "sync_interval": { "description": "Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).", "default": 21600, "anyOf": [ { "enum": [ 900 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 14400 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" } ], "x-auditable": true }, "system_prompt_ai_search": { "type": "string", "nullable": true, "x-auditable": true }, "system_prompt_index_summarization": { "type": "string", "nullable": true, "x-auditable": true }, "system_prompt_rewrite_query": { "type": "string", "nullable": true, "x-auditable": true }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true } } } } } }, "responses": { "200": { "description": "Returns the updated instance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "ai_gateway_id": { "type": "string", "nullable": true, "x-auditable": true }, "ai_search_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "cache": { "type": "boolean", "default": true, "x-auditable": true }, "cache_threshold": { "type": "string", "default": "close_enough", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ], "x-auditable": true }, "cache_ttl": { "description": "Cache entry TTL in seconds. Allowed values: 600 (10min), 1800 (30min), 3600 (1h), 7200 (2h), 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h), 259200 (72h), 518400 (6d).", "default": 172800, "anyOf": [ { "enum": [ 600 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" }, { "enum": [ 172800 ], "type": "number" }, { "enum": [ 259200 ], "type": "number" }, { "enum": [ 518400 ], "type": "number" } ], "x-auditable": true }, "chunk_overlap": { "type": "integer", "default": 10, "maximum": 30, "minimum": 0, "x-auditable": true }, "chunk_size": { "type": "integer", "minimum": 64, "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "nullable": true, "readOnly": true }, "custom_metadata": { "type": "array", "items": { "properties": { "data_type": { "type": "string", "enum": [ "text", "number", "boolean", "datetime" ] }, "field_name": { "type": "string", "maxLength": 64, "minLength": 1 } }, "required": [ "field_name", "data_type" ], "type": "object" }, "maxItems": 5, "x-auditable": true }, "embedding_model": { "type": "string", "nullable": true, "x-auditable": true }, "enable": { "type": "boolean", "default": true, "x-auditable": true }, "engine_version": { "type": "number", "default": 3, "readOnly": true }, "fusion_method": { "type": "string", "default": "rrf", "enum": [ "max", "rrf" ], "x-auditable": true }, "hybrid_search_enabled": { "description": "Deprecated — use index_method instead.", "type": "boolean", "default": false, "deprecated": true, "x-auditable": true }, "id": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true }, "index_method": { "description": "Controls which storage backends are used during indexing. Defaults to vector-only.", "type": "object", "default": { "keyword": false, "vector": true }, "properties": { "keyword": { "description": "Enable keyword (BM25) storage backend.", "type": "boolean" }, "vector": { "description": "Enable vector (embedding) storage backend.", "type": "boolean" } }, "required": [ "vector", "keyword" ], "x-auditable": true }, "indexing_options": { "type": "object", "nullable": true, "properties": { "keyword_tokenizer": { "description": "Tokenizer used for keyword search indexing. porter provides word-level tokenization with Porter stemming (good for natural language queries). trigram enables character-level substring matching (good for partial matches, code, identifiers). Changing this triggers a full re-index. Defaults to porter.", "type": "string", "default": "porter", "enum": [ "porter", "trigram" ] }, "use_ocr": { "description": "Enables OCR ingestion for PDFs and images. Changing this triggers a full re-index. Defaults to false.", "type": "boolean", "default": false } }, "x-auditable": true }, "last_activity": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1, "x-auditable": true }, "metadata": { "type": "object", "properties": { "created_from_aisearch_wizard": { "type": "boolean" }, "worker_domain": { "type": "string" } }, "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "nullable": true, "readOnly": true }, "namespace": { "type": "string", "nullable": true, "pattern": "^[a-z0-9]([a-z0-9-]{0,26}[a-z0-9])?$", "readOnly": true }, "paused": { "type": "boolean", "default": false, "x-auditable": true }, "public_endpoint_id": { "type": "string", "nullable": true, "readOnly": true }, "public_endpoint_params": { "type": "object", "properties": { "authorized_hosts": { "type": "array", "items": { "type": "string" } }, "chat_completions_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable chat completions endpoint for this public endpoint", "type": "boolean", "default": false } } }, "custom_domains": { "description": "Custom domain hostnames that alias this public endpoint. GET and create responses return the current set; on update (PUT) this field is only echoed back when supplied in the request body, otherwise it is null (omit it to leave domains unchanged).", "type": "array", "items": { "description": "Custom domain hostname (must be a Verified zone on this account).", "example": "search.example.com", "maxLength": 253, "minLength": 1, "type": "string" }, "maxItems": 1, "nullable": true, "x-auditable": true }, "default_domain_enabled": { "description": "When false, the instance is reachable only via a registered custom domain and the default .search.ai.cloudflare.com host returns 404. Requires at least one custom domain. Defaults to true. public_endpoint_params is replaced wholesale on update, so resend default_domain_enabled on every update to keep the default host off — omitting it resets to true.", "type": "boolean", "default": true, "x-auditable": true }, "enabled": { "type": "boolean", "default": false }, "mcp": { "type": "object", "properties": { "description": { "type": "string", "default": "Finds exactly what you're looking for" }, "disabled": { "description": "Disable MCP endpoint for this public endpoint", "type": "boolean", "default": false } } }, "rate_limit": { "type": "object", "properties": { "period_ms": { "type": "integer", "maximum": 3600000, "minimum": 60000 }, "requests": { "type": "integer", "minimum": 1 }, "technique": { "type": "string", "enum": [ "fixed", "sliding" ] } } }, "search_endpoint": { "type": "object", "properties": { "disabled": { "description": "Disable search endpoint for this public endpoint", "type": "boolean", "default": false } } } }, "x-auditable": true }, "reranking": { "type": "boolean", "default": false, "x-auditable": true }, "reranking_model": { "type": "string", "nullable": true, "x-auditable": true }, "retrieval_options": { "type": "object", "nullable": true, "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Each entry specifies a metadata field and an optional direction. Direction defaults to 'asc' for numeric/datetime fields and 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted on an update, the existing stored value is preserved; when never set, search falls back to 'and'.", "type": "string", "enum": [ "and", "or" ] } }, "x-auditable": true }, "rewrite_model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string", "nullable": true, "x-auditable": true }, "rewrite_query": { "type": "boolean", "default": false, "x-auditable": true }, "score_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0, "x-auditable": true }, "source": { "type": "string", "nullable": true, "x-auditable": true }, "source_params": { "type": "object", "nullable": true, "properties": { "exclude_items": { "description": "List of path patterns to exclude. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /admin/** matches /admin/users and /admin/settings/advanced). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/admin/**", "/private/**", "**\\temp\\**" ], "maxItems": 10 }, "include_items": { "description": "List of path patterns to include. Uses micromatch glob syntax: * matches within a path segment, ** matches across path segments (e.g., /blog/** matches /blog/post and /blog/2024/post). Most accounts are limited to 10 rules; contact support to raise it.", "type": "array", "items": { "maxLength": 500, "pattern": "^[*/\\\\]?[\\w\\-/.\\\\?*:=&%]+$", "type": "string" }, "example": [ "/blog/**", "/docs/**/*.html", "**\\blog\\**.html" ], "maxItems": 10 }, "prefix": { "type": "string" }, "r2_jurisdiction": { "type": "string", "default": "default" }, "web_crawler": { "type": "object", "default": { "parse_type": "sitemap" }, "properties": { "discover_options": { "description": "Options for parse_type 'discover', where Browser Run discovers URLs by link following and sitemaps. Ignored for 'sitemap'.", "type": "object", "properties": { "depth": { "description": "Maximum link-follow depth from the seed URL.", "type": "number", "example": 5, "default": 5, "maximum": 100000, "minimum": 1 }, "include_external_links": { "description": "Follow links that point outside the source domain. Must stay `false` — discover crawls are restricted to the zone you own.", "type": "boolean", "example": false, "default": false }, "include_subdomains": { "description": "Follow links to subdomains of the source host.", "type": "boolean", "example": false, "default": false }, "limit": { "description": "Maximum number of pages to crawl (1-100000).", "type": "number", "example": 10000, "default": 100000, "maximum": 100000, "minimum": 1 }, "max_age": { "description": "Maximum content age in seconds to accept (0–604800).", "type": "number", "example": 86400, "default": 86400, "maximum": 604800, "minimum": 0 }, "source": { "description": "Where the crawler looks for URLs: 'sitemaps' reads sitemap XML only, 'links' follows page links only, 'all' does both.", "type": "string", "example": "all", "default": "all", "enum": [ "all", "sitemaps", "links" ] } } }, "parse_options": { "type": "object", "properties": { "content_selector": { "description": "List of path-to-selector mappings for extracting specific content from crawled pages. Each entry pairs a URL glob pattern with a CSS selector. The first matching path wins. Only the matched HTML fragment is stored and indexed. Omit the field to disable content selection — empty arrays are rejected.", "type": "array", "items": { "properties": { "path": { "description": "Glob pattern to match against the page URL path. Uses standard glob syntax: * matches within a segment, ** crosses directories.", "type": "string", "example": "**/article/**", "maxLength": 200, "minLength": 1 }, "selector": { "description": "CSS selector to extract content from pages matching the path pattern. Must not contain disallowed characters (;, `, $, {, }, \\). Must target a single element; if multiple elements match, the selector is ignored and the full page is used.", "type": "string", "example": "article div.post-body", "maxLength": 200, "minLength": 1 } }, "required": [ "path", "selector" ], "type": "object" }, "example": [ { "path": "**/blog/**", "selector": "article div.post-body" }, { "path": "**/docs/**", "selector": "main" } ], "maxItems": 10, "minItems": 1 }, "include_headers": { "description": "Up to 5 custom HTTP headers sent with each crawl request. Names must be RFC-7230 token characters (no spaces, colons, or control characters); values must be HTAB + printable ASCII (no CR/LF).", "type": "object", "example": { "cache-control": "no-cache, no-store" }, "additionalProperties": { "maxLength": 8192, "pattern": "^[\\t\\x20-\\x7E]*$", "type": "string" } }, "include_images": { "type": "boolean", "default": false }, "specific_sitemaps": { "description": "List of specific sitemap URLs to use for crawling. Only valid when parse_type is 'sitemap'.", "type": "array", "items": { "format": "uri", "type": "string" }, "example": [ "https://example.com/sitemap.xml", "https://example.com/blog-sitemap.xml" ], "maxItems": 10 }, "use_browser_rendering": { "type": "boolean", "default": true } } }, "parse_type": { "description": "How URLs are discovered. 'sitemap' reads XML sitemaps; 'discover' follows links recursively and requires the source to be a Verified zone on this account.", "type": "string", "example": "sitemap", "default": "sitemap", "enum": [ "sitemap", "discover" ] } } } }, "x-auditable": true }, "status": { "type": "string", "default": "waiting", "readOnly": true }, "sync_interval": { "description": "Interval between automatic syncs, in seconds. Allowed values: 900 (15min), 1800 (30min), 3600 (1h), 7200 (2h), 14400 (4h), 21600 (6h), 43200 (12h), 86400 (24h).", "default": 21600, "anyOf": [ { "enum": [ 900 ], "type": "number" }, { "enum": [ 1800 ], "type": "number" }, { "enum": [ 3600 ], "type": "number" }, { "enum": [ 7200 ], "type": "number" }, { "enum": [ 14400 ], "type": "number" }, { "enum": [ 21600 ], "type": "number" }, { "enum": [ 43200 ], "type": "number" }, { "enum": [ 86400 ], "type": "number" } ], "x-auditable": true }, "token_id": { "type": "string", "format": "uuid", "x-auditable": true }, "type": { "type": "string", "enum": [ "r2", "web-crawler", null ], "nullable": true, "x-auditable": true } }, "required": [ "id", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Ai search instance invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "409": { "description": "Instance status modified concurrently please retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "update", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" }, "source": { "description": "R2 bucket name or root website URL to index." }, "source_params": { "description": "Optional data source settings as a JSON object." } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/chat/completions": { "post": { "operationId": "ai-search-namespace-instance-chat-completion", "summary": "Chat Completions", "description": "Performs a chat completion request against an AI Search instance, using indexed content as context for generating responses.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_search_options": { "type": "object", "properties": { "cache": { "type": "object", "properties": { "cache_threshold": { "type": "string", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ] }, "enabled": { "type": "boolean" } } }, "custom_metadata": { "description": "Metadata added to AI Gateway logs for requests triggered by this operation. Accepts up to 2 string, number, or boolean entries. Keys 'ai-search', 'task', 'origin', and keys beginning with 'cf.' are reserved.", "type": "object", "example": { "test": true, "user_id": "user-123" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "maxProperties": 2 }, "query_rewrite": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string" }, "rewrite_prompt": { "type": "string" } } }, "reranking": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "match_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0 }, "model": { "type": "string" } } }, "retrieval": { "type": "object", "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Overrides the instance-level boost_by config. Direction defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "context_expansion": { "type": "integer", "default": 0, "maximum": 3, "minimum": 0 }, "filters": { "type": "object", "additionalProperties": true }, "fusion_method": { "type": "string", "enum": [ "max", "rrf" ] }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted, falls back to the instance-level retrieval_options.keyword_match_mode, then to 'and'.", "type": "string", "enum": [ "and", "or" ] }, "match_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0 }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1 }, "retrieval_type": { "type": "string", "enum": [ "vector", "keyword", "hybrid" ] }, "return_on_failure": { "type": "boolean", "default": true } } } } }, "messages": { "type": "array", "items": { "additionalProperties": true, "properties": { "content": { "anyOf": [ { "type": "string" }, { "items": { "oneOf": [ { "properties": { "text": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type", "text" ], "type": "object" }, { "properties": { "image_url": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 20971520, "minLength": 1 } }, "required": [ "url" ] }, "type": { "type": "string", "enum": [ "image_url" ] } }, "required": [ "type", "image_url" ], "type": "object" }, { "properties": { "file": { "type": "object", "properties": { "file_data": { "type": "string", "maxLength": 13981144, "minLength": 1 }, "file_id": { "type": "string" }, "filename": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "filename" ] }, "type": { "type": "string", "enum": [ "file" ] } }, "required": [ "type", "file" ], "type": "object" } ] }, "minItems": 1, "type": "array" }, { "enum": [ null ], "nullable": true, "type": "string" } ] }, "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool" ] } }, "required": [ "role", "content" ], "type": "object" }, "minItems": 1 }, "model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string" }, "stream": { "type": "boolean" } }, "additionalProperties": true, "required": [ "messages" ] } } } }, "responses": { "200": { "description": "Returns the chat completions results with retrieved files.", "content": { "application/json": { "schema": { "type": "object", "properties": { "choices": { "type": "array", "items": { "properties": { "index": { "type": "integer" }, "message": { "type": "object", "additionalProperties": true, "properties": { "content": { "anyOf": [ { "type": "string" }, { "items": { "oneOf": [ { "properties": { "text": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type", "text" ], "type": "object" }, { "properties": { "image_url": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 20971520, "minLength": 1 } }, "required": [ "url" ] }, "type": { "type": "string", "enum": [ "image_url" ] } }, "required": [ "type", "image_url" ], "type": "object" }, { "properties": { "file": { "type": "object", "properties": { "file_data": { "type": "string", "maxLength": 13981144, "minLength": 1 }, "file_id": { "type": "string" }, "filename": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "filename" ] }, "type": { "type": "string", "enum": [ "file" ] } }, "required": [ "type", "file" ], "type": "object" } ] }, "minItems": 1, "type": "array" }, { "enum": [ null ], "nullable": true, "type": "string" } ] }, "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool" ] } }, "required": [ "role", "content" ] } }, "required": [ "message" ], "type": "object" } }, "chunks": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "item": { "type": "object", "properties": { "key": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "number" } }, "required": [ "key" ] }, "score": { "type": "number", "maximum": 1, "minimum": 0 }, "scoring_details": { "type": "object", "properties": { "fusion_method": { "type": "string", "enum": [ "rrf", "max" ] }, "keyword_rank": { "type": "number" }, "keyword_score": { "type": "number", "minimum": 0 }, "reranking_score": { "type": "number", "maximum": 1, "minimum": 0 }, "vector_rank": { "type": "number" }, "vector_score": { "type": "number", "maximum": 1, "minimum": 0 } } }, "text": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type", "score", "text" ], "type": "object" } }, "id": { "type": "string" }, "model": { "type": "string" }, "object": { "type": "string" } }, "additionalProperties": true, "required": [ "choices", "chunks" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "chat-completions", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items": { "get": { "operationId": "ai-search-namespace-instance-list-items", "summary": "Items List.", "description": "Lists indexed items in an AI Search instance.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50, "minimum": 0 } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 256 } }, { "name": "sort_by", "in": "query", "description": "Sort order for items. \"status\" (default) sorts by status priority then last_seen_at. \"modified_at\" sorts by file modification time (most recent first), falling back to created_at.", "schema": { "description": "Sort order for items. \"status\" (default) sorts by status priority then last_seen_at. \"modified_at\" sorts by file modification time (most recent first), falling back to created_at.", "type": "string", "default": "status", "enum": [ "status", "modified_at" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "running", "completed", "error", "skipped", "outdated" ] } }, { "name": "source", "in": "query", "description": "Filter items by source_id. Use \"builtin\" for uploaded files, or a source identifier like \"web-crawler:https://example.com\".", "schema": { "description": "Filter items by source_id. Use \"builtin\" for uploaded files, or a source identifier like \"web-crawler:https://example.com\".", "type": "string", "maxLength": 512 } }, { "name": "metadata_filter", "in": "query", "description": "JSON-encoded metadata filter using Vectorize filter syntax. Examples: {\"folder\":\"reports/\"}, {\"timestamp\":{\"$gte\":1700000000000}}, {\"folder\":{\"$in\":[\"docs/\",\"reports/\"]}}", "schema": { "description": "JSON-encoded metadata filter using Vectorize filter syntax. Examples: {\"folder\":\"reports/\"}, {\"timestamp\":{\"$gte\":1700000000000}}, {\"folder\":{\"$in\":[\"docs/\",\"reports/\"]}}", "type": "string", "maxLength": 2048 } }, { "name": "item_id", "in": "query", "description": "Filter items by their unique ID. Returns at most one item.", "schema": { "description": "Filter items by their unique ID. Returns at most one item.", "type": "string", "maxLength": 64 } }, { "name": "key", "in": "query", "description": "Filter items by their exact key (object key / filename). Keys are unique per source, so combine with `source` to disambiguate across data sources.", "schema": { "description": "Filter items by their exact key (object key / filename). Keys are unique per source, so combine with `source` to disambiguate across data sources.", "type": "string", "maxLength": 1024 } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "responses": { "200": { "description": "Returns the AI Search items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "checksum": { "type": "string", "readOnly": true }, "chunks_count": { "type": "integer", "nullable": true, "readOnly": true, "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "error": { "type": "string", "readOnly": true }, "file_size": { "type": "number", "nullable": true, "readOnly": true, "x-auditable": true }, "id": { "type": "string", "readOnly": true }, "key": { "type": "string", "readOnly": true }, "last_seen_at": { "type": "string", "format": "date-time", "readOnly": true }, "metadata": { "description": "Built-in, configured filterable, and retained source metadata for the item.", "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "nullable": true, "readOnly": true }, "namespace": { "type": "string", "readOnly": true }, "next_action": { "type": "string", "enum": [ "INDEX", "DELETE", null ], "nullable": true, "readOnly": true }, "source_id": { "description": "Identifies which data source this item belongs to. \"builtin\" for uploaded files, \"{type}:{source}\" for external sources, null for legacy items.", "type": "string", "nullable": true, "readOnly": true }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "error", "skipped", "outdated" ], "readOnly": true } }, "required": [ "id", "key", "status", "next_action", "checksum", "namespace", "chunks_count", "file_size", "metadata", "source_id", "last_seen_at", "created_at" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer", "default": 20, "maximum": 50, "minimum": 5 }, "total_count": { "type": "integer" } }, "required": [ "count", "page", "total_count" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Items" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.items", "x-fern-sdk-method-name": "list", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } } }, "post": { "operationId": "ai-search-namespace-instance-upload-item", "summary": "Upload Item.", "description": "Uploads a file to a managed AI Search instance via multipart/form-data.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "description": "The file to upload. Filename must not exceed 128 characters.", "type": "string", "format": "binary" }, "metadata": { "description": "JSON string of custom metadata key-value pairs.", "type": "string" }, "wait_for_completion": { "description": "Wait for indexing to fully complete before responding. On RAGs with vector indexing enabled, this additionally waits for Vectorize ingestion confirmation (up to 40s) so the returned item reflects a queryable state. On timeout the item is returned in `running` state and the background alarm continues polling. Defaults to false.", "type": "boolean", "default": false } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Item uploaded successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "checksum": { "type": "string", "readOnly": true }, "chunks_count": { "type": "integer", "nullable": true, "readOnly": true, "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "error": { "type": "string", "readOnly": true }, "file_size": { "type": "number", "nullable": true, "readOnly": true, "x-auditable": true }, "id": { "type": "string", "readOnly": true }, "key": { "type": "string", "readOnly": true }, "last_seen_at": { "type": "string", "format": "date-time", "readOnly": true }, "metadata": { "description": "Built-in, configured filterable, and retained source metadata for the item.", "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "nullable": true, "readOnly": true }, "namespace": { "type": "string", "readOnly": true }, "next_action": { "type": "string", "enum": [ "INDEX", "DELETE", null ], "nullable": true, "readOnly": true }, "source_id": { "description": "Identifies which data source this item belongs to. \"builtin\" for uploaded files, \"{type}:{source}\" for external sources, null for legacy items.", "type": "string", "nullable": true, "readOnly": true }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "error", "skipped", "outdated" ], "readOnly": true }, "warnings": { "type": "array", "items": { "oneOf": [ { "properties": { "code": { "type": "string", "enum": [ "custom_metadata_value_not_indexed" ] }, "expected_type": { "type": "string", "enum": [ "text", "number", "boolean", "datetime" ] }, "field": { "type": "string", "maxLength": 512 } }, "required": [ "code", "field", "expected_type" ], "type": "object" }, { "properties": { "code": { "type": "string", "enum": [ "custom_metadata_field_not_filterable" ] }, "field": { "type": "string", "maxLength": 512 } }, "required": [ "code", "field" ], "type": "object" } ] }, "maxItems": 10 } }, "required": [ "id", "key", "status", "next_action", "checksum", "namespace", "chunks_count", "file_size", "metadata", "source_id", "last_seen_at", "created_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Invalid metadata format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "409": { "description": "Item key already exist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "413": { "description": "File exceeds maximum size.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "429": { "description": "Item write rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Items" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.items", "x-fern-sdk-method-name": "upload", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } } }, "put": { "operationId": "ai-search-namespace-instance-create-or-update-item", "summary": "Create or Update Item.", "description": "Creates or updates an indexed item in an AI Search instance.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "description": "Item key / filename. Must not exceed 128 characters.", "type": "string" }, "next_action": { "type": "string", "enum": [ "INDEX" ] }, "wait_for_completion": { "description": "Wait for indexing to fully complete before responding. On RAGs with vector indexing enabled, this additionally waits for Vectorize ingestion confirmation (up to 40s) so the returned item reflects a queryable state. On timeout the item is returned in `running` state and the background alarm continues polling. Defaults to false.", "type": "boolean", "default": false } }, "required": [ "key", "next_action" ] } } } }, "responses": { "200": { "description": "Returns a AI Search Item detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "checksum": { "type": "string", "readOnly": true }, "chunks_count": { "type": "integer", "nullable": true, "readOnly": true, "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "error": { "type": "string", "readOnly": true }, "file_size": { "type": "number", "nullable": true, "readOnly": true, "x-auditable": true }, "id": { "type": "string", "readOnly": true }, "key": { "type": "string", "readOnly": true }, "last_seen_at": { "type": "string", "format": "date-time", "readOnly": true }, "metadata": { "description": "Built-in, configured filterable, and retained source metadata for the item.", "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "nullable": true, "readOnly": true }, "namespace": { "type": "string", "readOnly": true }, "next_action": { "type": "string", "enum": [ "INDEX", "DELETE", null ], "nullable": true, "readOnly": true }, "source_id": { "description": "Identifies which data source this item belongs to. \"builtin\" for uploaded files, \"{type}:{source}\" for external sources, null for legacy items.", "type": "string", "nullable": true, "readOnly": true }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "error", "skipped", "outdated" ], "readOnly": true } }, "required": [ "id", "key", "status", "next_action", "checksum", "namespace", "chunks_count", "file_size", "metadata", "source_id", "last_seen_at", "created_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Filename exceeds maximum length.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "409": { "description": "Item key already exist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to sync item.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Items" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.items", "x-fern-sdk-method-name": "upsert", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" }, "next_action": { "default": "INDEX", "hidden": true } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items/{item_id}": { "delete": { "operationId": "ai-search-namespace-instance-delete-item", "summary": "Delete Item.", "description": "Deletes a file from a managed AI Search instance and triggers a reindex.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "responses": { "200": { "description": "Item deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "This operation requires a managed instance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Item not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Items" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.items", "x-fern-sdk-method-name": "delete", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "item_id": { "description": "Indexed item ID.", "flagName": "item-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } } }, "get": { "operationId": "ai-search-namespace-instance-get-item", "summary": "Get Item.", "description": "Retrieves a specific indexed item from an AI Search instance.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "responses": { "200": { "description": "Returns a AI Search Item detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "checksum": { "type": "string", "readOnly": true }, "chunks_count": { "type": "integer", "nullable": true, "readOnly": true, "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "error": { "type": "string", "readOnly": true }, "file_size": { "type": "number", "nullable": true, "readOnly": true, "x-auditable": true }, "id": { "type": "string", "readOnly": true }, "key": { "type": "string", "readOnly": true }, "last_seen_at": { "type": "string", "format": "date-time", "readOnly": true }, "metadata": { "description": "Built-in, configured filterable, and retained source metadata for the item.", "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "nullable": true, "readOnly": true }, "namespace": { "type": "string", "readOnly": true }, "next_action": { "type": "string", "enum": [ "INDEX", "DELETE", null ], "nullable": true, "readOnly": true }, "source_id": { "description": "Identifies which data source this item belongs to. \"builtin\" for uploaded files, \"{type}:{source}\" for external sources, null for legacy items.", "type": "string", "nullable": true, "readOnly": true }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "error", "skipped", "outdated" ], "readOnly": true } }, "required": [ "id", "key", "status", "next_action", "checksum", "namespace", "chunks_count", "file_size", "metadata", "source_id", "last_seen_at", "created_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Job not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Items" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.items", "x-fern-sdk-method-name": "get", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "item_id": { "description": "Indexed item ID.", "flagName": "item-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } } }, "patch": { "operationId": "ai-search-namespace-instance-sync-item", "summary": "Sync Item.", "description": "Syncs an item to an AI Search instance index.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "next_action": { "type": "string", "enum": [ "INDEX" ] }, "wait_for_completion": { "description": "Wait for indexing to fully complete before responding. On RAGs with vector indexing enabled, this additionally waits for Vectorize ingestion confirmation (up to 40s) so the returned item reflects a queryable state. On timeout the item is returned in `running` state and the background alarm continues polling. Defaults to false.", "type": "boolean", "default": false } }, "required": [ "next_action" ] } } } }, "responses": { "200": { "description": "Returns a AI Search Item detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "checksum": { "type": "string", "readOnly": true }, "chunks_count": { "type": "integer", "nullable": true, "readOnly": true, "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "error": { "type": "string", "readOnly": true }, "file_size": { "type": "number", "nullable": true, "readOnly": true, "x-auditable": true }, "id": { "type": "string", "readOnly": true }, "key": { "type": "string", "readOnly": true }, "last_seen_at": { "type": "string", "format": "date-time", "readOnly": true }, "metadata": { "description": "Built-in, configured filterable, and retained source metadata for the item.", "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "nullable": true, "readOnly": true }, "namespace": { "type": "string", "readOnly": true }, "next_action": { "type": "string", "enum": [ "INDEX", "DELETE", null ], "nullable": true, "readOnly": true }, "source_id": { "description": "Identifies which data source this item belongs to. \"builtin\" for uploaded files, \"{type}:{source}\" for external sources, null for legacy items.", "type": "string", "nullable": true, "readOnly": true }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "error", "skipped", "outdated" ], "readOnly": true } }, "required": [ "id", "key", "status", "next_action", "checksum", "namespace", "chunks_count", "file_size", "metadata", "source_id", "last_seen_at", "created_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to sync item.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Items" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.items", "x-fern-sdk-method-name": "sync", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "item_id": { "description": "Indexed item ID.", "flagName": "item-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" }, "next_action": { "default": "INDEX", "hidden": true } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items/{item_id}/chunks": { "get": { "operationId": "ai-search-namespace-instance-list-item-chunks", "summary": "List Item Chunks.", "description": "Lists chunks for a specific item in an AI Search instance, including their text content.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "responses": { "200": { "description": "Returns the AI Search item chunks with text content.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "end_byte": { "type": "number" }, "id": { "type": "string" }, "item": { "type": "object", "properties": { "key": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "number" } }, "required": [ "key" ] }, "start_byte": { "type": "number" }, "text": { "type": "string" } }, "required": [ "id", "text", "item" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "count", "total", "limit", "offset" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Item not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Items" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.items", "x-fern-sdk-method-name": "chunks", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "item_id": { "description": "Indexed item ID.", "flagName": "item-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items/{item_id}/download": { "get": { "operationId": "ai-search-namespace-instance-get-item-content", "summary": "Download Item Content.", "description": "Downloads the raw file content for a specific item from the managed AI Search instance storage.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "responses": { "200": { "description": "Raw file content.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Content download not available for external source items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "403": { "description": "Items in this instance were crawled from a public site for search and AI input only. Full page content isn't available for download; use the search endpoint to retrieve cited excerpts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Item not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Items" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.items", "x-fern-sdk-method-name": "download", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "item_id": { "description": "Indexed item ID.", "flagName": "item-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/items/{item_id}/logs": { "get": { "operationId": "ai-search-namespace-instance-logs-item", "summary": "Item Logs.", "description": "Lists processing logs for a specific item in an AI Search instance.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 512 } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "responses": { "200": { "description": "Returns the AI Search item logs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "action": { "type": "string" }, "chunkCount": { "type": "integer", "nullable": true }, "errorType": { "type": "string", "nullable": true }, "fileKey": { "type": "string" }, "message": { "type": "string", "nullable": true }, "processingTimeMs": { "type": "integer", "nullable": true }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "timestamp", "action", "message", "fileKey", "chunkCount", "processingTimeMs", "errorType" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "cursor": { "type": "string", "nullable": true }, "per_page": { "type": "integer" }, "truncated": { "type": "boolean" } }, "required": [ "count", "per_page", "cursor", "truncated" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Item not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Items" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.items", "x-fern-sdk-method-name": "logs", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "item_id": { "description": "Indexed item ID.", "flagName": "item-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/jobs": { "get": { "operationId": "ai-search-namespace-instance-list-jobs", "summary": "List Jobs", "description": "Lists indexing jobs for an AI Search instance.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50, "minimum": 0 } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "responses": { "200": { "description": "Returns a list of AI Search Jobs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "description": { "type": "string" }, "end_reason": { "type": "string" }, "ended_at": { "type": "string" }, "id": { "type": "string", "x-auditable": true }, "last_seen_at": { "type": "string" }, "source": { "type": "string", "enum": [ "user", "schedule" ], "x-auditable": true }, "started_at": { "type": "string" } }, "required": [ "id", "source" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" } }, "required": [ "count", "page", "per_page", "total_count" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Jobs" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.jobs", "x-fern-sdk-method-name": "list", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } } }, "post": { "operationId": "ai-search-namespace-instance-create-job", "summary": "Create new job", "description": "Creates a new indexing job for an AI Search instance.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "Returns the AI Search job id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "description": { "type": "string" }, "end_reason": { "type": "string" }, "ended_at": { "type": "string" }, "id": { "type": "string", "x-auditable": true }, "last_seen_at": { "type": "string" }, "source": { "type": "string", "enum": [ "user", "schedule" ], "x-auditable": true }, "started_at": { "type": "string" } }, "required": [ "id", "source" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "429": { "description": "Sync in cooldown.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Jobs" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.jobs", "x-fern-sdk-method-name": "create", "x-forge-params": { "description": { "description": "Optional description for the indexing job." }, "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/jobs/{job_id}": { "get": { "operationId": "ai-search-namespace-instance-get-job", "summary": "Get a Job Details", "description": "Retrieves details for a specific AI Search indexing job.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "responses": { "200": { "description": "Returns a AI Search Job Details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "description": { "type": "string" }, "end_reason": { "type": "string" }, "ended_at": { "type": "string" }, "id": { "type": "string", "x-auditable": true }, "last_seen_at": { "type": "string" }, "source": { "type": "string", "enum": [ "user", "schedule" ], "x-auditable": true }, "started_at": { "type": "string" } }, "required": [ "id", "source" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Job not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Jobs" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.jobs", "x-fern-sdk-method-name": "get", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "job_id": { "description": "Indexing job ID.", "flagName": "job-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } } }, "patch": { "operationId": "ai-search-namespace-instance-change-job-status", "summary": "Cancel an indexing job.", "description": "Cancel an in-progress indexing job for an AI Search instance.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "cancel" ] } }, "required": [ "action" ] } } } }, "responses": { "200": { "description": "Returns the updated AI Search Job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "description": { "type": "string" }, "end_reason": { "type": "string" }, "ended_at": { "type": "string" }, "id": { "type": "string", "x-auditable": true }, "last_seen_at": { "type": "string" }, "source": { "type": "string", "enum": [ "user", "schedule" ], "x-auditable": true }, "started_at": { "type": "string" } }, "required": [ "id", "source" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Job cannot be cancelled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Job not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Jobs" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.jobs", "x-fern-sdk-method-name": "cancel", "x-forge-params": { "action": { "default": "cancel", "hidden": true }, "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "job_id": { "description": "Indexing job ID.", "flagName": "job-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } }, "x-forge-require-confirmation": "This operation cancels the running indexing job." } }, "/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/jobs/{job_id}/logs": { "get": { "operationId": "ai-search-namespace-instance-list-job-logs", "summary": "List Job Logs", "description": "Lists log entries for an AI Search indexing job.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 500, "minimum": 0 } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "responses": { "200": { "description": "Returns a list of AI Search Job Logs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "created_at": { "type": "number" }, "id": { "type": "integer" }, "message": { "type": "string" }, "message_type": { "type": "integer" } }, "required": [ "id", "message", "message_type", "created_at" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" } }, "required": [ "count", "page", "per_page", "total_count" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "Unable to connect to ai search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances Jobs" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.jobs", "x-fern-sdk-method-name": "logs", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "job_id": { "description": "Indexing job ID.", "flagName": "job-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/purge_cache": { "post": { "operationId": "ai-search-namespace-purge-instance-cache", "summary": "Purge search cache.", "description": "Purges all cached search results for an AI Search instance. A new internal cache key is generated, immediately orphaning all prior cached entries.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "responses": { "200": { "description": "Cache purged successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "404": { "description": "Ai search not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "purge-cache", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/search": { "post": { "operationId": "ai-search-namespace-instance-search", "summary": "Search", "description": "Executes a semantic search query against an AI Search instance to find relevant indexed content.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_search_options": { "type": "object", "properties": { "cache": { "type": "object", "properties": { "cache_threshold": { "type": "string", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ] }, "enabled": { "type": "boolean" } } }, "custom_metadata": { "description": "Metadata added to AI Gateway logs for requests triggered by this operation. Accepts up to 2 string, number, or boolean entries. Keys 'ai-search', 'task', 'origin', and keys beginning with 'cf.' are reserved.", "type": "object", "example": { "test": true, "user_id": "user-123" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "maxProperties": 2 }, "query_rewrite": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string" }, "rewrite_prompt": { "type": "string" } } }, "reranking": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "match_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0 }, "model": { "type": "string" } } }, "retrieval": { "type": "object", "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Overrides the instance-level boost_by config. Direction defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "context_expansion": { "type": "integer", "default": 0, "maximum": 3, "minimum": 0 }, "filters": { "type": "object", "additionalProperties": true }, "fusion_method": { "type": "string", "enum": [ "max", "rrf" ] }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted, falls back to the instance-level retrieval_options.keyword_match_mode, then to 'and'.", "type": "string", "enum": [ "and", "or" ] }, "match_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0 }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1 }, "retrieval_type": { "type": "string", "enum": [ "vector", "keyword", "hybrid" ] }, "return_on_failure": { "type": "boolean", "default": true } } } } }, "messages": { "description": "OpenAI-compatible message array. For multimodal queries, set the last user message's `content` to an array of typed parts: `[{type:'text', text:'…'}, {type:'image_url', image_url:{url:'…'}}]`. Image inputs require the RAG's embedding_model to declare 'image' in supported_modalities.", "type": "array", "items": { "additionalProperties": true, "properties": { "content": { "anyOf": [ { "type": "string" }, { "items": { "oneOf": [ { "properties": { "text": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type", "text" ], "type": "object" }, { "properties": { "image_url": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 20971520, "minLength": 1 } }, "required": [ "url" ] }, "type": { "type": "string", "enum": [ "image_url" ] } }, "required": [ "type", "image_url" ], "type": "object" }, { "properties": { "file": { "type": "object", "properties": { "file_data": { "type": "string", "maxLength": 13981144, "minLength": 1 }, "file_id": { "type": "string" }, "filename": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "filename" ] }, "type": { "type": "string", "enum": [ "file" ] } }, "required": [ "type", "file" ], "type": "object" } ] }, "minItems": 1, "type": "array" }, { "enum": [ null ], "nullable": true, "type": "string" } ] }, "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool" ] } }, "required": [ "role", "content" ], "type": "object" }, "minItems": 1 }, "query": { "description": "A simple text query string. Alternative to 'messages' — provide either this or 'messages', not both.", "minLength": 1, "type": "string" } } } } } }, "responses": { "200": { "description": "Returns the search results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "chunks": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "item": { "type": "object", "properties": { "key": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "number" } }, "required": [ "key" ] }, "score": { "type": "number", "maximum": 1, "minimum": 0 }, "scoring_details": { "type": "object", "properties": { "fusion_method": { "type": "string", "enum": [ "rrf", "max" ] }, "keyword_rank": { "type": "number" }, "keyword_score": { "type": "number", "minimum": 0 }, "reranking_score": { "type": "number", "maximum": 1, "minimum": 0 }, "vector_rank": { "type": "number" }, "vector_score": { "type": "number", "maximum": 1, "minimum": 0 } } }, "text": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type", "score", "text" ], "type": "object" } }, "query_kind": { "type": "string", "enum": [ "text", "image", "multimodal" ] }, "search_query": { "type": "string" } }, "required": [ "query_kind", "chunks" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "search", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" }, "query": { "description": "Text to search for.", "positional": true } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}/instances/{id}/stats": { "get": { "operationId": "ai-search-namespace-stats", "summary": "Get instance statistics.", "description": "Retrieve usage and indexing statistics for an AI Search instance.", "parameters": [ { "name": "id", "in": "path", "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "required": true, "schema": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "type": "string", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "x-auditable": true } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "responses": { "200": { "description": "Returns the AI Search stats.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "completed": { "type": "integer" }, "degraded": { "description": "True when status counts are unavailable (e.g. legacy stats query exceeded D1 statement-size limit). Counts are omitted in this case.", "type": "boolean" }, "engine": { "description": "Engine-specific metadata. Present only for managed (v3) instances.", "type": "object", "properties": { "r2": { "description": "R2 bucket storage usage in bytes.", "type": "object", "properties": { "metadataSizeBytes": { "type": "integer" }, "objectCount": { "type": "integer" }, "payloadSizeBytes": { "type": "integer" } }, "required": [ "payloadSizeBytes", "metadataSizeBytes", "objectCount" ] }, "vectorize": { "description": "Vectorize index metadata (dimensions, vector count).", "type": "object", "properties": { "dimensions": { "type": "integer" }, "vectorsCount": { "type": "integer" } }, "required": [ "vectorsCount", "dimensions" ] } } }, "error": { "type": "integer" }, "file_embed_errors": { "type": "object", "additionalProperties": true }, "index_source_errors": { "type": "object", "additionalProperties": true }, "last_activity": { "type": "string", "format": "date-time" }, "outdated": { "type": "integer" }, "queued": { "type": "integer" }, "running": { "type": "integer" }, "skipped": { "type": "integer" } } }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Instances" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "stats", "x-forge-params": { "id": { "description": "AI Search instance ID.", "flagName": "instance-id" }, "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" } } } }, "/accounts/{account_id}/ai-search/namespaces/{name}/search": { "post": { "operationId": "ai-search-namespace-multi-instance-search", "summary": "Multi-Instance Search", "description": "Performs a semantic search query against multiple AI Search instances in parallel, merging the retrieved results into a single ranked response.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "name", "in": "path", "description": "Namespace name", "required": true, "schema": { "type": "string" }, "example": "my-namespace" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_search_options": { "type": "object", "properties": { "cache": { "type": "object", "properties": { "cache_threshold": { "type": "string", "enum": [ "super_strict_match", "close_enough", "flexible_friend", "anything_goes" ] }, "enabled": { "type": "boolean" } } }, "custom_metadata": { "description": "Metadata added to AI Gateway logs for requests triggered by this operation. Accepts up to 2 string, number, or boolean entries. Keys 'ai-search', 'task', 'origin', and keys beginning with 'cf.' are reserved.", "type": "object", "example": { "test": true, "user_id": "user-123" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "maxProperties": 2 }, "instance_ids": { "type": "array", "items": { "description": "AI Search instance ID. Lowercase alphanumeric, hyphens, and underscores.", "example": "my-ai-search", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$", "type": "string", "x-auditable": true }, "minItems": 1 }, "query_rewrite": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "model": { "description": "A Workers AI model ID or an AI Gateway model ID compatible with the OpenAI Chat Completions API. An empty string uses the configured or default model.", "type": "string" }, "rewrite_prompt": { "type": "string" } } }, "reranking": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "match_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0 }, "model": { "type": "string" } } }, "retrieval": { "type": "object", "properties": { "boost_by": { "description": "Metadata fields to boost search results by. Overrides the instance-level boost_by config. Direction defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields. Fields must match 'timestamp' or a defined custom_metadata field.", "type": "array", "items": { "properties": { "direction": { "description": "Boost direction. 'desc' = higher values rank higher (e.g. newer timestamps). 'asc' = lower values rank higher. 'exists' = boost chunks that have the field. 'not_exists' = boost chunks that lack the field. Optional — defaults to 'asc' for numeric/datetime fields, 'exists' for text/boolean fields.", "type": "string", "enum": [ "asc", "desc", "exists", "not_exists" ] }, "field": { "description": "Metadata field name to boost by. Use 'timestamp' for document freshness, or any custom_metadata field. Numeric and datetime fields support all four directions (asc, desc, exists, not_exists); text/boolean fields only support exists/not_exists.", "type": "string", "example": "timestamp", "maxLength": 64, "minLength": 1 } }, "required": [ "field" ], "type": "object" }, "example": [ { "direction": "desc", "field": "timestamp" } ], "maxItems": 3 }, "context_expansion": { "type": "integer", "default": 0, "maximum": 3, "minimum": 0 }, "filters": { "type": "object", "additionalProperties": true }, "fusion_method": { "type": "string", "enum": [ "max", "rrf" ] }, "keyword_match_mode": { "description": "Controls which documents are candidates for BM25 scoring. 'and' restricts candidates to documents containing all query terms; 'or' includes any document containing at least one term, ranked by BM25 relevance. When omitted, falls back to the instance-level retrieval_options.keyword_match_mode, then to 'and'.", "type": "string", "enum": [ "and", "or" ] }, "match_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0 }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1 }, "retrieval_type": { "type": "string", "enum": [ "vector", "keyword", "hybrid" ] }, "return_on_failure": { "type": "boolean", "default": true } } } }, "required": [ "instance_ids" ] }, "messages": { "description": "OpenAI-compatible message array. For multimodal queries, set the last user message's `content` to an array of typed parts: `[{type:'text', text:'…'}, {type:'image_url', image_url:{url:'…'}}]`. Image inputs require the RAG's embedding_model to declare 'image' in supported_modalities.", "type": "array", "items": { "additionalProperties": true, "properties": { "content": { "anyOf": [ { "type": "string" }, { "items": { "oneOf": [ { "properties": { "text": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "text" ] } }, "required": [ "type", "text" ], "type": "object" }, { "properties": { "image_url": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 20971520, "minLength": 1 } }, "required": [ "url" ] }, "type": { "type": "string", "enum": [ "image_url" ] } }, "required": [ "type", "image_url" ], "type": "object" }, { "properties": { "file": { "type": "object", "properties": { "file_data": { "type": "string", "maxLength": 13981144, "minLength": 1 }, "file_id": { "type": "string" }, "filename": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "filename" ] }, "type": { "type": "string", "enum": [ "file" ] } }, "required": [ "type", "file" ], "type": "object" } ] }, "minItems": 1, "type": "array" }, { "enum": [ null ], "nullable": true, "type": "string" } ] }, "role": { "type": "string", "enum": [ "system", "developer", "user", "assistant", "tool" ] } }, "required": [ "role", "content" ], "type": "object" }, "minItems": 1 }, "query": { "description": "A simple text query string. Alternative to 'messages' — provide either this or 'messages', not both.", "minLength": 1, "type": "string" } }, "required": [ "ai_search_options" ] } } } }, "responses": { "200": { "description": "Returns the merged search results from all instances.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "chunks": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "instance_id": { "type": "string" }, "item": { "type": "object", "properties": { "key": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "number" } }, "required": [ "key" ] }, "score": { "type": "number", "maximum": 1, "minimum": 0 }, "scoring_details": { "type": "object", "properties": { "fusion_method": { "type": "string", "enum": [ "rrf", "max" ] }, "keyword_rank": { "type": "number" }, "keyword_score": { "type": "number", "minimum": 0 }, "reranking_score": { "type": "number", "maximum": 1, "minimum": 0 }, "vector_rank": { "type": "number" }, "vector_score": { "type": "number", "maximum": 1, "minimum": 0 } } }, "text": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type", "score", "text", "instance_id" ], "type": "object" } }, "errors": { "type": "array", "items": { "properties": { "instance_id": { "type": "string" }, "message": { "type": "string" } }, "required": [ "instance_id", "message" ], "type": "object" } }, "query_kind": { "type": "string", "enum": [ "text", "image", "multimodal" ] }, "search_query": { "type": "string" } }, "required": [ "query_kind", "chunks" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Account Search" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search", "x-fern-sdk-method-name": "multi-search", "x-forge-params": { "name": { "default": "default", "description": "Namespace to use for this operation.", "flagName": "namespace" }, "query": { "description": "Text to search for.", "positional": true } } } }, "/accounts/{account_id}/ai-search/tokens": { "get": { "operationId": "ai-search-list-tokens", "summary": "List tokens", "description": "List stored AI Search credentials in the account without exposing their secrets.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "page", "in": "query", "description": "Page number (1-indexed).", "schema": { "description": "Page number (1-indexed).", "type": "integer", "example": 1, "default": 1, "maximum": 100, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "description": "Number of results per page.", "type": "integer", "example": 20, "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Filter tokens whose name contains this string (case-insensitive).", "schema": { "description": "Filter tokens whose name contains this string (case-insensitive).", "type": "string", "example": "my-token", "maxLength": 256 } } ], "responses": { "200": { "description": "List of tokens.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "cf_api_id": { "type": "string", "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "nullable": true, "readOnly": true }, "enabled": { "type": "boolean", "default": true, "x-auditable": true }, "id": { "type": "string", "format": "uuid", "x-auditable": true }, "legacy": { "type": "boolean", "default": true, "readOnly": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "nullable": true, "readOnly": true }, "name": { "type": "string", "x-auditable": true } }, "required": [ "id", "name", "cf_api_id", "created_at", "modified_at" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "page", "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "result_info" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Tokens" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.tokens", "x-fern-sdk-method-name": "list" }, "post": { "operationId": "ai-search-create-tokens", "summary": "Create a token", "description": "Create a stored Cloudflare credential for an AI Search instance to access its data source.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cf_api_id": { "type": "string", "example": "a1b2c3d4e5f6" }, "cf_api_key": { "type": "string", "example": "abc123", "writeOnly": true, "x-sensitive": true }, "legacy": { "type": "boolean", "default": true }, "name": { "type": "string", "example": "my-token" } }, "required": [ "name", "cf_api_id", "cf_api_key" ] } } } }, "responses": { "201": { "description": "Token created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "cf_api_id": { "type": "string", "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "nullable": true, "readOnly": true }, "enabled": { "type": "boolean", "default": true, "x-auditable": true }, "id": { "type": "string", "format": "uuid", "x-auditable": true }, "legacy": { "type": "boolean", "default": true, "readOnly": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "nullable": true, "readOnly": true }, "name": { "type": "string", "x-auditable": true } }, "required": [ "id", "name", "cf_api_id", "created_at", "modified_at" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Ai search instance invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Tokens" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.tokens", "x-fern-sdk-method-name": "create", "x-forge-params": { "cf_api_id": { "description": "Cloudflare API token ID.", "flagName": "api-token-id" }, "cf_api_key": { "description": "Cloudflare API token value.", "flagName": "api-token" }, "legacy": { "description": "Whether the credential uses the legacy API key format." }, "name": { "description": "Human-readable name for the credential.", "positional": true } } } }, "/accounts/{account_id}/ai-search/tokens/{id}": { "delete": { "operationId": "ai-search-delete-tokens", "summary": "Delete a token", "description": "Permanently delete a stored AI Search credential. Credentials in use by an instance cannot be deleted.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "62af0db3-c410-40b2-9ee3-0e93f6dd1de0" } } ], "responses": { "200": { "description": "Token deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "additionalProperties": false }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Token not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "409": { "description": "Token in use by instances.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Tokens" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.tokens", "x-fern-sdk-method-name": "delete", "x-forge-params": { "id": { "description": "Stored credential record ID.", "flagName": "token-id" } }, "x-forge-require-confirmation": "This operation permanently deletes the stored credential." }, "get": { "operationId": "ai-search-fetch-tokens", "summary": "Get a token", "description": "Retrieve a stored AI Search credential without exposing its secret.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "62af0db3-c410-40b2-9ee3-0e93f6dd1de0" } } ], "responses": { "200": { "description": "Token details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "cf_api_id": { "type": "string", "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "nullable": true, "readOnly": true }, "enabled": { "type": "boolean", "default": true, "x-auditable": true }, "id": { "type": "string", "format": "uuid", "x-auditable": true }, "legacy": { "type": "boolean", "default": true, "readOnly": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "nullable": true, "readOnly": true }, "name": { "type": "string", "x-auditable": true } }, "required": [ "id", "name", "cf_api_id", "created_at", "modified_at" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Input Validation Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "path" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Token not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Tokens" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.tokens", "x-fern-sdk-method-name": "get", "x-forge-params": { "id": { "description": "Stored credential record ID.", "flagName": "token-id" } } }, "put": { "operationId": "ai-search-update-tokens", "summary": "Update a token", "description": "Replace a stored AI Search credential and invalidate cached credentials for instances that use it.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "62af0db3-c410-40b2-9ee3-0e93f6dd1de0" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cf_api_id": { "type": "string", "example": "a1b2c3d4e5f6" }, "cf_api_key": { "type": "string", "example": "abc123", "writeOnly": true, "x-sensitive": true }, "legacy": { "type": "boolean", "default": true }, "name": { "type": "string", "example": "my-token" } }, "required": [ "name", "cf_api_id", "cf_api_key" ] } } } }, "responses": { "200": { "description": "Returns the updated token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "cf_api_id": { "type": "string", "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "created_by": { "type": "string", "nullable": true, "readOnly": true }, "enabled": { "type": "boolean", "default": true, "x-auditable": true }, "id": { "type": "string", "format": "uuid", "x-auditable": true }, "legacy": { "type": "boolean", "default": true, "readOnly": true }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true }, "modified_by": { "type": "string", "nullable": true, "readOnly": true }, "name": { "type": "string", "x-auditable": true } }, "required": [ "id", "name", "cf_api_id", "created_at", "modified_at" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Ai search instance invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "Token not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Search Tokens" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai-search" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "ai-search.tokens", "x-fern-sdk-method-name": "update", "x-forge-params": { "cf_api_id": { "description": "Cloudflare API token ID.", "flagName": "api-token-id" }, "cf_api_key": { "description": "Cloudflare API token value.", "flagName": "api-token" }, "id": { "description": "Stored credential record ID.", "flagName": "token-id" }, "legacy": { "description": "Whether the credential uses the legacy API key format." }, "name": { "description": "Human-readable name for the credential." } } } }, "/accounts/{account_id}/ai/authors/search": { "get": { "operationId": "workers-ai-search-author", "summary": "Author Search", "description": "Searches Workers AI models by author or organization name.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } } ], "responses": { "200": { "description": "Returns a list of authors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "array", "items": { "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "result", "errors", "messages" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers AI" ], "x-api-token-group": [ "Workers AI Write", "Workers AI Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai.authors", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/ai/finetunes": { "get": { "operationId": "workers-ai-list-finetunes", "summary": "List Finetunes", "description": "Lists all fine-tuning jobs created by the account, including status and metrics.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } } ], "responses": { "200": { "description": "Returns all finetunes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "id": { "type": "string", "format": "uuid", "x-auditable": true }, "model": { "type": "string", "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "x-auditable": true } }, "required": [ "id", "model", "name", "created_at", "modified_at" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers AI Finetune" ], "x-api-token-group": [ "Workers AI Write", "Workers AI Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai.finetunes", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "workers-ai-create-finetune", "summary": "Create a new Finetune", "description": "Creates a new fine-tuning job for a Workers AI model using custom training data.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string" }, "model": { "type": "string", "x-auditable": true }, "name": { "type": "string", "x-auditable": true }, "public": { "type": "boolean", "default": false, "x-auditable": true } }, "required": [ "model", "name" ] } } } }, "responses": { "200": { "description": "Returns the created finetune.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "id": { "type": "string", "format": "uuid", "x-auditable": true }, "model": { "type": "string", "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "x-auditable": true }, "public": { "type": "boolean", "x-auditable": true } }, "required": [ "id", "created_at", "modified_at", "public", "name", "model" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Finetune creation failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "errors", "success" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers AI Finetune" ], "x-api-token-group": [ "Workers AI Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai.finetunes", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/ai/finetunes/public": { "get": { "operationId": "workers-ai-list-public-finetunes", "summary": "List Public Finetunes", "description": "Lists publicly available fine-tuned models that can be used with Workers AI.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } }, { "name": "limit", "in": "query", "description": "Pagination Limit.", "schema": { "description": "Pagination Limit.", "type": "number", "default": 20 } }, { "name": "offset", "in": "query", "description": "Pagination Offset.", "schema": { "description": "Pagination Offset.", "type": "number", "default": 0 } }, { "name": "orderBy", "in": "query", "description": "Order By Column Name.", "schema": { "description": "Order By Column Name.", "type": "string" } } ], "responses": { "200": { "description": "Returns all public finetunes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "id": { "type": "string", "format": "uuid", "x-auditable": true }, "model": { "type": "string", "x-auditable": true }, "modified_at": { "type": "string", "format": "date-time" }, "name": { "type": "string", "x-auditable": true }, "public": { "type": "boolean", "x-auditable": true } }, "required": [ "id", "model", "name", "public", "created_at", "modified_at" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers AI Finetune" ], "x-api-token-group": [ "Workers AI Write", "Workers AI Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai.finetunes.public", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/ai/finetunes/{finetune_id}": { "delete": { "operationId": "workers-ai-delete-finetune", "summary": "Delete a Finetune", "description": "Delete a finetune. Any in-flight requests referencing the lora will fail after the files are deleted.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } }, { "name": "finetune_id", "in": "path", "required": true, "schema": { "type": "string", "example": "bc451aef-f723-4b26-a6b2-901afd2e7a8a" } } ], "responses": { "200": { "description": "Finetune deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Finetune not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers AI Finetune" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai.finetunes", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true } }, "/accounts/{account_id}/ai/finetunes/{finetune_id}/finetune-assets": { "post": { "operationId": "workers-ai-upload-finetune-asset", "summary": "Upload a Finetune Asset", "description": "Uploads training data assets for a Workers AI fine-tuning job.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } }, { "name": "finetune_id", "in": "path", "required": true, "schema": { "type": "string", "example": "bc451aef-f723-4b26-a6b2-901afd2e7a8a" } } ], "requestBody": { "description": "Finetune asset file upload.", "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "description": "File to upload.", "type": "string", "format": "binary" }, "file_name": { "description": "Name of the file (adapter_config.json or adapter_model.safetensors).", "type": "string" } }, "required": [ "file_name", "file" ] } } } }, "responses": { "200": { "description": "Returns successfully if finetunes were uploaded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "400": { "description": "Finetune creation failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers AI Finetune" ], "x-api-token-group": [ "Workers AI Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai.finetunes.assets", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/ai/finetunes/{finetune_id}/finetune-assets/{file_name}": { "get": { "operationId": "workers-ai-download-finetune-asset", "summary": "Download a Finetune Asset", "description": "Returns a pre-signed R2 URL for downloading a finetune asset file.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } }, { "name": "finetune_id", "in": "path", "required": true, "schema": { "type": "string", "example": "bc451aef-f723-4b26-a6b2-901afd2e7a8a" } }, { "name": "file_name", "in": "path", "required": true, "schema": { "type": "string", "example": "adapter_model.safetensors" } } ], "responses": { "200": { "description": "Pre-signed download URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "file_name": { "type": "string" }, "file_url": { "type": "string" } }, "required": [ "file_name", "file_url" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Finetune or asset not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Finetune Asset" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai.finetunes.assets", "x-fern-sdk-method-name": "download", "x-forge-hidden": true } }, "/accounts/{account_id}/ai/models/schema": { "get": { "operationId": "workers-ai-get-model-schema", "summary": "Get Model Schema", "description": "Retrieves the input and output JSON schema definition for a Workers AI model.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } }, { "name": "model", "in": "query", "description": "Model Name", "required": true, "schema": { "description": "Model Name", "type": "string" } } ], "responses": { "200": { "description": "Model Schema", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "input": { "type": "object", "properties": { "additionalProperties": { "type": "boolean", "example": true }, "description": { "type": "string", "example": "JSON Schema definition for the model's input parameters" }, "type": { "type": "string", "example": "object" } }, "required": [ "type", "description", "additionalProperties" ] }, "output": { "type": "object", "properties": { "additionalProperties": { "type": "boolean", "example": true }, "description": { "type": "string", "example": "JSON Schema definition for the model's output format" }, "type": { "type": "string", "example": "object" } }, "required": [ "type", "description", "additionalProperties" ] } }, "required": [ "input", "output" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers AI" ], "x-api-token-group": [ "Workers AI Write", "Workers AI Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "ai", "x-fern-sdk-method-name": "getModelSchema" } }, "/accounts/{account_id}/ai/models/search": { "get": { "operationId": "workers-ai-search-model", "summary": "Model Search", "description": "Searches Workers AI models by name or description.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "task", "in": "query", "description": "Filter by Task Name.", "schema": { "description": "Filter by Task Name.", "type": "string", "example": "Text Generation", "default": "" } }, { "name": "author", "in": "query", "description": "Filter by Author.", "schema": { "description": "Filter by Author.", "type": "string", "default": "" } }, { "name": "source", "in": "query", "description": "Filter by Source Id.", "schema": { "description": "Filter by Source Id.", "type": "number" } }, { "name": "hide_experimental", "in": "query", "description": "Filter to hide experimental models.", "schema": { "description": "Filter to hide experimental models.", "type": "boolean", "default": false } }, { "name": "search", "in": "query", "description": "Search.", "schema": { "description": "Search.", "type": "string", "default": "" } }, { "name": "include_deprecated", "in": "query", "description": "If true, include models for up to three months after their deprecation date. Defaults to false.", "schema": { "description": "If true, include models for up to three months after their deprecation date. Defaults to false.", "type": "boolean", "default": false } }, { "name": "format", "in": "query", "description": "If set, return models in the requested marketplace format instead of the default response.", "schema": { "description": "If set, return models in the requested marketplace format instead of the default response.", "type": "string", "enum": [ "openrouter" ] } } ], "responses": { "200": { "description": "Returns a list of models. Default shape is the standard envelope; when `format` is supplied the marketplace-specific shape is returned instead.", "content": { "application/json": { "schema": { "anyOf": [ { "properties": { "errors": { "type": "array", "items": { "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "array", "items": { "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "result", "errors", "messages" ], "type": "object" }, { "description": "Marketplace-format response. See https://openrouter.ai/docs/guides/get-started/for-providers.", "properties": { "data": { "type": "array", "items": { "type": "object" } } }, "required": [ "data" ], "type": "object" } ] } } } }, "404": { "description": "Object not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers AI" ], "x-api-token-group": [ "Workers AI Write", "Workers AI Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai.models", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/ai/run": { "post": { "operationId": "workers-ai-post-run-generic", "summary": "Execute AI Model (Generic)", "description": "Execute an AI model by specifying the model name in the request body.\n\nThis endpoint provides a generic interface for running AI models where the model name is part of the request payload rather than the URL path. It supports all AI Gateway features including caching, custom headers, and request options.\n\nModel-specific inputs available in [Cloudflare Docs](https://developers.cloudflare.com/workers-ai/models/).", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "Model-specific input data. Format varies by model type.", "type": "object", "example": { "prompt": "Tell me a joke" } }, "model": { "description": "The AI model to execute (e.g., openai/gpt-5.5, anthropic/claude-opus-4.7)", "type": "string", "example": "openai/gpt-5.5" }, "options": { "type": "object", "properties": { "extraHeaders": { "description": "Additional headers to pass to the AI provider", "type": "object", "additionalProperties": { "type": "string" } }, "gateway": { "type": "object", "properties": { "cacheTtl": { "description": "Cache TTL in seconds", "type": "number", "example": 3600 }, "id": { "description": "AI Gateway ID for caching and logging", "type": "string", "example": "my-gateway" }, "skipCache": { "description": "Skip cache lookup for this request", "type": "boolean" } } } } } }, "required": [ "model", "input" ] } } } }, "responses": { "200": { "description": "Model response", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" } }, "messages": { "type": "array", "items": { "type": "object" } }, "result": { "description": "Model-specific output. Format varies by model type.", "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "result", "errors", "messages" ] } } } }, "400": { "description": "Bad request - missing required fields or invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers AI" ], "x-api-token-group": [ "Workers AI Write", "Workers AI Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai", "x-fern-sdk-method-name": "run", "x-forge-hidden": true } }, "/accounts/{account_id}/ai/run/{model_name}": { "post": { "operationId": "workers-ai-post-run-model", "summary": "Execute AI model", "description": "This endpoint provides users with the capability to run specific AI models on-demand.\n\nBy submitting the required input data, users can receive real-time predictions or results generated by the chosen AI\nmodel. The endpoint supports various AI model types, ensuring flexibility and adaptability for diverse use cases.\n\nModel specific inputs available in [Cloudflare Docs](https://developers.cloudflare.com/workers-ai/models/).", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } }, { "name": "model_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "properties": { "text": { "description": "The text that you want to classify", "type": "string", "minLength": 1 } }, "required": [ "text" ], "title": "Text Classification", "type": "object" }, { "properties": { "guidance": { "description": "Controls how closely the generated image should adhere to the prompt; higher values make the image more aligned with the prompt", "type": "number", "default": 7.5 }, "height": { "description": "The height of the generated image in pixels", "type": "integer", "maximum": 2048, "minimum": 256 }, "image": { "description": "For use with img2img tasks. An array of integers that represent the image data constrained to 8-bit unsigned integer values", "type": "array", "items": { "description": "A value between 0 and 255", "type": "number" } }, "image_b64": { "description": "For use with img2img tasks. A base64-encoded string of the input image", "type": "string" }, "mask": { "description": "An array representing An array of integers that represent mask image data for inpainting constrained to 8-bit unsigned integer values", "type": "array", "items": { "description": "A value between 0 and 255", "type": "number" } }, "negative_prompt": { "description": "Text describing elements to avoid in the generated image", "type": "string" }, "num_steps": { "description": "The number of diffusion steps; higher values can improve quality but take longer", "type": "integer", "default": 20, "maximum": 20 }, "prompt": { "description": "A text description of the image you want to generate", "type": "string", "minLength": 1 }, "seed": { "description": "Random seed for reproducibility of the image generation", "type": "integer" }, "strength": { "description": "A value between 0 and 1 indicating how strongly to apply the transformation during img2img tasks; lower values make the output closer to the input image", "type": "number", "default": 1 }, "width": { "description": "The width of the generated image in pixels", "type": "integer", "maximum": 2048, "minimum": 256 } }, "required": [ "prompt" ], "title": "Text To Image", "type": "object" }, { "properties": { "lang": { "description": "The speech language (e.g., 'en' for English, 'fr' for French). Defaults to 'en' if not specified", "type": "string", "default": "en" }, "prompt": { "description": "A text description of the audio you want to generate", "type": "string", "minLength": 1 } }, "required": [ "prompt" ], "title": "Text To Speech", "type": "object" }, { "properties": { "text": { "oneOf": [ { "description": "The text to embed", "minLength": 1, "type": "string" }, { "description": "Batch of text values to embed", "items": { "description": "The text to embed", "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" } ] } }, "required": [ "text" ], "title": "Text Embeddings", "type": "object" }, { "oneOf": [ { "format": "binary", "type": "string" }, { "properties": { "audio": { "description": "An array of integers that represent the audio data constrained to 8-bit unsigned integer values", "type": "array", "items": { "description": "A value between 0 and 255", "type": "number" } }, "source_lang": { "description": "The language of the recorded audio", "type": "string" }, "target_lang": { "description": "The language to translate the transcription into. Currently only English is supported.", "type": "string" } }, "required": [ "audio" ], "type": "object" } ], "title": "Automatic Speech Recognition", "type": "object" }, { "oneOf": [ { "description": "The image to classify", "format": "binary", "type": "string" }, { "properties": { "image": { "description": "An array of integers that represent the image data constrained to 8-bit unsigned integer values", "type": "array", "items": { "description": "A value between 0 and 255 (unsigned 8bit)", "type": "number" } } }, "required": [ "image" ], "type": "object" } ], "title": "Image Classification", "type": "object" }, { "oneOf": [ { "description": "The image to use for detection", "format": "binary", "type": "string" }, { "properties": { "image": { "description": "An array of integers that represent the image data constrained to 8-bit unsigned integer values", "type": "array", "items": { "description": "A value between 0 and 255 (unsigned 8bit)", "type": "number" } } }, "type": "object" } ], "title": "Object Detection", "type": "object" }, { "oneOf": [ { "properties": { "frequency_penalty": { "description": "Decreases the likelihood of the model repeating the same lines verbatim.", "type": "number", "maximum": 2, "minimum": -2 }, "lora": { "description": "Name of the LoRA (Low-Rank Adaptation) model to fine-tune the base model.", "type": "string" }, "max_tokens": { "description": "The maximum number of tokens to generate in the response.", "type": "integer", "default": 256 }, "presence_penalty": { "description": "Increases the likelihood of the model introducing new topics.", "type": "number", "maximum": 2, "minimum": -2 }, "prompt": { "description": "The input text prompt for the model to generate a response.", "type": "string", "minLength": 1 }, "raw": { "description": "If true, a chat template is not applied and you must adhere to the specific model's expected formatting.", "type": "boolean", "default": false }, "repetition_penalty": { "description": "Penalty for repeated tokens; higher values discourage repetition.", "type": "number", "maximum": 2, "minimum": 0 }, "response_format": { "type": "object", "properties": { "json_schema": {}, "type": { "type": "string", "enum": [ "json_object", "json_schema" ] } }, "title": "JSON Mode" }, "seed": { "description": "Random seed for reproducibility of the generation.", "type": "integer", "maximum": 9999999999, "minimum": 1 }, "stream": { "description": "If true, the response will be streamed back incrementally using SSE, Server Sent Events.", "type": "boolean", "default": false }, "temperature": { "description": "Controls the randomness of the output; higher values produce more random results.", "type": "number", "default": 0.6, "maximum": 5, "minimum": 0 }, "top_k": { "description": "Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises.", "type": "integer", "maximum": 50, "minimum": 1 }, "top_p": { "description": "Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses.", "type": "number", "maximum": 1, "minimum": 0.001 } }, "required": [ "prompt" ], "title": "Prompt" }, { "properties": { "frequency_penalty": { "description": "Decreases the likelihood of the model repeating the same lines verbatim.", "type": "number", "maximum": 2, "minimum": -2 }, "functions": { "type": "array", "items": { "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "code" ], "type": "object" } }, "max_tokens": { "description": "The maximum number of tokens to generate in the response.", "type": "integer", "default": 256 }, "messages": { "description": "An array of message objects representing the conversation history.", "type": "array", "items": { "properties": { "content": { "oneOf": [ { "description": "The content of the message as a string.", "type": "string" }, { "description": "Array of text content parts.", "items": { "properties": { "text": { "description": "Text content", "type": "string" }, "type": { "description": "Type of the content (text)", "type": "string" } }, "type": "object" }, "type": "array" } ] }, "role": { "description": "The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool').", "type": "string" } }, "required": [ "role", "content" ], "type": "object" } }, "presence_penalty": { "description": "Increases the likelihood of the model introducing new topics.", "type": "number", "maximum": 2, "minimum": -2 }, "raw": { "description": "If true, a chat template is not applied and you must adhere to the specific model's expected formatting.", "type": "boolean", "default": false }, "repetition_penalty": { "description": "Penalty for repeated tokens; higher values discourage repetition.", "type": "number", "maximum": 2, "minimum": 0 }, "response_format": { "type": "object", "properties": { "json_schema": {}, "type": { "type": "string", "enum": [ "json_object", "json_schema" ] } }, "title": "JSON Mode" }, "seed": { "description": "Random seed for reproducibility of the generation.", "type": "integer", "maximum": 9999999999, "minimum": 1 }, "stream": { "description": "If true, the response will be streamed back incrementally using SSE, Server Sent Events.", "type": "boolean", "default": false }, "temperature": { "description": "Controls the randomness of the output; higher values produce more random results.", "type": "number", "default": 0.6, "maximum": 5, "minimum": 0 }, "tools": { "description": "A list of tools available for the assistant to use.", "type": "array", "items": { "oneOf": [ { "properties": { "description": { "description": "A brief description of what the tool does.", "type": "string" }, "name": { "description": "The name of the tool. More descriptive the better.", "type": "string" }, "parameters": { "description": "Schema defining the parameters accepted by the tool.", "required": [ "type", "properties" ], "properties": { "properties": { "description": "Definitions of each parameter.", "type": "object", "additionalProperties": { "properties": { "description": { "description": "A description of the expected parameter.", "type": "string" }, "type": { "description": "The data type of the parameter.", "type": "string" } }, "required": [ "type", "description" ], "type": "object" } }, "required": { "description": "List of required parameter names.", "type": "array", "items": { "type": "string" } }, "type": { "description": "The type of the parameters object (usually 'object').", "type": "string" } }, "type": "object" } }, "required": [ "name", "description", "parameters" ] }, { "properties": { "function": { "description": "Details of the function tool.", "type": "object", "properties": { "description": { "description": "A brief description of what the function does.", "type": "string" }, "name": { "description": "The name of the function.", "type": "string" }, "parameters": { "description": "Schema defining the parameters accepted by the function.", "required": [ "type", "properties" ], "properties": { "properties": { "description": "Definitions of each parameter.", "type": "object", "additionalProperties": { "properties": { "description": { "description": "A description of the expected parameter.", "type": "string" }, "type": { "description": "The data type of the parameter.", "type": "string" } }, "required": [ "type", "description" ], "type": "object" } }, "required": { "description": "List of required parameter names.", "type": "array", "items": { "type": "string" } }, "type": { "description": "The type of the parameters object (usually 'object').", "type": "string" } }, "type": "object" } }, "required": [ "name", "description", "parameters" ] }, "type": { "description": "Specifies the type of tool (e.g., 'function').", "type": "string" } }, "required": [ "type", "function" ] } ], "type": "object" } }, "top_k": { "description": "Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises.", "type": "integer", "maximum": 50, "minimum": 1 }, "top_p": { "description": "Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses.", "type": "number", "maximum": 1, "minimum": 0.001 } }, "required": [ "messages" ], "title": "Messages" } ], "title": "Text Generation", "type": "object" }, { "properties": { "source_lang": { "description": "The language code of the source text (e.g., 'en' for English). Defaults to 'en' if not specified", "type": "string", "default": "en" }, "target_lang": { "description": "The language code to translate the text into (e.g., 'es' for Spanish)", "type": "string" }, "text": { "description": "The text to be translated", "type": "string", "minLength": 1 } }, "required": [ "text", "target_lang" ], "title": "Translation", "type": "object" }, { "properties": { "input_text": { "description": "The text that you want the model to summarize", "type": "string", "minLength": 1 }, "max_length": { "description": "The maximum length of the generated summary in tokens", "type": "integer", "default": 1024 } }, "required": [ "input_text" ], "title": "Summarization", "type": "object" }, { "oneOf": [ { "description": "Binary string representing the image contents.", "format": "binary", "type": "string" }, { "properties": { "frequency_penalty": { "description": "Decreases the likelihood of the model repeating the same lines verbatim.", "type": "number" }, "image": { "oneOf": [ { "description": "An array of integers that represent the image data constrained to 8-bit unsigned integer values", "items": { "description": "A value between 0 and 255", "type": "number" }, "type": "array" }, { "description": "Binary string representing the image contents.", "format": "binary", "type": "string" } ] }, "max_tokens": { "description": "The maximum number of tokens to generate in the response.", "type": "integer", "default": 512 }, "presence_penalty": { "description": "Increases the likelihood of the model introducing new topics.", "type": "number" }, "prompt": { "description": "The input text prompt for the model to generate a response.", "type": "string" }, "raw": { "description": "If true, a chat template is not applied and you must adhere to the specific model's expected formatting.", "type": "boolean", "default": false }, "repetition_penalty": { "description": "Penalty for repeated tokens; higher values discourage repetition.", "type": "number" }, "seed": { "description": "Random seed for reproducibility of the generation.", "type": "number" }, "temperature": { "description": "Controls the randomness of the output; higher values produce more random results.", "type": "number" }, "top_k": { "description": "Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises.", "type": "number" }, "top_p": { "description": "Controls the creativity of the AI's responses by adjusting how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses.", "type": "number" } }, "required": [ "image" ], "type": "object" } ], "title": "Image To Text", "type": "object" }, { "oneOf": [ { "properties": { "frequency_penalty": { "description": "Decreases the likelihood of the model repeating the same lines verbatim.", "type": "number" }, "ignore_eos": { "description": "Whether to ignore the EOS token and continue generating tokens after the EOS token is generated.", "type": "boolean" }, "image": { "description": "Image in base64 encoded format.", "type": "string" }, "max_tokens": { "description": "The maximum number of tokens to generate in the response.", "type": "integer", "default": 512 }, "presence_penalty": { "description": "Increases the likelihood of the model introducing new topics.", "type": "number" }, "prompt": { "description": "The input text prompt for the model to generate a response.", "type": "string", "minLength": 1 }, "repetition_penalty": { "description": "Penalty for repeated tokens; higher values discourage repetition.", "type": "number" }, "seed": { "description": "Random seed for reproducibility of the generation.", "type": "number" }, "temperature": { "description": "Controls the randomness of the output; higher values produce more random results.", "type": "number" }, "top_k": { "description": "Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises.", "type": "number" }, "top_p": { "description": "Controls the creativity of the AI's responses by adjusting how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses.", "type": "number" } }, "required": [ "prompt", "image" ], "type": "object" }, { "properties": { "frequency_penalty": { "description": "Decreases the likelihood of the model repeating the same lines verbatim.", "type": "number" }, "ignore_eos": { "description": "Whether to ignore the EOS token and continue generating tokens after the EOS token is generated.", "type": "boolean" }, "image": { "description": "Image in base64 encoded format.", "type": "string" }, "max_tokens": { "description": "The maximum number of tokens to generate in the response.", "type": "integer", "default": 512 }, "messages": { "description": "An array of message objects representing the conversation history.", "type": "array", "items": { "properties": { "content": { "anyOf": [ { "description": "The content of the message as a string.", "type": "string" }, { "description": "Array of content parts (text, image_url, etc.).", "items": { "properties": { "image_url": { "description": "Image URL object (when type is 'image_url').", "type": "object", "properties": { "url": { "description": "Image URI with data (e.g. data:image/jpeg;base64,/9j/...).", "type": "string" } }, "required": [ "url" ] }, "text": { "description": "Text content (when type is 'text').", "type": "string" }, "type": { "description": "Type of the content part (e.g. 'text', 'image_url').", "type": "string" } }, "required": [ "type" ], "type": "object" }, "type": "array" } ] }, "role": { "description": "The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool').", "type": "string" } }, "required": [ "role", "content" ], "type": "object" } }, "presence_penalty": { "description": "Increases the likelihood of the model introducing new topics.", "type": "number" }, "repetition_penalty": { "description": "Penalty for repeated tokens; higher values discourage repetition.", "type": "number" }, "seed": { "description": "Random seed for reproducibility of the generation.", "type": "number" }, "temperature": { "description": "Controls the randomness of the output; higher values produce more random results.", "type": "number" }, "top_k": { "description": "Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises.", "type": "number" }, "top_p": { "description": "Controls the creativity of the AI's responses by adjusting how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses.", "type": "number" } }, "required": [ "messages", "image" ], "type": "object" } ], "title": "Image Text To Text", "type": "object" }, { "properties": { "image": { "description": "Image in base64 encoded format.", "type": "string", "minLength": 1 }, "text": { "type": "array", "items": { "minLength": 1, "type": "string" } } }, "title": "Multimodal Embeddings", "type": "object" } ] } } } }, "responses": { "200": { "description": "Model response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "oneOf": [ { "description": "An array of classification results for the input text", "items": { "properties": { "label": { "description": "The classification label assigned to the text (e.g., 'POSITIVE' or 'NEGATIVE')", "type": "string" }, "score": { "description": "Confidence score indicating the likelihood that the text belongs to the specified label", "type": "number" } }, "type": "object" }, "title": "Text Classification", "type": "array" }, { "description": "The generated image in PNG format", "format": "binary", "title": "Text To Image", "type": "string" }, { "oneOf": [ { "properties": { "audio": { "description": "The generated audio in MP3 format, base64-encoded", "type": "string" } }, "type": "object" }, { "description": "The generated audio in MP3 format", "format": "binary", "type": "string" } ], "title": "Text To Speech", "type": "object" }, { "properties": { "data": { "description": "Embeddings of the requested text values", "type": "array", "items": { "description": "Floating point embedding representation shaped by the embedding model", "items": { "type": "number" }, "type": "array" } }, "shape": { "type": "array", "items": { "type": "number" } } }, "title": "Text Embeddings", "type": "object" }, { "properties": { "text": { "description": "The transcription", "type": "string" }, "vtt": { "type": "string" }, "word_count": { "type": "number" }, "words": { "type": "array", "items": { "properties": { "end": { "description": "The ending second when the word completes", "type": "number" }, "start": { "description": "The second this word begins in the recording", "type": "number" }, "word": { "type": "string" } }, "type": "object" } } }, "required": [ "text" ], "title": "Automatic Speech Recognition", "type": "object" }, { "items": { "properties": { "label": { "description": "The predicted category or class for the input image based on analysis", "type": "string" }, "score": { "description": "A confidence value, between 0 and 1, indicating how certain the model is about the predicted label", "type": "number" } }, "type": "object" }, "title": "Image Classification", "type": "array" }, { "description": "An array of detected objects within the input image", "items": { "properties": { "box": { "description": "Coordinates defining the bounding box around the detected object", "type": "object", "properties": { "xmax": { "description": "The x-coordinate of the bottom-right corner of the bounding box", "type": "number" }, "xmin": { "description": "The x-coordinate of the top-left corner of the bounding box", "type": "number" }, "ymax": { "description": "The y-coordinate of the bottom-right corner of the bounding box", "type": "number" }, "ymin": { "description": "The y-coordinate of the top-left corner of the bounding box", "type": "number" } } }, "label": { "description": "The class label or name of the detected object", "type": "string" }, "score": { "description": "Confidence score indicating the likelihood that the detection is correct", "type": "number" } }, "type": "object" }, "title": "Object Detection", "type": "array" }, { "oneOf": [ { "properties": { "response": { "description": "The generated text response from the model", "type": "string" }, "tool_calls": { "description": "An array of tool calls requests made during the response generation", "type": "array", "items": { "properties": { "arguments": { "description": "The arguments passed to be passed to the tool call request", "type": "object" }, "name": { "description": "The name of the tool to be called", "type": "string" } }, "type": "object" } }, "usage": { "description": "Usage statistics for the inference request", "type": "object", "properties": { "completion_tokens": { "description": "Total number of tokens in output", "type": "number", "default": 0 }, "prompt_tokens": { "description": "Total number of tokens in input", "type": "number", "default": 0 }, "total_tokens": { "description": "Total number of input and output tokens", "type": "number", "default": 0 } } } }, "required": [ "response" ], "type": "object" }, { "format": "binary", "type": "string" } ], "title": "Text Generation", "type": "object" }, { "properties": { "translated_text": { "description": "The translated text in the target language", "type": "string" } }, "title": "Translation", "type": "object" }, { "properties": { "summary": { "description": "The summarized version of the input text", "type": "string" } }, "title": "Summarization", "type": "object" }, { "properties": { "description": { "type": "string" } }, "title": "Image To Text", "type": "object" }, { "properties": { "description": { "type": "string" } }, "title": "Image Text To Text", "type": "object" }, { "properties": { "data": { "type": "array", "items": { "items": { "type": "number" }, "type": "array" } }, "shape": { "type": "array", "items": { "type": "number" } } }, "title": "Multimodal Embeddings", "type": "object" } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers AI" ], "x-api-token-group": [ "Workers AI Write", "Workers AI Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "ai", "x-fern-sdk-method-name": "runModel" } }, "/accounts/{account_id}/ai/tasks/search": { "get": { "operationId": "workers-ai-search-task", "summary": "Task Search", "description": "Searches Workers AI models by task type (e.g., text-generation, embeddings).", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } } ], "responses": { "200": { "description": "Returns a list of tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "array", "items": { "type": "object" } }, "success": { "type": "boolean", "x-auditable": true } }, "required": [ "success", "result", "errors", "messages" ] } } } }, "404": { "description": "Object not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers AI" ], "x-api-token-group": [ "Workers AI Write", "Workers AI Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai.tasks", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/ai/tomarkdown": { "post": { "operationId": "workers-ai-post-to-markdown", "summary": "Convert Files into Markdown", "description": "Converts uploaded files into Markdown format using Workers AI.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "format": "binary", "type": "string" } } }, "required": [ "files" ] } } } }, "responses": { "200": { "description": "Model Schema", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "data": { "type": "string", "x-auditable": true }, "format": { "type": "string", "x-auditable": true }, "mimeType": { "type": "string", "x-auditable": true }, "name": { "type": "string", "x-auditable": true }, "tokens": { "type": "string", "x-auditable": true } }, "required": [ "name", "mimeType", "format", "tokens", "data" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers AI" ], "x-api-token-group": [ "Workers AI Write", "Workers AI Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "ai", "x-fern-sdk-method-name": "toMarkdown" } }, "/accounts/{account_id}/ai/tomarkdown/supported": { "get": { "operationId": "workers-ai-get-to-markdown-supported", "summary": "Get all converted formats supported", "description": "Lists all file formats supported for conversion to Markdown.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "extension": { "type": "string", "x-auditable": true }, "mimeType": { "type": "string", "x-auditable": true } }, "required": [ "extension", "mimeType" ], "type": "object" } }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers AI" ], "x-api-token-group": [ "Workers AI Write", "Workers AI Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.ai" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "ai", "x-fern-sdk-method-name": "listMarkdownSupportedFormats" } }, "/accounts/{account_id}/alerting/v3/available_alerts": { "get": { "operationId": "notification-alert-types-get-alert-types", "summary": "Get Alert Types", "description": "Gets a list of all alert types for which an account is eligible.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } } ], "responses": { "200": { "description": "Get Alert Types response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_alerts-response_collection" } } } }, "4XX": { "description": "Get Alert Types response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification Alert Types" ], "x-api-token-group": [ "Zero Trust: PII Read", "Notifications Write", "Notifications Read", "Account Settings Write", "Account Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.available-alerts", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/alerting/v3/destinations/eligible": { "get": { "operationId": "notification-mechanism-eligibility-get-delivery-mechanism-eligibility", "summary": "Get delivery mechanism eligibility", "description": "Get a list of all delivery mechanism types for which an account is eligible.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } } ], "responses": { "200": { "description": "Get delivery mechanism eligibility response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_schemas-response_collection" } } } }, "4XX": { "description": "Get delivery mechanism eligibility response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification Mechanism Eligibility" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.destinations.eligible", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/alerting/v3/destinations/pagerduty": { "delete": { "operationId": "notification-destinations-with-pager-duty-delete-pager-duty-services", "summary": "Delete PagerDuty Services", "description": "Deletes all the PagerDuty Services connected to the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } } ], "responses": { "200": { "description": "Delete PagerDuty Services response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_api-response-common-2" } } } }, "4XX": { "description": "Delete PagerDuty Services response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification destinations with PagerDuty" ], "x-api-token-group": [ "Notifications Write", "Account Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.destinations.pagerduty", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes all PagerDuty services connected to the account." }, "get": { "operationId": "notification-destinations-with-pager-duty-list-pager-duty-services", "summary": "List PagerDuty services", "description": "Get a list of all configured PagerDuty services.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } } ], "responses": { "200": { "description": "List PagerDuty services response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_components-schemas-response_collection" } } } }, "4XX": { "description": "List PagerDuty services response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification destinations with PagerDuty" ], "x-api-token-group": [ "Zero Trust: PII Read", "Notifications Write", "Notifications Read", "Account Settings Write", "Account Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.destinations.pagerduty", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/alerting/v3/destinations/pagerduty/connect": { "post": { "operationId": "notification-destinations-with-pager-duty-connect-pager-duty", "summary": "Create PagerDuty integration token", "description": "Creates a new token for integrating with PagerDuty.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } } ], "responses": { "201": { "description": "Token for PagerDuty integration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_sensitive_id_response" } } } }, "4XX": { "description": "Create a token for PagerDuty integration failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_id_response" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification destinations with PagerDuty" ], "x-api-token-group": [ "Notifications Write", "Account Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.destinations.pagerduty", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/alerting/v3/destinations/pagerduty/connect/{token_id}": { "get": { "operationId": "notification-destinations-with-pager-duty-connect-pager-duty-token", "summary": "Connect PagerDuty", "description": "Links PagerDuty with the account using the integration token.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } }, { "name": "token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_integration-token" } } ], "responses": { "200": { "description": "Create a Notification policy response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_id_response" } } } }, "4XX": { "description": "Create a Notification policy response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_id_response" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification destinations with PagerDuty" ], "x-api-token-group": [ "Notifications Write", "Account Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.destinations.pagerduty", "x-fern-sdk-method-name": "link", "x-forge-hidden": true } }, "/accounts/{account_id}/alerting/v3/destinations/webhooks": { "get": { "operationId": "notification-webhooks-list-webhooks", "summary": "List webhooks", "description": "Gets a list of all configured webhook destinations.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } } ], "responses": { "200": { "description": "List webhooks response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_webhooks_components-schemas-response_collection" } } } }, "4XX": { "description": "List webhooks response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_webhooks_components-schemas-response_collection" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification webhooks" ], "x-api-token-group": [ "Zero Trust: PII Read", "Notifications Write", "Notifications Read", "Account Settings Write", "Account Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.destinations.webhooks", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "notification-webhooks-create-a-webhook", "summary": "Create a webhook", "description": "Creates a new webhook destination.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "$ref": "#/components/schemas/aaa_components-schemas-name" }, "secret": { "$ref": "#/components/schemas/aaa_secret" }, "url": { "$ref": "#/components/schemas/aaa_url" } }, "required": [ "name", "url" ] } } } }, "responses": { "201": { "description": "Create a webhook response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_id_response" } } } }, "4XX": { "description": "Create a webhook response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_id_response" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification webhooks" ], "x-api-token-group": [ "Notifications Write", "Account Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.destinations.webhooks", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/alerting/v3/destinations/webhooks/{webhook_id}": { "delete": { "operationId": "notification-webhooks-delete-a-webhook", "summary": "Delete a webhook", "description": "Delete a configured webhook destination.", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_webhook-id" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } } ], "responses": { "200": { "description": "Delete a webhook response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_api-response-common-2" } } } }, "4XX": { "description": "Delete a webhook response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification webhooks" ], "x-api-token-group": [ "Notifications Write", "Account Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.destinations.webhooks", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes the webhook destination." }, "get": { "operationId": "notification-webhooks-get-a-webhook", "summary": "Get a webhook", "description": "Get details for a single webhooks destination.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } }, { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_webhook-id" } } ], "responses": { "200": { "description": "Get a webhook response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_schemas-single_response" } } } }, "4XX": { "description": "Get a webhook response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_schemas-single_response" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification webhooks" ], "x-api-token-group": [ "Zero Trust: PII Read", "Notifications Write", "Notifications Read", "Account Settings Write", "Account Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.destinations.webhooks", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "notification-webhooks-update-a-webhook", "summary": "Update a webhook", "description": "Update a webhook destination.", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_webhook-id" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "$ref": "#/components/schemas/aaa_components-schemas-name" }, "secret": { "$ref": "#/components/schemas/aaa_secret" }, "url": { "$ref": "#/components/schemas/aaa_url" } }, "required": [ "name", "url" ] } } } }, "responses": { "200": { "description": "Update a webhook response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_id_response" } } } }, "4XX": { "description": "Update a webhook response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_id_response" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification webhooks" ], "x-api-token-group": [ "Notifications Write", "Account Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.destinations.webhooks", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/alerting/v3/history": { "get": { "operationId": "notification-history-list-history", "summary": "List History", "description": "Gets a list of history records for notifications sent to an account. The records are displayed for last `x` number of days based on the zone plan (free = 30, pro = 30, biz = 30, ent = 90).", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } }, { "name": "per_page", "in": "query", "schema": { "$ref": "#/components/schemas/aaa_per_page" } }, { "name": "before", "in": "query", "schema": { "$ref": "#/components/schemas/aaa_before" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "since", "in": "query", "schema": { "description": "Limit the returned results to history records newer than the specified date. This must be a timestamp that conforms to RFC3339.", "type": "string", "format": "date-time", "example": "2022-05-19T20:29:58.679897Z" } } ], "responses": { "200": { "description": "List History response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_history_components-schemas-response_collection" } } } }, "4XX": { "description": "List History response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_history_components-schemas-response_collection" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification History" ], "x-api-token-group": [ "Zero Trust: PII Read", "Notifications Write", "Notifications Read", "Account Settings Write", "Account Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.history", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/alerting/v3/policies": { "get": { "operationId": "notification-policies-list-notification-policies", "summary": "List Notification policies", "description": "Get a list of all Notification policies.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } } ], "responses": { "200": { "description": "List Notification policies response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_policies_components-schemas-response_collection" } } } }, "4XX": { "description": "List Notification policies response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification policies" ], "x-api-token-group": [ "Zero Trust: PII Read", "Notifications Write", "Notifications Read", "Account Settings Write", "Account Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.policies", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "notification-policies-create-a-notification-policy", "summary": "Create a Notification policy", "description": "Creates a new Notification policy.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "alert_interval": { "$ref": "#/components/schemas/aaa_alert_interval" }, "alert_type": { "$ref": "#/components/schemas/aaa_alert_type" }, "description": { "$ref": "#/components/schemas/aaa_schemas-description" }, "enabled": { "$ref": "#/components/schemas/aaa_enabled" }, "filters": { "$ref": "#/components/schemas/aaa_filters" }, "mechanisms": { "$ref": "#/components/schemas/aaa_mechanisms" }, "name": { "$ref": "#/components/schemas/aaa_schemas-name" } }, "required": [ "name", "alert_type", "enabled", "mechanisms" ] } } } }, "responses": { "200": { "description": "Create a Notification policy response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_id_response" } } } }, "4XX": { "description": "Create a Notification policy response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_id_response" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification policies" ], "x-api-token-group": [ "Notifications Write", "Account Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.policies", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/alerting/v3/policies/{policy_id}": { "delete": { "operationId": "notification-policies-delete-a-notification-policy", "summary": "Delete a Notification policy", "description": "Delete a Notification policy.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_policy-id" } } ], "responses": { "200": { "description": "Delete a Notification policy response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_api-response-collection" } } } }, "4XX": { "description": "Delete a Notification policy response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-collection" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification policies" ], "x-api-token-group": [ "Notifications Write", "Account Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.policies", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes the notification policy." }, "get": { "operationId": "notification-policies-get-a-notification-policy", "summary": "Get a Notification policy", "description": "Get details for a single policy.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_policy-id" } } ], "responses": { "200": { "description": "Get a Notification policy response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_single_response" } } } }, "4XX": { "description": "Get a Notification policy response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_single_response" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification policies" ], "x-api-token-group": [ "Zero Trust: PII Read", "Notifications Write", "Notifications Read", "Account Settings Write", "Account Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.policies", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "notification-policies-update-a-notification-policy", "summary": "Update a Notification policy", "description": "Update a Notification policy.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_policy-id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "alert_interval": { "$ref": "#/components/schemas/aaa_alert_interval" }, "alert_type": { "$ref": "#/components/schemas/aaa_alert_type" }, "description": { "$ref": "#/components/schemas/aaa_schemas-description" }, "enabled": { "$ref": "#/components/schemas/aaa_enabled" }, "filters": { "$ref": "#/components/schemas/aaa_filters" }, "mechanisms": { "$ref": "#/components/schemas/aaa_mechanisms" }, "name": { "$ref": "#/components/schemas/aaa_schemas-name" } } } } } }, "responses": { "200": { "description": "Update a Notification policy response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_id_response" } } } }, "4XX": { "description": "Update a Notification policy response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_id_response" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification policies" ], "x-api-token-group": [ "Notifications Write", "Account Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.policies", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/alerting/v3/policies/{policy_id}/email/unsubscribe": { "get": { "operationId": "notification-policies-show-email-unsubscribe-details", "summary": "Show email unsubscribe details", "description": "Shows details for unsubscribing an email address from a notification policy.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_policy-id" } }, { "name": "email", "in": "query", "required": true, "schema": { "type": "string", "format": "email" } }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Show email unsubscribe details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_unsubscribe_email_single_response" } }, "text/html": { "schema": { "type": "string" } } } }, "4XX": { "description": "Show email unsubscribe details response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } } } } }, "security": [], "tags": [ "Notification policies" ], "x-api-token-group": [ "Zero Trust: PII Read", "Notifications Write", "Notifications Read", "Account Settings Write", "Account Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.policies.email", "x-fern-sdk-method-name": "details", "x-forge-hidden": true }, "post": { "operationId": "notification-policies-unsubscribe-email-from-notification-policy", "summary": "Unsubscribe email from a Notification policy", "description": "Unsubscribes an email address from a notification policy.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_policy-id" } }, { "name": "email", "in": "query", "required": true, "schema": { "type": "string", "format": "email" } }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Unsubscribe email from Notification policy response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_unsubscribe_email_post_single_response" } }, "text/html": { "schema": { "type": "string" } } } }, "4XX": { "description": "Unsubscribe email from Notification policy response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } } } } }, "security": [], "tags": [ "Notification policies" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.policies.email", "x-fern-sdk-method-name": "unsubscribe", "x-forge-hidden": true } }, "/accounts/{account_id}/alerting/v3/policies/{policy_id}/test": { "post": { "operationId": "notification-policies-test-a-notification-policy", "summary": "Test a Notification policy", "description": "Send a test notification for a policy to verify delivery mechanisms are working as expected.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_policy-id" } } ], "requestBody": { "description": "Optional configuration for the test notification. When omitted, a default INFO-severity test alert is sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "severity": { "description": "Severity level for the test alert. Defaults to INFO (1) if omitted.", "type": "integer", "example": 1, "enum": [ 0, 1, 2, 3, 4 ] }, "source": { "description": "Source identifier for the test alert.", "type": "string" }, "state_correlation_id": { "description": "Correlation ID for stateful test alerts. Required when state_event is set.", "type": "string" }, "state_event": { "description": "State event type for stateful test alerts. Use with state_correlation_id.", "type": "integer", "enum": [ 0, 1, 2 ] } } } } } }, "responses": { "200": { "description": "Test a Notification policy response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_api-response-common-2" } } } }, "4XX": { "description": "Test a Notification policy response failure. Common causes include an invalid or non-existent policy ID, or a delivery mechanism that is unreachable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification policies" ], "x-api-token-group": [ "Notifications Write", "Account Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.policies", "x-fern-sdk-method-name": "test", "x-forge-hidden": true } }, "/accounts/{account_id}/alerting/v3/silences": { "get": { "operationId": "notification-silences-list-silences", "summary": "List Silences", "description": "Gets a list of silences for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } } ], "responses": { "200": { "description": "List Silences response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_silences_components-schemas-response_collection" } } } }, "4XX": { "description": "List Silences response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_silences_components-schemas-response_collection" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification Silences" ], "x-api-token-group": [ "Zero Trust: PII Read", "Notifications Write", "Notifications Read", "Account Settings Write", "Account Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.silences", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "notification-silences-create-silences", "summary": "Create Silences", "description": "Creates a new silence for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/aaa_silence_create_request" } } } } }, "responses": { "200": { "description": "Create Silences response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_api-response-common-2" } } } }, "4XX": { "description": "Create Silences response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_silences_components-schemas-response_collection" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification Silences" ], "x-api-token-group": [ "Notifications Write", "Account Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.silences", "x-fern-sdk-method-name": "create", "x-forge-hidden": true }, "put": { "operationId": "notification-silences-update-silences", "summary": "Update Silences", "description": "Updates existing silences for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/aaa_silence_update_request" } } } } }, "responses": { "200": { "description": "Update Silences response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_silences_components-schemas-response_collection" } } } }, "4XX": { "description": "Update Silences response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_silences_components-schemas-response_collection" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification Silences" ], "x-api-token-group": [ "Notifications Write", "Account Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.silences", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/alerting/v3/silences/{silence_id}": { "delete": { "operationId": "notification-silences-delete-silences", "summary": "Delete Silence", "description": "Deletes an existing silence for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } }, { "name": "silence_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_silence-id" } } ], "responses": { "200": { "description": "Delete Silence response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_api-response-common-2" } } } }, "4XX": { "description": "Delete Silence response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_silence_components-schemas-response_collection" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification Silences" ], "x-api-token-group": [ "Notifications Write", "Account Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.silences", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes the notification silence." }, "get": { "operationId": "notification-silences-get-silence", "summary": "Get Silence", "description": "Gets a specific silence for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_account-id" } }, { "name": "silence_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_silence-id" } } ], "responses": { "200": { "description": "Get Silence response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_silence_components-schemas-response_collection" } } } }, "4XX": { "description": "Get Silence response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_silence_components-schemas-response_collection" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Notification Silences" ], "x-api-token-group": [ "Zero Trust: PII Read", "Notifications Write", "Notifications Read", "Account Settings Write", "Account Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerting.silences", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/analytics/query/data-security/content-findings/top-n": { "post": { "operationId": "data-security-content-findings-top-n", "summary": "Top integrations by content findings", "description": "Returns the top N integrations ranked by total content findings.\n", "parameters": [ { "$ref": "#/components/parameters/art_account_id" } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "top_integrations": { "summary": "Top 10 integrations by content findings", "value": { "filters": [], "from": "2024-11-01T00:00:00Z", "n": 10, "to": "2024-11-08T00:00:00Z" } } }, "schema": { "$ref": "#/components/schemas/art_DataSecurityContentFindingsTopNQuery" } } } }, "responses": { "200": { "description": "Top integrations result.", "content": { "application/json": { "examples": { "success": { "summary": "Successful top integrations result", "value": { "errors": [], "messages": [ { "code": 1000, "message": "API in beta: expect breaking changes." } ], "result": [ { "integrationId": "123e4567-e89b-12d3-a456-426614174000", "integrationName": "Google Workspace", "total": 42 }, { "integrationId": "223e4567-e89b-12d3-a456-426614174001", "integrationName": "Microsoft 365", "total": 17 } ], "success": true } } }, "schema": { "$ref": "#/components/schemas/art_TopNResponse" } } } }, "400": { "$ref": "#/components/responses/art_BadRequest" }, "401": { "$ref": "#/components/responses/art_Unauthorized" }, "403": { "$ref": "#/components/responses/art_Forbidden" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Data Security" ], "x-api-token-group": [ "Zero Trust Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "analytics.query", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/analytics/query/data-security/findings/summary": { "post": { "operationId": "data-security-findings-summary", "summary": "Data security findings summary", "description": "Returns aggregate current-period and previous-period totals for CASB findings.\n", "parameters": [ { "$ref": "#/components/parameters/art_account_id" } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "findings_summary": { "summary": "Summary for a week", "value": { "filters": [], "from": "2024-11-01T00:00:00Z", "to": "2024-11-08T00:00:00Z" } } }, "schema": { "$ref": "#/components/schemas/art_DataSecurityFindingsSummaryQuery" } } } }, "responses": { "200": { "description": "Findings summary result.", "content": { "application/json": { "examples": { "success": { "summary": "Successful findings summary", "value": { "errors": [], "messages": [ { "code": 1000, "message": "API in beta: expect breaking changes." } ], "result": { "currentTotal": [ { "findingProduct": "Cloud", "findingType": "Content", "findingsTotal": 48291 }, { "findingProduct": "SaaS", "findingType": "Posture", "findingsTotal": 1205 } ], "previousTotal": [ { "findingProduct": "Cloud", "findingType": "Content", "findingsTotal": 41033 }, { "findingProduct": "SaaS", "findingType": "Posture", "findingsTotal": 982 } ] }, "success": true } } }, "schema": { "$ref": "#/components/schemas/art_SummaryResponse" } } } }, "400": { "$ref": "#/components/responses/art_BadRequest" }, "401": { "$ref": "#/components/responses/art_Unauthorized" }, "403": { "$ref": "#/components/responses/art_Forbidden" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Data Security" ], "x-api-token-group": [ "Zero Trust Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "analytics.query", "x-fern-sdk-method-name": "dataSecurityFindingsSummary", "x-forge-hidden": true } }, "/accounts/{account_id}/analytics/query/data-security/findings/timeseries": { "post": { "operationId": "data-security-findings-timeseries", "summary": "Data security findings timeseries", "description": "Returns merged time-bucketed CASB findings.\n", "parameters": [ { "$ref": "#/components/parameters/art_account_id" } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "findings_timeseries": { "summary": "Weekly findings timeseries", "value": { "filters": [], "from": "2024-11-01T00:00:00Z", "to": "2024-11-08T00:00:00Z" } } }, "schema": { "$ref": "#/components/schemas/art_DataSecurityFindingsTimeseriesQuery" } } } }, "responses": { "200": { "description": "Findings timeseries result.", "content": { "application/json": { "examples": { "success": { "summary": "Successful findings timeseries", "value": { "errors": [], "messages": [ { "code": 1000, "message": "API in beta: expect breaking changes." } ], "result": { "slots": [ { "content": { "cloud": 150, "saas": 23 }, "posture": { "cloud": 0, "saas": 5 }, "timestamp": "2024-11-05T00:00:00Z" }, { "content": { "cloud": 180, "saas": 30 }, "posture": { "cloud": 0, "saas": 7 }, "timestamp": "2024-11-06T00:00:00Z" } ] }, "success": true } } }, "schema": { "$ref": "#/components/schemas/art_DataSecurityFindingsTimeseriesResponse" } } } }, "400": { "$ref": "#/components/responses/art_BadRequest" }, "401": { "$ref": "#/components/responses/art_Unauthorized" }, "403": { "$ref": "#/components/responses/art_Forbidden" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Data Security" ], "x-api-token-group": [ "Zero Trust Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "analytics.query", "x-fern-sdk-method-name": "dataSecurityFindingsTimeseries", "x-forge-hidden": true } }, "/accounts/{account_id}/analytics/query/{dataset}/summary": { "post": { "operationId": "art-analytics-query-summary", "summary": "Query analytics summary", "description": "Returns aggregate summary stats for a dataset. Includes current-period and previous-period totals for trend comparison.\n", "parameters": [ { "$ref": "#/components/parameters/art_account_id" }, { "name": "dataset", "in": "path", "description": "Dataset name to query. Examples: `access-logins`, `gateway-http`, `gateway-dns`, `gateway-http`, `shadow-it`.\n", "required": true, "schema": { "type": "string", "example": "access-logins" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "access_summary": { "summary": "Access login summary for a week", "value": { "filters": [], "from": "2024-11-01T00:00:00Z", "groupBy": [], "stats": [ "attemptsTotal" ], "to": "2024-11-08T00:00:00Z" } } }, "schema": { "$ref": "#/components/schemas/art_QuerySummary" } } } }, "responses": { "200": { "description": "Summary query result.", "content": { "application/json": { "examples": { "success": { "summary": "Successful summary result", "value": { "errors": [], "messages": [ { "code": 1000, "message": "API in beta: expect breaking changes." } ], "result": { "currentTotal": [ { "attemptsTotal": 48291 } ], "previousTotal": [ { "attemptsTotal": 41033 } ] }, "success": true } } }, "schema": { "$ref": "#/components/schemas/art_SummaryResponse" } } } }, "400": { "$ref": "#/components/responses/art_BadRequest" }, "401": { "$ref": "#/components/responses/art_Unauthorized" }, "403": { "$ref": "#/components/responses/art_Forbidden" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "ART Analytics" ], "x-api-token-group": [ "Zero Trust Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "analytics.query", "x-fern-sdk-method-name": "artAnalyticsQuerySummary", "x-forge-hidden": true } }, "/accounts/{account_id}/analytics/query/{dataset}/timeseries": { "post": { "operationId": "art-analytics-query-timeseries", "summary": "Query analytics timeseries", "description": "Returns time-bucketed analytics data for a dataset. Includes time slots, each containing the requested stats, group-by dimensions, and resolution-controlled bucket size (e.g. `hour`, `day`).\n", "parameters": [ { "$ref": "#/components/parameters/art_account_id" }, { "name": "dataset", "in": "path", "description": "Dataset name to query. Examples: `access-logins`, `gateway-http`, `gateway-dns`, `gateway-http`, `shadow-it`.\n", "required": true, "schema": { "type": "string", "example": "shadow_it" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "access_logins_daily": { "summary": "Access logins daily timeseries with filter", "value": { "filters": [ { "name": "allowed", "op": "eq", "values": [ true ] } ], "from": "2024-11-01T00:00:00Z", "groupBy": [ "country", "allowed" ], "resolution": "day", "stats": [ "attemptsTotal" ], "to": "2024-11-08T00:00:00Z" } }, "shadow_it_hourly": { "summary": "Shadow IT hourly timeseries", "value": { "filters": [], "from": "2024-11-05T00:00:00Z", "groupBy": [ "appName" ], "resolution": "hour", "stats": [ "bytesTotal" ], "to": "2024-11-06T00:00:00Z" } } }, "schema": { "$ref": "#/components/schemas/art_QueryTimeseries" } } } }, "responses": { "200": { "description": "Timeseries query result.", "content": { "application/json": { "examples": { "success": { "summary": "Successful timeseries result", "value": { "errors": [], "messages": [ { "code": 1000, "message": "API in beta: expect breaking changes." } ], "result": { "resolution": "hour", "slots": [ { "appName": "Slack", "bytesTotal": 1048576, "time_bucket": "2024-11-05T00:00:00Z" }, { "appName": "Slack", "bytesTotal": 2097152, "time_bucket": "2024-11-05T01:00:00Z" } ] }, "success": true } } }, "schema": { "$ref": "#/components/schemas/art_TimeseriesResponse" } } } }, "400": { "$ref": "#/components/responses/art_BadRequest" }, "401": { "$ref": "#/components/responses/art_Unauthorized" }, "403": { "$ref": "#/components/responses/art_Forbidden" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "ART Analytics" ], "x-api-token-group": [ "Zero Trust Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "analytics.query", "x-fern-sdk-method-name": "artAnalyticsQueryTimeseries", "x-forge-hidden": true } }, "/accounts/{account_id}/analytics/query/{dataset}/top-n": { "post": { "operationId": "art-analytics-query-top-n", "summary": "Query analytics top-N", "description": "Returns the top N results for a dataset by a specified stat. Includes an array of result rows, each containing the requested stats and group-by dimensions.\n", "parameters": [ { "$ref": "#/components/parameters/art_account_id" }, { "name": "dataset", "in": "path", "description": "Dataset name to query. Examples: `access-logins`, `gateway-http`, `gateway-dns`, `gateway-http`, `shadow-it`.\n", "required": true, "schema": { "type": "string", "example": "gateway-http" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "top_apps_by_bytes": { "summary": "Top 10 shadow IT apps by bytes", "value": { "filters": [], "from": "2024-11-05T00:00:00Z", "groupBy": [ "appName", "appCategory" ], "n": 10, "orderBy": "bytesTotal", "stats": [ "bytesTotal", "requestsTotal" ], "to": "2024-11-06T00:00:00Z" } }, "top_countries_access": { "summary": "Top 5 countries by login attempts", "value": { "filters": [ { "name": "allowed", "op": "eq", "values": [ false ] } ], "from": "2024-11-01T00:00:00Z", "groupBy": [ "country" ], "n": 5, "orderBy": "attemptsTotal", "stats": [ "attemptsTotal" ], "to": "2024-11-08T00:00:00Z" } } }, "schema": { "$ref": "#/components/schemas/art_QueryTopN" } } } }, "responses": { "200": { "description": "Top-N query result.", "content": { "application/json": { "examples": { "success": { "summary": "Successful top-N result", "value": { "errors": [], "messages": [ { "code": 1000, "message": "API in beta: expect breaking changes." } ], "result": [ { "appCategory": "Collaboration", "appName": "Slack", "bytesTotal": 10485760, "requestsTotal": 1024 }, { "appCategory": "File Storage", "appName": "Dropbox", "bytesTotal": 5242880, "requestsTotal": 512 } ], "success": true } } }, "schema": { "$ref": "#/components/schemas/art_TopNResponse" } } } }, "400": { "$ref": "#/components/responses/art_BadRequest" }, "401": { "$ref": "#/components/responses/art_Unauthorized" }, "403": { "$ref": "#/components/responses/art_Forbidden" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "ART Analytics" ], "x-api-token-group": [ "Zero Trust Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "analytics.query", "x-fern-sdk-method-name": "artAnalyticsQueryTopN", "x-forge-hidden": true } }, "/accounts/{account_id}/analytics_engine/sql": { "get": { "operationId": "analytics-engine-sql-query-get", "summary": "Execute an Analytics Engine SQL query via query parameter", "description": "Executes a SQL query against Workers Analytics Engine data. Pass the SQL query as a query parameter. The response uses newline-delimited JSON (NDJSON) by default, or a single JSON object when the query includes a FORMAT JSON clause. Use the POST method for longer queries that may exceed URL length limits.", "parameters": [ { "name": "query", "in": "query", "description": "Supply a SQL query to run against your Analytics Engine datasets. Use only SELECT statements. The service validates the query against a restricted SQL grammar before execution.", "required": true, "schema": { "type": "string", "example": "SELECT blob1, count() FROM my_dataset WHERE timestamp > NOW() - INTERVAL '1' DAY GROUP BY blob1 ORDER BY count() DESC LIMIT 10" } } ], "responses": { "200": { "$ref": "#/components/responses/analytics-engine_QuerySuccess" }, "400": { "$ref": "#/components/responses/analytics-engine_BadRequest" }, "403": { "$ref": "#/components/responses/analytics-engine_Forbidden" }, "422": { "$ref": "#/components/responses/analytics-engine_UnprocessableQuery" }, "429": { "$ref": "#/components/responses/analytics-engine_TooManyRequests" }, "500": { "$ref": "#/components/responses/analytics-engine_InternalServerError" }, "503": { "$ref": "#/components/responses/analytics-engine_ServiceUnavailable" }, "504": { "$ref": "#/components/responses/analytics-engine_GatewayTimeout" } }, "security": [ { "api_token": [] } ], "tags": [ "Analytics Engine" ], "x-api-token-group": [ "Account Analytics Read" ], "x-fern-availability": "generally-available", "x-fern-ignore": true, "x-fern-sdk-group-name": "analytics_engine.sql", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/analytics-engine_AccountId" } ], "post": { "operationId": "analytics-engine-sql-query-post", "summary": "Execute an Analytics Engine SQL query via request body", "description": "Executes a SQL query against Workers Analytics Engine data. Pass the SQL query in the request body as plain text. The response uses newline-delimited JSON (NDJSON) by default, or a single JSON object when the query includes a FORMAT JSON clause. Prefer this method for longer queries that may exceed URL length limits.", "requestBody": { "required": true, "content": { "text/plain": { "examples": { "aggregation_query": { "summary": "Aggregation with time filter", "value": "SELECT blob1, sum(double1) as total\nFROM my_dataset\nWHERE timestamp > NOW() - INTERVAL '7' DAY\nGROUP BY blob1\nORDER BY total DESC\nLIMIT 100\n" }, "json_format_query": { "summary": "Query with JSON output format", "value": "SELECT blob1, count() FROM my_dataset GROUP BY blob1 FORMAT JSON" }, "simple_query": { "summary": "Simple count query", "value": "SELECT count() FROM my_dataset" } }, "schema": { "description": "Supply a SQL query to run against your Analytics Engine datasets. Use only SELECT statements. The service validates the query against a restricted SQL grammar before execution.", "type": "string" } } } }, "responses": { "200": { "$ref": "#/components/responses/analytics-engine_QuerySuccess" }, "400": { "$ref": "#/components/responses/analytics-engine_BadRequest" }, "403": { "$ref": "#/components/responses/analytics-engine_Forbidden" }, "422": { "$ref": "#/components/responses/analytics-engine_UnprocessableQuery" }, "429": { "$ref": "#/components/responses/analytics-engine_TooManyRequests" }, "500": { "$ref": "#/components/responses/analytics-engine_InternalServerError" }, "503": { "$ref": "#/components/responses/analytics-engine_ServiceUnavailable" }, "504": { "$ref": "#/components/responses/analytics-engine_GatewayTimeout" } }, "security": [ { "api_token": [] } ], "tags": [ "Analytics Engine" ], "x-api-token-group": [ "Account Analytics Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "analytics_engine.sql", "x-fern-sdk-method-name": "query", "x-forge-hidden": true } }, "/accounts/{account_id}/artifacts/namespaces": { "get": { "operationId": "artifacts_namespaces_list", "summary": "List namespaces", "description": "Lists Artifacts namespaces for an account.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 200, "minimum": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Namespaces.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "array", "items": { "properties": { "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "jurisdiction": { "type": "string", "enum": [ "unrestricted", "us", "eu", "fedramp" ] }, "namespace": { "type": "string" }, "repo_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "namespace", "jurisdiction", "repo_count", "created_at", "updated_at" ], "type": "object" } }, "result_info": { "anyOf": [ { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "cursor": { "type": "string" }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "cursor", "per_page", "count" ], "type": "object" }, { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_pages": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "page", "per_page", "total_pages", "count", "total_count" ], "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Read" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces", "x-fern-sdk-method-name": "list", "x-forge-hidden": true, "x-stability": "beta" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "artifacts_namespaces_create", "summary": "Create a namespace", "description": "Creates an empty Artifacts namespace for an account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jurisdiction": { "type": "string", "default": "unrestricted", "enum": [ "unrestricted", "us", "eu", "fedramp" ] }, "namespace": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, "required": [ "namespace" ] } } } }, "responses": { "201": { "description": "Namespace created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "jurisdiction": { "type": "string", "enum": [ "unrestricted", "us", "eu", "fedramp" ] }, "namespace": { "type": "string" }, "repo_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "namespace", "jurisdiction", "repo_count", "created_at", "updated_at" ] }, "result_info": { "anyOf": [ { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "cursor": { "type": "string" }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "cursor", "per_page", "count" ], "type": "object" }, { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_pages": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "page", "per_page", "total_pages", "count", "total_count" ], "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "409": { "description": "Operation conflict.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Edit" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-stability": "beta" } }, "/accounts/{account_id}/artifacts/namespaces/{namespace}": { "delete": { "operationId": "artifacts_namespaces_delete", "summary": "Delete a namespace", "description": "Deletes an empty Artifacts namespace.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } } ], "responses": { "204": { "description": "Namespace deleted." }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "409": { "description": "Operation conflict.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Edit" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-stability": "beta" }, "get": { "operationId": "artifacts_namespaces_get", "summary": "Get a namespace", "description": "Returns an Artifacts namespace summary.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } } ], "responses": { "200": { "description": "Namespace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "jurisdiction": { "type": "string", "enum": [ "unrestricted", "us", "eu", "fedramp" ] }, "namespace": { "type": "string" }, "repo_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "namespace", "jurisdiction", "repo_count", "created_at", "updated_at" ] }, "result_info": { "anyOf": [ { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "cursor": { "type": "string" }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "cursor", "per_page", "count" ], "type": "object" }, { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_pages": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "page", "per_page", "total_pages", "count", "total_count" ], "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Read" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stability": "beta" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ] }, "/accounts/{account_id}/artifacts/namespaces/{namespace}/repos": { "get": { "operationId": "artifacts_repos_list", "summary": "List repositories", "description": "Lists repositories in a namespace.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200, "minimum": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "default": "created_at", "enum": [ "created_at", "updated_at", "last_push_at", "name" ] } }, { "name": "direction", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Repositories.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "array", "items": { "properties": { "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "default_branch": { "description": "Default branch name. Must not contain '..' and must not end with '/' or '.'.", "type": "string" }, "description": { "type": "string", "nullable": true }, "id": { "type": "string" }, "last_push_at": { "type": "string", "format": "date-time", "nullable": true, "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "name": { "type": "string" }, "read_only": { "type": "boolean" }, "remote": { "type": "string" }, "source": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "name", "description", "default_branch", "created_at", "updated_at", "last_push_at", "source", "read_only", "remote" ], "type": "object" } }, "result_info": { "anyOf": [ { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "cursor": { "type": "string" }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "cursor", "per_page", "count" ], "type": "object" }, { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_pages": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "page", "per_page", "total_pages", "count", "total_count" ], "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Read" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces.repos", "x-fern-sdk-method-name": "list", "x-forge-hidden": true, "x-stability": "beta" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "artifacts_repos_create", "summary": "Create a repository", "description": "Creates a Git-compatible Artifacts repository in a namespace.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "default_branch": { "description": "Git branch name. Must match /^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/, must not contain '..', and must not end with '/' or '.'.", "type": "string", "maxLength": 256, "minLength": 1, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._/-]*$" }, "description": { "type": "string", "maxLength": 1024 }, "name": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" }, "read_only": { "type": "boolean" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Repository created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "default_branch": { "type": "string" }, "description": { "type": "string", "nullable": true }, "id": { "type": "string" }, "name": { "type": "string" }, "remote": { "type": "string" }, "token": { "type": "string" } }, "required": [ "id", "name", "description", "default_branch", "remote", "token" ] }, "result_info": { "anyOf": [ { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "cursor": { "type": "string" }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "cursor", "per_page", "count" ], "type": "object" }, { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_pages": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "page", "per_page", "total_pages", "count", "total_count" ], "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "409": { "description": "Operation conflict.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Edit" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces.repos", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-stability": "beta" } }, "/accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}": { "delete": { "operationId": "artifacts_repos_delete", "summary": "Delete a repository", "description": "Deletes a repository and schedules cleanup of its backing data.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "name", "in": "path", "description": "Repository name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } } ], "responses": { "202": { "description": "Delete accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "result_info": { "anyOf": [ { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "cursor": { "type": "string" }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "cursor", "per_page", "count" ], "type": "object" }, { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_pages": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "page", "per_page", "total_pages", "count", "total_count" ], "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Edit" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces.repos", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-stability": "beta" }, "get": { "operationId": "artifacts_repos_get", "summary": "Get a repository", "description": "Returns repository metadata.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "name", "in": "path", "description": "Repository name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } } ], "responses": { "200": { "description": "Repository.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "default_branch": { "description": "Default branch name. Must not contain '..' and must not end with '/' or '.'.", "type": "string" }, "description": { "type": "string", "nullable": true }, "id": { "type": "string" }, "last_push_at": { "type": "string", "format": "date-time", "nullable": true, "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "name": { "type": "string" }, "read_only": { "type": "boolean" }, "remote": { "type": "string" }, "source": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "name", "description", "default_branch", "created_at", "updated_at", "last_push_at", "source", "read_only", "remote" ] }, "result_info": { "anyOf": [ { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "cursor": { "type": "string" }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "cursor", "per_page", "count" ], "type": "object" }, { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_pages": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "page", "per_page", "total_pages", "count", "total_count" ], "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "409": { "description": "Operation conflict.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Read" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces.repos", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stability": "beta" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ] }, "/accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/blob/{hash}": { "get": { "operationId": "artifacts_repos_blob_get", "summary": "Read a Git blob", "description": "Returns raw bytes for an immutable Git blob object. Blob responses are cacheable forever by hash.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "name", "in": "path", "description": "Repository name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "hash", "in": "path", "description": "40-character lowercase hexadecimal Git object hash.", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$" } } ], "responses": { "200": { "description": "Blob bytes.", "headers": { "cache-control": { "description": "Immutable object cache policy.", "schema": { "type": "string" } }, "content-length": { "description": "Size of the response body in bytes.", "schema": { "type": "integer" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "413": { "description": "Request entity too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Read" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces.repos.blobs", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stability": "beta" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ] }, "/accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/commit/{hash}": { "get": { "operationId": "artifacts_repos_commit_get", "summary": "Read a Git commit", "description": "Returns decoded metadata for an immutable Git commit object. Commit responses are cacheable forever by hash.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "name", "in": "path", "description": "Repository name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "hash", "in": "path", "description": "40-character lowercase hexadecimal Git object hash.", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$" } } ], "responses": { "200": { "description": "Commit metadata.", "headers": { "cache-control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "author": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "email" ] }, "authoredAt": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "committedAt": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "committer": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "email" ] }, "hash": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "message": { "type": "string" }, "parents": { "type": "array", "items": { "pattern": "^[0-9a-f]{40}$", "type": "string" } }, "treeHash": { "type": "string", "pattern": "^[0-9a-f]{40}$" } }, "required": [ "hash", "treeHash", "message", "author", "committer", "parents", "authoredAt", "committedAt" ] }, "result_info": { "anyOf": [ { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "cursor": { "type": "string" }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "cursor", "per_page", "count" ], "type": "object" }, { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_pages": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "page", "per_page", "total_pages", "count", "total_count" ], "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Read" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces.repos.commits", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stability": "beta" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ] }, "/accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/file": { "get": { "operationId": "artifacts_repos_file_get", "summary": "Read a file", "description": "Returns raw bytes for a file resolved by ref and path.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "name", "in": "path", "description": "Repository name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "ref", "in": "query", "description": "Git ref, branch, tag, or commit hash.", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "path", "in": "query", "description": "File path.", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "File bytes.", "headers": { "content-length": { "description": "Size of the response body in bytes.", "schema": { "type": "integer" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "413": { "description": "Request entity too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Read" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces.repos.files", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stability": "beta" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ] }, "/accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/fork": { "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "artifacts_repos_fork", "summary": "Fork a repository", "description": "Forks a source repository into a new repository.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "name", "in": "path", "description": "Repository name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "default_branch_only": { "type": "boolean" }, "description": { "type": "string", "maxLength": 1024 }, "name": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" }, "read_only": { "type": "boolean" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Repository forked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "default_branch": { "type": "string" }, "description": { "type": "string", "nullable": true }, "id": { "type": "string" }, "name": { "type": "string" }, "objects": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "remote": { "type": "string" }, "token": { "type": "string" } }, "required": [ "id", "name", "description", "default_branch", "remote", "token", "objects" ] }, "result_info": { "anyOf": [ { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "cursor": { "type": "string" }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "cursor", "per_page", "count" ], "type": "object" }, { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_pages": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "page", "per_page", "total_pages", "count", "total_count" ], "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "409": { "description": "Operation conflict.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "503": { "description": "Service unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Edit" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces.repos", "x-fern-sdk-method-name": "fork", "x-forge-hidden": true, "x-stability": "beta" } }, "/accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/import": { "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "artifacts_repos_import", "summary": "Import a repository", "description": "Imports an HTTPS Git repository into an Artifacts repository.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "name", "in": "path", "description": "Repository name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "branch": { "description": "Git branch name. Must match /^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/, must not contain '..', and must not end with '/' or '.'.", "type": "string", "maxLength": 256, "minLength": 1, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._/-]*$" }, "depth": { "type": "integer", "maximum": 9007199254740991, "minimum": 1 }, "read_only": { "type": "boolean" }, "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "Repository import started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "default_branch": { "type": "string" }, "description": { "type": "string", "nullable": true }, "id": { "type": "string" }, "name": { "type": "string" }, "remote": { "type": "string" }, "token": { "type": "string" } }, "required": [ "id", "name", "description", "default_branch", "remote", "token" ] }, "result_info": { "anyOf": [ { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "cursor": { "type": "string" }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "cursor", "per_page", "count" ], "type": "object" }, { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_pages": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "page", "per_page", "total_pages", "count", "total_count" ], "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "409": { "description": "Operation conflict.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "413": { "description": "Request entity too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "422": { "description": "Unprocessable entity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "502": { "description": "Upstream unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "503": { "description": "Service unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "504": { "description": "Gateway timeout.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Edit" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces.repos", "x-fern-sdk-method-name": "import", "x-forge-hidden": true, "x-stability": "beta" } }, "/accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/log": { "get": { "operationId": "artifacts_repos_log_get", "summary": "Read commit history", "description": "Returns commit metadata walking backwards from a ref, branch, tag, or HEAD.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "name", "in": "path", "description": "Repository name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "ref", "in": "query", "description": "Git ref, branch, tag, or commit hash. Defaults to HEAD.", "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 1000, "minimum": 1 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Commits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "array", "items": { "properties": { "author": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "email" ] }, "authoredAt": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "committedAt": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "committer": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "email" ] }, "hash": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "message": { "type": "string" }, "parents": { "type": "array", "items": { "pattern": "^[0-9a-f]{40}$", "type": "string" } }, "treeHash": { "type": "string", "pattern": "^[0-9a-f]{40}$" } }, "required": [ "hash", "treeHash", "message", "author", "committer", "parents", "authoredAt", "committedAt" ], "type": "object" } }, "result_info": { "anyOf": [ { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "cursor": { "type": "string" }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "cursor", "per_page", "count" ], "type": "object" }, { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_pages": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "page", "per_page", "total_pages", "count", "total_count" ], "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Read" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces.repos.logs", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stability": "beta" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ] }, "/accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/raw/{ref}/{path}": { "get": { "operationId": "artifacts_repos_raw_get", "summary": "Read a raw file with content type", "description": "Returns file bytes resolved by ref and path, with a sniffed content type and browser-safe response headers.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "name", "in": "path", "description": "Repository name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "ref", "in": "path", "description": "Git ref, branch, tag, or 40-character commit hash.", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "path", "in": "path", "description": "File path. May contain slashes.", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "File bytes with sniffed Content-Type and browser-safe response headers.", "headers": { "content-length": { "description": "Size of the response body in bytes.", "schema": { "type": "integer" } }, "content-security-policy": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "string" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "text/html": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "413": { "description": "Request entity too large.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Read" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces.repos.raw", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stability": "beta" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ] }, "/accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/tokens": { "get": { "operationId": "artifacts_repo_tokens_list", "summary": "List repository tokens", "description": "Lists tokens for a repository.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "name", "in": "path", "description": "Repository name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "state", "in": "query", "schema": { "type": "string", "default": "active", "enum": [ "active", "expired", "revoked", "all" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Tokens.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "array", "items": { "properties": { "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "expires_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "id": { "type": "string" }, "scope": { "type": "string", "enum": [ "read", "write" ] }, "state": { "type": "string", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "id", "scope", "state", "created_at", "expires_at" ], "type": "object" } }, "result_info": { "anyOf": [ { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "cursor": { "type": "string" }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "cursor", "per_page", "count" ], "type": "object" }, { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_pages": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "page", "per_page", "total_pages", "count", "total_count" ], "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "409": { "description": "Operation conflict.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Read" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces.repos.tokens", "x-fern-sdk-method-name": "list", "x-forge-hidden": true, "x-stability": "beta" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ] }, "/accounts/{account_id}/artifacts/namespaces/{namespace}/repos/{name}/tree/{hash}": { "get": { "operationId": "artifacts_repos_tree_get", "summary": "Read a Git tree", "description": "Returns decoded entries for an immutable Git tree object. Tree responses are cacheable forever by hash.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "name", "in": "path", "description": "Repository name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "hash", "in": "path", "description": "40-character lowercase hexadecimal Git object hash.", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$" } } ], "responses": { "200": { "description": "Tree entries.", "headers": { "cache-control": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "array", "items": { "properties": { "hash": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "mode": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "tree", "blob", "symlink", "gitlink", "exec" ] } }, "required": [ "name", "mode", "hash", "type" ], "type": "object" } }, "result_info": { "anyOf": [ { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "cursor": { "type": "string" }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "cursor", "per_page", "count" ], "type": "object" }, { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_pages": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "page", "per_page", "total_pages", "count", "total_count" ], "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Read" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces.repos.trees", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stability": "beta" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ] }, "/accounts/{account_id}/artifacts/namespaces/{namespace}/tokens": { "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "artifacts_tokens_create", "summary": "Create a repository token", "description": "Creates a scoped Git token for a repository.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repo": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" }, "scope": { "type": "string", "enum": [ "read", "write" ] }, "ttl": { "type": "integer", "maximum": 31536000, "minimum": 60 } }, "required": [ "repo" ] } } } }, "responses": { "201": { "description": "Token created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "expires_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "id": { "type": "string" }, "plaintext": { "type": "string" }, "scope": { "type": "string", "enum": [ "read", "write" ] } }, "required": [ "id", "plaintext", "scope", "expires_at" ] }, "result_info": { "anyOf": [ { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "cursor": { "type": "string" }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "cursor", "per_page", "count" ], "type": "object" }, { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_pages": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "page", "per_page", "total_pages", "count", "total_count" ], "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "409": { "description": "Operation conflict.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Edit" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces.tokens", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-stability": "beta" } }, "/accounts/{account_id}/artifacts/namespaces/{namespace}/tokens/{id}": { "delete": { "operationId": "artifacts_tokens_revoke", "summary": "Revoke a token", "description": "Revokes an Artifacts repository token.", "parameters": [ { "name": "namespace", "in": "path", "description": "Artifacts namespace name.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" } }, { "name": "id", "in": "path", "description": "Token ID. Must match /^[0-9a-z]{16}$/.", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-z]{16}$" } } ], "responses": { "200": { "description": "Token revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "result_info": { "anyOf": [ { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "cursor": { "type": "string" }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "cursor", "per_page", "count" ], "type": "object" }, { "properties": { "count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "per_page": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "total_pages": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } }, "required": [ "page", "per_page", "total_pages", "count", "total_count" ], "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "documentation_url": { "type": "string", "format": "uri" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Artifacts" ], "x-api-token-group": [ "Artifacts Edit" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "artifacts.namespaces.tokens", "x-fern-sdk-method-name": "revoke", "x-forge-hidden": true, "x-stability": "beta" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ] }, "/accounts/{account_id}/audit_logs": { "get": { "operationId": "audit-logs-get-account-audit-logs", "summary": "Get account audit logs", "description": "Gets a list of audit logs for an account. Can be filtered by who made the change, on which zone, and the timeframe of the change.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/aaa_identifier" } }, { "name": "id", "in": "query", "schema": { "description": "Finds a specific log by its ID.", "type": "string", "example": "f174be97-19b1-40d6-954d-70cd5fbd52db" } }, { "name": "export", "in": "query", "schema": { "description": "Indicates that this request is an export of logs in CSV format.", "type": "boolean", "example": true } }, { "name": "action.type", "in": "query", "schema": { "description": "Filters by the action type.", "type": "string", "example": "add" } }, { "name": "actor.ip", "in": "query", "schema": { "description": "Filters by the IP address of the request that made the change by specific IP address or valid CIDR Range.", "type": "string", "example": "17.168.228.63" } }, { "name": "actor.email", "in": "query", "schema": { "description": "Filters by the email address of the actor that made the change.", "type": "string", "format": "email", "example": "alice@example.com" } }, { "name": "since", "in": "query", "schema": { "oneOf": [ { "description": "Limits the returned results to logs newer than the specified date. A `full-date` that conforms to RFC3339.", "example": "2019-04-30", "format": "date", "type": "string" }, { "description": "Limits the returned results to logs newer than the specified date. A `date-time` that conforms to RFC3339.", "example": "2019-04-30T01:12:20Z", "format": "date-time", "type": "string" } ] } }, { "name": "before", "in": "query", "schema": { "oneOf": [ { "description": "Limits the returned results to logs older than the specified date. A `full-date` that conforms to RFC3339.", "example": "2019-04-30", "format": "date", "type": "string" }, { "description": "Limits the returned results to logs older than the specified date. A `date-time` that conforms to RFC3339.", "example": "2019-04-30T01:12:20Z", "format": "date-time", "type": "string" } ] } }, { "name": "zone.name", "in": "query", "schema": { "description": "Filters by the name of the zone associated to the change.", "type": "string", "example": "example.com" } }, { "name": "direction", "in": "query", "schema": { "description": "Changes the direction of the chronological sorting.", "type": "string", "example": "desc", "default": "desc", "enum": [ "desc", "asc" ] } }, { "name": "per_page", "in": "query", "schema": { "description": "Sets the number of results to return per page.", "type": "number", "example": 25, "default": 100, "maximum": 1000, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "description": "Defines which page of results to return.", "type": "number", "example": 50, "default": 1, "minimum": 1 } }, { "name": "hide_user_logs", "in": "query", "schema": { "description": "Indicates whether or not to hide user level audit logs.", "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Get account audit logs response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_audit_logs_response_collection" } } } }, "4XX": { "description": "Get account audit logs response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_audit_logs_response_collection" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Audit Logs" ], "x-api-token-group": [ "Account Settings Write", "Account Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "audit-logs", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/autorag/rags/{id}/ai-search": { "post": { "operationId": "autorag-config-ai-search", "summary": "AI Search", "description": "Runs an AI Search query against an AutoRAG.", "parameters": [ { "name": "id", "in": "path", "description": "rag id", "required": true, "schema": { "description": "rag id", "type": "string", "example": "my-rag", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "anyOf": [ { "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte" ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "key", "type", "value" ], "type": "object" }, { "properties": { "filters": { "type": "array", "items": { "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte" ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "key", "type", "value" ], "type": "object" } }, "type": { "type": "string", "enum": [ "and", "or" ] } }, "required": [ "type", "filters" ], "type": "object" } ] }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1 }, "model": { "anyOf": [ { "enum": [ "@cf/meta/llama-3.3-70b-instruct-fp8-fast", "@cf/meta/llama-3.1-8b-instruct-fast", "@cf/meta/llama-3.1-8b-instruct-fp8", "@cf/meta/llama-4-scout-17b-16e-instruct", "@cf/qwen/qwen3-30b-a3b-fp8", "@cf/deepseek-ai/deepseek-r1-distill-qwen-32b", "@cf/moonshotai/kimi-k2-instruct", "anthropic/claude-3-7-sonnet", "anthropic/claude-sonnet-4", "anthropic/claude-opus-4", "anthropic/claude-3-5-haiku", "cerebras/qwen-3-235b-a22b-instruct", "cerebras/qwen-3-235b-a22b-thinking", "cerebras/llama-3.3-70b", "cerebras/llama-4-maverick-17b-128e-instruct", "cerebras/llama-4-scout-17b-16e-instruct", "cerebras/gpt-oss-120b", "google-ai-studio/gemini-2.5-flash", "google-ai-studio/gemini-2.5-pro", "grok/grok-4", "groq/llama-3.3-70b-versatile", "groq/llama-3.1-8b-instant", "openai/gpt-5", "openai/gpt-5-mini", "openai/gpt-5-nano" ], "type": "string" }, { "enum": [ "" ], "type": "string" } ] }, "query": { "type": "string" }, "ranking_options": { "type": "object", "default": {}, "properties": { "ranker": { "type": "string" }, "score_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0 } } }, "reranking": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "model": { "anyOf": [ { "enum": [ "@cf/baai/bge-reranker-base" ], "type": "string" }, { "enum": [ "" ], "type": "string" } ] } } }, "rewrite_query": { "type": "boolean", "default": false }, "stream": { "type": "boolean", "default": false }, "system_prompt": { "type": "string" } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Returns the log details", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "attributes": { "type": "object" }, "content": { "items": { "properties": { "text": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "type": "array" }, "file_id": { "type": "string" }, "filename": { "type": "string" }, "score": { "type": "number" } }, "required": [ "score" ], "type": "object" } }, "has_more": { "type": "boolean", "default": false }, "next_page": { "type": "string", "nullable": true }, "object": { "type": "string" }, "response": { "type": "string" }, "search_query": { "type": "string" } }, "required": [ "search_query", "response" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AutoRAG RAG Search" ], "x-api-token-group": [ "Auto Rag Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.rag" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "autorag", "x-fern-sdk-method-name": "ai-search" } }, "/accounts/{account_id}/autorag/rags/{id}/files": { "get": { "operationId": "autorag-config-files", "summary": "Files", "description": "Lists files indexed by an AutoRAG.", "parameters": [ { "name": "id", "in": "path", "description": "rag id", "required": true, "schema": { "description": "rag id", "type": "string", "example": "my-rag", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50, "minimum": 0 } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "completed", "queued", "running", "error" ] } } ], "responses": { "200": { "description": "Returns the AI Search files", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "error": { "type": "string" }, "key": { "type": "string" } }, "required": [ "key", "error" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer", "default": 20, "maximum": 50, "minimum": 5 }, "total_count": { "type": "integer" } }, "required": [ "count", "page", "total_count" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "404": { "description": "autorag_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "autorag_not_found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "unable_to_connect_to_autorag", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7017 }, "message": { "type": "string", "example": "unable_to_connect_to_autorag" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AutoRAG RAG" ], "x-api-token-group": [ "Auto Rag Write", "Auto Rag Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.rag" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "autorag", "x-fern-sdk-method-name": "files" } }, "/accounts/{account_id}/autorag/rags/{id}/jobs": { "get": { "operationId": "autorag-config-list-jobs", "summary": "List Jobs", "description": "Lists jobs for an AutoRAG.", "parameters": [ { "name": "id", "in": "path", "description": "rag id", "required": true, "schema": { "description": "rag id", "type": "string", "example": "my-rag", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50, "minimum": 0 } } ], "responses": { "200": { "description": "Returns a list of AutoRAG Jobs", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "end_reason": { "type": "string" }, "ended_at": { "type": "string" }, "id": { "type": "string" }, "last_seen_at": { "type": "string" }, "source": { "type": "string", "enum": [ "user", "schedule" ] }, "started_at": { "type": "string" } }, "required": [ "id", "source" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" } }, "required": [ "count", "page", "per_page", "total_count" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "404": { "description": "autorag_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "autorag_not_found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "unable_to_connect_to_autorag", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7017 }, "message": { "type": "string", "example": "unable_to_connect_to_autorag" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AutoRAG Jobs" ], "x-api-token-group": [ "Auto Rag Write", "Auto Rag Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.rag" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "autorag.jobs", "x-fern-sdk-method-name": "list" } }, "/accounts/{account_id}/autorag/rags/{id}/jobs/{job_id}": { "get": { "operationId": "autorag-config-get-job", "summary": "Get a Job Details", "description": "Returns details for an AutoRAG job.", "parameters": [ { "name": "id", "in": "path", "description": "rag id", "required": true, "schema": { "description": "rag id", "type": "string", "example": "my-rag", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "responses": { "200": { "description": "Returns a AutoRAG Job Details", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "end_reason": { "type": "string" }, "ended_at": { "type": "string" }, "id": { "type": "string" }, "last_seen_at": { "type": "string" }, "source": { "type": "string", "enum": [ "user", "schedule" ] }, "started_at": { "type": "string" } }, "required": [ "id", "source" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "job_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7021 }, "message": { "type": "string", "example": "job_not_found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "unable_to_connect_to_autorag", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7017 }, "message": { "type": "string", "example": "unable_to_connect_to_autorag" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AutoRAG Jobs" ], "x-api-token-group": [ "Auto Rag Write", "Auto Rag Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.rag" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "autorag.jobs", "x-fern-sdk-method-name": "get" } }, "/accounts/{account_id}/autorag/rags/{id}/jobs/{job_id}/logs": { "get": { "operationId": "autorag-config-list-job-logs", "summary": "List Job Logs", "description": "Lists logs for an AutoRAG job.", "parameters": [ { "name": "id", "in": "path", "description": "rag id", "required": true, "schema": { "description": "rag id", "type": "string", "example": "my-rag", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 500, "minimum": 0 } } ], "responses": { "200": { "description": "Returns a list of AutoRAG Job Logs", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "properties": { "created_at": { "type": "number" }, "id": { "type": "integer" }, "message": { "type": "string" }, "message_type": { "type": "integer" } }, "required": [ "id", "message", "message_type", "created_at" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" } }, "required": [ "count", "page", "per_page", "total_count" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result", "result_info" ] } } } }, "404": { "description": "autorag_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "autorag_not_found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "unable_to_connect_to_autorag", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7017 }, "message": { "type": "string", "example": "unable_to_connect_to_autorag" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AutoRAG Jobs" ], "x-api-token-group": [ "Auto Rag Write", "Auto Rag Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.rag" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "autorag.jobs", "x-fern-sdk-method-name": "logs" } }, "/accounts/{account_id}/autorag/rags/{id}/search": { "post": { "operationId": "autorag-config-search", "summary": "Search", "description": "Searches an AutoRAG.", "parameters": [ { "name": "id", "in": "path", "description": "rag id", "required": true, "schema": { "description": "rag id", "type": "string", "example": "my-rag", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "anyOf": [ { "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte" ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "key", "type", "value" ], "type": "object" }, { "properties": { "filters": { "type": "array", "items": { "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte" ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "key", "type", "value" ], "type": "object" } }, "type": { "type": "string", "enum": [ "and", "or" ] } }, "required": [ "type", "filters" ], "type": "object" } ] }, "max_num_results": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1 }, "query": { "type": "string" }, "ranking_options": { "type": "object", "default": {}, "properties": { "ranker": { "type": "string" }, "score_threshold": { "type": "number", "default": 0.4, "maximum": 1, "minimum": 0 } } }, "reranking": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "model": { "anyOf": [ { "enum": [ "@cf/baai/bge-reranker-base" ], "type": "string" }, { "enum": [ "" ], "type": "string" } ] } } }, "rewrite_query": { "type": "boolean", "default": false } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Returns the log details", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "attributes": { "type": "object" }, "content": { "items": { "properties": { "text": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "type": "array" }, "file_id": { "type": "string" }, "filename": { "type": "string" }, "score": { "type": "number" } }, "required": [ "score" ], "type": "object" } }, "has_more": { "type": "boolean", "default": false }, "next_page": { "type": "string", "nullable": true }, "object": { "type": "string" }, "search_query": { "type": "string" } }, "required": [ "search_query" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "Not Found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AutoRAG RAG Search" ], "x-api-token-group": [ "Auto Rag Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.rag" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "autorag", "x-fern-sdk-method-name": "search" } }, "/accounts/{account_id}/autorag/rags/{id}/sync": { "patch": { "operationId": "autorag-config-sync", "summary": "Sync", "description": "Starts synchronization for an AutoRAG.", "parameters": [ { "name": "id", "in": "path", "description": "rag id", "required": true, "schema": { "description": "rag id", "type": "string", "example": "my-rag", "maxLength": 32, "minLength": 1, "pattern": "^[a-z0-9_]+(?:-[a-z0-9_]+)*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "example": "c3dc5f0b34a14ff8e1b3ec04895e1b22" } } ], "responses": { "200": { "description": "Returns the autorag sync status", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] } } } }, "400": { "description": "autorag_is_paused", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7032 }, "message": { "type": "string", "example": "autorag_is_paused" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "404": { "description": "autorag_not_found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7002 }, "message": { "type": "string", "example": "autorag_not_found" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "429": { "description": "sync_in_cooldown", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7020 }, "message": { "type": "string", "example": "sync_in_cooldown" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } }, "503": { "description": "unable_to_connect_to_autorag", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number", "example": 7017 }, "message": { "type": "string", "example": "unable_to_connect_to_autorag" } }, "required": [ "code", "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AutoRAG RAG" ], "x-api-token-group": [ "Auto Rag Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.rag" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "autorag", "x-fern-sdk-method-name": "sync" } }, "/accounts/{account_id}/billable-usage": { "get": { "operationId": "billable-usage-get-v1-account-usage", "summary": "Get Account Billable Usage (Version 1, Alpha)", "description": "Returns billable usage data for the account.\nWhen no query parameters are provided, returns usage for the current\nbilling period.\n", "parameters": [ { "$ref": "#/components/parameters/billable-usage-api_account_id" }, { "$ref": "#/components/parameters/billable-usage-api_from" }, { "$ref": "#/components/parameters/billable-usage-api_to" } ], "responses": { "200": { "description": "Indicates account usage data was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billable-usage-api_usage_response" } } } }, "4XX": { "description": "Indicates the request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billable-usage-api_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Billable Usage" ], "x-cfPlanAvailability": { "business": true, "enterprise": false, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "billing.usage", "x-fern-sdk-method-name": "get-v1" } }, "/accounts/{account_id}/billable-usage/info": { "get": { "operationId": "billable-usage-get-v1-account-usage-info", "summary": "Get Account Billable Usage Info (Version 1, Alpha)", "description": "Returns high-level usage information for the account, including coverage,\nand subscription metadata.\n", "parameters": [ { "$ref": "#/components/parameters/billable-usage-api_account_id" } ], "responses": { "200": { "description": "Indicates account usage data was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billable-usage-api_usage_info_response" } } } }, "4XX": { "description": "Indicates the request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billable-usage-api_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Billable Usage" ], "x-cfPlanAvailability": { "business": true, "enterprise": false, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "billing.usage", "x-fern-sdk-method-name": "get-info-v1" } }, "/accounts/{account_id}/billable/usage": { "get": { "operationId": "billable-usage-v2-get-account-usage", "summary": "Get Account Usage (Version 2, Alpha, Restricted)", "description": "Returns cost and usage data for a single Cloudflare account, aligned\nwith the [FinOps FOCUS v1.3](https://focus.finops.org/focus-specification/v1-3/)\nCost and Usage dataset specification.\n\nEach record represents one billable metric for one account on one day.\nThis includes all metered usage, including usage that falls within\nfree-tier allowances and may result in zero cost.\n\n**Note:** Cost and pricing fields are not yet populated and\nwill be absent from responses until billing integration is complete.\n\nWhen `from` and `to` are omitted, defaults to the start of the current\nmonth through today. The maximum date range is 31 days.\n", "parameters": [ { "$ref": "#/components/parameters/billable-usage-api_account_id" }, { "$ref": "#/components/parameters/billable-usage-api_v2_from" }, { "$ref": "#/components/parameters/billable-usage-api_v2_to" } ], "responses": { "200": { "description": "Account usage data was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billable-usage-api_v2_usage_response" } } } }, "4XX": { "description": "Indicates the request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billable-usage-api_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Billable Usage V2" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "billing.usage", "x-fern-sdk-method-name": "get-account-usage-v2" }, "post": { "operationId": "billable-usage-v2-query-account-usage", "summary": "Query Account Usage (Version 2, Alpha, Restricted)", "description": "Returns cost and usage data for a single Cloudflare account, aligned\nwith the [FinOps FOCUS v1.3](https://focus.finops.org/focus-specification/v1-3/)\nCost and Usage dataset specification.\n\nThis is the filterable counterpart to `GET` on the same path. It is a\nread-only operation and requires only the `#billing:read` permission;\n`POST` is used so that filter criteria can be supplied in a request body\nrather than in the query string.\n\nEach record represents one billable metric for one account on one day.\nThis includes all metered usage, including usage that falls within\nfree-tier allowances and may result in zero cost.\n\n**Note:** Cost and pricing fields are not yet populated and\nwill be absent from responses until billing integration is complete.\n\nThe request body is optional. When it is omitted, or when `TimePeriod`\nis omitted, the range defaults to the start of the current month through\ntoday. The maximum date range is 31 days.\n\nFilters of different kinds are combined with AND. Values within one tag\nfilter are combined with OR. Filter values that do not match usage\nproduce an empty result set.\n\nResults can be grouped by up to two customer resource-tag keys. Grouped\nvalues are returned in the `Tags` field. Usage without a requested tag\nremains in an untagged group, with that key omitted from `Tags`.\n\nRequests using tag filtering or grouping return HTTP 400 when tag-aware\nusage data is unavailable.\n", "parameters": [ { "$ref": "#/components/parameters/billable-usage-api_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billable-usage-api_v2_usage_query" } } } }, "responses": { "200": { "description": "Account usage data was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billable-usage-api_v2_usage_response" } } } }, "4XX": { "description": "Indicates the request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billable-usage-api_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Billable Usage V2" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "billing.usage", "x-fern-sdk-method-name": "query" } }, "/accounts/{account_id}/billing/bad-debt": { "get": { "operationId": "account-billing-get-bad-debt", "summary": "Get Account Bad Debt", "description": "Gets bad debt information for an account, including outstanding invoices and total debt amount.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "responses": { "200": { "description": "Get Account Bad Debt response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_bad_debt_response_single" } } } }, "4XX": { "description": "Get Account Bad Debt response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Billing" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "accounts.billing", "x-fern-sdk-method-name": "getBadDebt" } }, "/accounts/{account_id}/billing/credits": { "get": { "operationId": "account-billing-get-credits", "summary": "Get Account Credits", "description": "Gets the credit balance and eligibility for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "responses": { "200": { "description": "Get Account Credits response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_account_credits_response" } } } }, "4XX": { "description": "Get Account Credits response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Billing" ], "x-api-token-group": [ "Billing Write", "Billing Read" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "accounts.billing", "x-fern-sdk-method-name": "getCredits" } }, "/accounts/{account_id}/billing/history": { "get": { "operationId": "account-billing-history-get-billing-history", "summary": "Get Account Billing History", "description": "Gets the billing history for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of items per page.", "type": "integer", "default": 20, "minimum": 1 } }, { "name": "status", "in": "query", "schema": { "description": "Filter billing history by status.", "type": "string" } } ], "responses": { "200": { "description": "Get Account Billing History response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_account_billing_history_collection" } } } }, "4XX": { "description": "Get Account Billing History response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Billing History" ], "x-api-token-group": [ "Billing Write", "Billing Read" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "accounts.billing.history", "x-fern-sdk-method-name": "list" } }, "/accounts/{account_id}/billing/profile": { "delete": { "operationId": "account-billing-profile-delete-billing-profile", "summary": "Delete Billing Profile", "description": "Deletes the billing profile for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "responses": { "204": { "description": "Delete Billing Profile response" }, "4XX": { "description": "Delete Billing Profile response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Billing Profile" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "billing.profiles", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "account-billing-profile-get-billing-profile", "summary": "Get Billing Profile", "description": "Gets the current billing profile for the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "responses": { "200": { "description": "Billing Profile Details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_billing_response_single" } } } }, "4XX": { "description": "Billing Profile Details response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Billing Profile" ], "x-api-token-group": [ "Billing Write", "Billing Read" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "billing.profiles", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "account-billing-profile-update-billing-email", "summary": "Update Billing Email", "description": "Updates the billing email addresses and preferred locale for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "billing_email": { "type": "string", "example": "billing@example.com" }, "preferred_locale": { "type": "string", "example": "en-US" }, "secondary_billing_email": { "type": "string", "example": "secondary@example.com" } } } } } }, "responses": { "200": { "description": "Update Billing Email response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_billing_response_single" } } } }, "4XX": { "description": "Update Billing Email response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Billing Profile" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read", "#billing:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "billing.profiles", "x-fern-sdk-method-name": "updateEmail" }, "post": { "operationId": "account-billing-profile-create-billing-profile", "summary": "Create Billing Profile", "description": "Creates a billing profile for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_billing_profile_request" } } } }, "responses": { "200": { "description": "Create Billing Profile response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_billing_response_single" } } } }, "4XX": { "description": "Create Billing Profile response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Billing Profile" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read", "#billing:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "billing.profiles", "x-fern-sdk-method-name": "create" }, "put": { "operationId": "account-billing-profile-update-billing-profile", "summary": "Update Billing Profile", "description": "Updates the billing profile for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_billing_profile_request" } } } }, "responses": { "200": { "description": "Update Billing Profile response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_billing_response_single" } } } }, "4XX": { "description": "Update Billing Profile response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Billing Profile" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read", "#billing:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "billing.profiles", "x-fern-sdk-method-name": "update" } }, "/accounts/{account_id}/billing/profile/payment-method": { "post": { "operationId": "account-billing-create-payment-intent", "summary": "Create Payment Intent for Billing Profile", "description": "Creates a Stripe payment intent for adding or updating a payment method on the account's billing profile. Returns a client secret for frontend payment method collection.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "responses": { "200": { "description": "Create Payment Intent response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_payment_intent_response_single" } } } }, "4XX": { "description": "Create Payment Intent response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Billing" ], "x-api-token-group": [ "Billing Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "billing.profiles", "x-fern-sdk-method-name": "createPaymentIntent" } }, "/accounts/{account_id}/billing/unpaid-invoice": { "get": { "operationId": "account-billing-get-unpaid-invoices", "summary": "Get Unpaid Invoices", "description": "Gets unpaid invoice information for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "responses": { "200": { "description": "Get Unpaid Invoices response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_unpaid_invoices_response_single" } } } }, "4XX": { "description": "Get Unpaid Invoices response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Billing" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "accounts.billing", "x-fern-sdk-method-name": "getUnpaidInvoices" } }, "/accounts/{account_id}/billing/usage": { "get": { "operationId": "usage-analytics-get-account-billing-usage", "summary": "Get account billing usage", "description": "Retrieve billing usage analytics for an account. Returns time-series data for all billable product metrics including Stream, Media (Images), Rate Limiting, Load Balancing, Argo, Workers, Workers KV, Image Resizing, and Spectrum.\n", "parameters": [ { "$ref": "#/components/parameters/usage-analytics_account_id" }, { "$ref": "#/components/parameters/usage-analytics_metrics" }, { "$ref": "#/components/parameters/usage-analytics_since" }, { "$ref": "#/components/parameters/usage-analytics_until" }, { "$ref": "#/components/parameters/usage-analytics_time_delta" }, { "$ref": "#/components/parameters/usage-analytics_limit" }, { "$ref": "#/components/parameters/usage-analytics_filters" } ], "responses": { "200": { "description": "Usage analytics response.", "content": { "application/json": { "examples": { "success": { "summary": "Successful billing usage retrieval", "value": { "errors": [], "messages": [], "result": [ { "argoAcceleratedBytes": 5000000, "imageResizingRequests": 15000, "loadBalancingQueries": 10000, "mediaUniqueTransformations": 45000, "rateLimitingRequestsAllowed": 50000, "spectrumBytesTransferred": 8000000, "streamMinutesViewed": 125000, "ts": 1693526400, "workersKVReads": 30000, "workersRequests": 200000 } ], "success": true } } }, "schema": { "$ref": "#/components/schemas/usage-analytics_billing_usage_response" } } } }, "400": { "$ref": "#/components/responses/usage-analytics_bad_request" }, "401": { "$ref": "#/components/responses/usage-analytics_unauthorized" }, "403": { "$ref": "#/components/responses/usage-analytics_forbidden" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Usage Analytics" ], "x-api-token-group": [ "Billing Read" ], "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "billing.usage", "x-fern-sdk-method-name": "get" } }, "/accounts/{account_id}/botnet_feed/asn/{asn_id}/day_report": { "get": { "operationId": "botnet-threat-feed-get-day-report", "summary": "Get daily report", "description": "Gets all the data the botnet tracking database has for a given ASN registered to user account for given date. If no date is given, it will return results for the previous day.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dos_identifier" } }, { "name": "asn_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dos_asn" } }, { "name": "date", "in": "query", "schema": { "$ref": "#/components/schemas/dos_timestamp" } } ], "responses": { "200": { "description": "Get botnet feed report for day", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dos_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "cidr": { "type": "string", "example": "1.1.1.1/32" }, "date": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z" }, "offense_count": { "type": "integer", "example": 1000 } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Get botnet feed report for day response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dos_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Botnet Threat Feed" ], "x-api-token-group": [ "DDoS Botnet Feed Write", "DDoS Botnet Feed Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "botnet-feed.asn", "x-fern-sdk-method-name": "day-report", "x-forge-hidden": true } }, "/accounts/{account_id}/botnet_feed/asn/{asn_id}/full_report": { "get": { "operationId": "botnet-threat-feed-get-full-report", "summary": "Get full report", "description": "Gets all the data the botnet threat feed tracking database has for a given ASN registered to user account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dos_identifier" } }, { "name": "asn_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dos_asn" } } ], "responses": { "200": { "description": "Get full botnet feed report", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dos_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "cidr": { "type": "string", "example": "1.1.1.1/32" }, "date": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z" }, "offense_count": { "type": "integer", "example": 1000 } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Get full botnet feed report response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dos_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Botnet Threat Feed" ], "x-api-token-group": [ "DDoS Botnet Feed Write", "DDoS Botnet Feed Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "botnet-feed.asn", "x-fern-sdk-method-name": "full-report", "x-forge-hidden": true } }, "/accounts/{account_id}/botnet_feed/configs/asn": { "get": { "operationId": "botnet-threat-feed-list-asn", "summary": "Get list of ASNs", "description": "Gets a list of all ASNs registered for a user for the DDoS Botnet Feed API.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dos_identifier" } } ], "responses": { "200": { "description": "Get list of ASNs response", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dos_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "asn": { "type": "integer", "example": 13335 } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Get list of ASNs response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dos_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Botnet Threat Feed" ], "x-api-token-group": [ "DDoS Botnet Feed Write", "DDoS Botnet Feed Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "botnet-feed.configs.asn", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/botnet_feed/configs/asn/{asn_id}": { "delete": { "operationId": "botnet-threat-feed-delete-asn", "summary": "Delete an ASN", "description": "Delete an ASN from botnet threat feed for a given user.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dos_identifier" } }, { "name": "asn_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dos_asn" } } ], "responses": { "200": { "description": "Delete ASN response", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dos_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "asn": { "type": "integer", "example": 13335 } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Delete ASN response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dos_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Botnet Threat Feed" ], "x-api-token-group": [ "DDoS Botnet Feed Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "botnet-feed.configs.asn", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/alerts": { "get": { "operationId": "getAccountsAccountIdBrandProtectionAlerts", "summary": "Read all alerts on submitted domains", "description": "Return all alerts on submitted domains", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerts", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "patch": { "operationId": "patchAccountsAccountIdBrandProtectionAlerts", "summary": "Update alerts on submitted domains by ID", "description": "Return a success message after updating alerts on submitted domains by ID", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerts", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/alerts/clear": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "patch": { "operationId": "patchAccountsAccountIdBrandProtectionAlertsClear", "summary": "Update verification statuses of tracked URLs to awaiting by ID", "description": "Return a success message after updating verification statuses of tracked URLs to awaiting by ID", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerts.clear", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/alerts/refute": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "patch": { "operationId": "patchAccountsAccountIdBrandProtectionAlertsRefute", "summary": "Update verification statuses of tracked URLs to disproven by ID", "description": "Return a success message after updating verification statuses of tracked URLs to disproven by ID", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerts.refute", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/alerts/verify": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "patch": { "operationId": "patchAccountsAccountIdBrandProtectionAlertsVerify", "summary": "Update verification statuses of tracked URLs to confirmed by ID", "description": "Return a success message after updating verification statuses of tracked URLs to confirmed by ID", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "alerts.verify", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/brands": { "delete": { "operationId": "deleteAccountsAccountIdBrandProtectionBrands", "summary": "Delete brands by ID", "description": "Return a success message after deleting brands by ID", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "brands", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "getAccountsAccountIdBrandProtectionBrands", "summary": "Read all brands", "description": "Return all brands", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "brands", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "post": { "operationId": "postAccountsAccountIdBrandProtectionBrands", "summary": "Create new brands", "description": "Return new brands", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "brands", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/brands/patterns": { "delete": { "operationId": "deleteAccountsAccountIdBrandProtectionBrandsPatterns", "summary": "Delete patterns for brands by ID", "description": "Return a success message after deleting patterns for brands by ID", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "brands.patterns", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "getAccountsAccountIdBrandProtectionBrandsPatterns", "summary": "Read patterns for brands by ID", "description": "Return patterns for brands based on ID", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "brands.patterns", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "post": { "operationId": "postAccountsAccountIdBrandProtectionBrandsPatterns", "summary": "Create new patterns for brands by ID", "description": "Return a success message after creating new patterns for brands by ID", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "brands.patterns", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/clear": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "patch": { "operationId": "patchAccountsAccountIdBrandProtectionClear", "summary": "Update verification statuses of submitted URLs to awaiting by ID", "description": "Return a success message after updating verification statuses of submitted URLs to awaiting by ID", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "clear", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/domain-info": { "get": { "operationId": "getAccountsAccountIdBrandProtectionDomainInfo", "summary": "Read submitted domains by ID", "description": "Return submitted domains based on ID", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "domain-info", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/accounts/{account_id}/brand-protection/logo-matches": { "get": { "operationId": "getAccountsAccountIdBrandProtectionLogoMatches", "summary": "Read matches for logo queries by ID", "description": "Return matches for logo queries based on ID", "parameters": [ { "name": "logo_id", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true, "style": "form" }, { "name": "offset", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_LogoMatch" } } } }, "422": { "$ref": "#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT" }, "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "logo_match" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logo-matches", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/accounts/{account_id}/brand-protection/logo-matches/download": { "get": { "operationId": "getAccountsAccountIdBrandProtectionLogoMatchesDownload", "summary": "Download matches for logo queries by ID", "description": "Return matches as CSV for logo queries based on ID", "parameters": [ { "name": "logo_id", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true, "style": "form" }, { "name": "offset", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_LogoMatch" } } } }, "422": { "$ref": "#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT" }, "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "logo_match" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logo-matches.download", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/accounts/{account_id}/brand-protection/logos": { "get": { "operationId": "getAccountsAccountIdBrandProtectionLogos", "summary": "Read all saved logo queries", "description": "Return all saved logo queries", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "logo_match" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logos", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "post": { "operationId": "postAccountsAccountIdBrandProtectionLogos", "summary": "Create new saved logo queries from image files", "description": "Return new saved logo queries created from image files", "parameters": [ { "name": "tag", "in": "query", "schema": { "type": "string" } }, { "name": "match_type", "in": "query", "schema": { "type": "string" } }, { "name": "threshold", "in": "query", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/brand-protection-api_ImageFile" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Logo" } } } }, "422": { "$ref": "#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT" }, "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "logo_match" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logos", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/logos/{logo_id}": { "delete": { "operationId": "deleteAccountsAccountIdBrandProtectionLogosLogoId", "summary": "Delete saved logo queries by ID", "description": "Return a success message after deleting saved logo queries by ID", "responses": { "204": { "description": "No Content" }, "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "logo_match" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logos", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "getAccountsAccountIdBrandProtectionLogosLogoId", "summary": "Read saved logo queries by ID", "description": "Return saved logo queries based on ID", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "logo_match" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logos", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "logo_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/accounts/{account_id}/brand-protection/matches": { "get": { "operationId": "getAccountsAccountIdBrandProtectionMatches", "summary": "Read matches for string queries by ID", "description": "Return matches for string queries based on ID", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "include_domain_id", "in": "query", "schema": { "type": "boolean" } }, { "name": "include_dismissed", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_QueryMatch" } } } }, "422": { "$ref": "#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT" }, "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "matches", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/accounts/{account_id}/brand-protection/matches/download": { "get": { "operationId": "getAccountsAccountIdBrandProtectionMatchesDownload", "summary": "Download matches for string queries by ID", "description": "Return matches as CSV for string queries based on ID", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "include_domain_id", "in": "query", "schema": { "type": "boolean" } }, { "name": "include_dismissed", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_QueryMatch" } } } }, "422": { "$ref": "#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT" }, "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "matches.download", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/accounts/{account_id}/brand-protection/queries": { "delete": { "operationId": "deleteAccountsAccountIdBrandProtectionQueries", "summary": "Delete saved string queries by ID", "description": "Return a success message after deleting saved string queries by ID", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "schema": { "type": "string" } }, { "name": "scan", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "204": { "description": "No Content" }, "422": { "$ref": "#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT" }, "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "queries", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "getAccountsAccountIdBrandProtectionQueries", "summary": "Read string queries by ID", "description": "Return string queries based on ID", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "queries", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "patch": { "operationId": "patchAccountsAccountIdBrandProtectionQueries", "summary": "Update saved string queries by ID", "description": "Update a saved query's tag, scan setting, or string_matches (pattern). When string_matches is provided, the query parameters and hash are updated. At least one of tag, scan, or string_matches is required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The query ID to update (required when updating tag or scan)", "type": "integer" }, "scan": { "description": "Whether to scan matches", "type": "boolean" }, "string_matches": { "description": "Updated pattern match constraints. When provided, replaces the existing string_matches.", "type": "array", "items": { "properties": { "max_edit_distance": { "description": "Maximum Levenshtein edit distance for fuzzy matching", "type": "number" }, "pattern": { "description": "The pattern to match against", "type": "string" } }, "required": [ "pattern" ], "type": "object" } }, "tag": { "description": "Query tag. Required as identifier when updating string_matches.", "type": "string" } } } } } }, "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "queries", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "post": { "operationId": "postAccountsAccountIdBrandProtectionQueries", "summary": "Create new saved string queries", "description": "Return a success message after creating new saved string queries", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "schema": { "type": "string" } }, { "name": "scan", "in": "query", "schema": { "type": "boolean" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Query" } } } }, "responses": { "204": { "description": "No Content" }, "422": { "$ref": "#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT" }, "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "queries", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/queries/bulk": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "post": { "operationId": "postAccountsAccountIdBrandProtectionQueriesBulk", "summary": "Create new saved string queries in bulk", "description": "Return a success message after creating new saved string queries in bulk", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_QueryBulk" } } } }, "responses": { "204": { "description": "No Content" }, "422": { "$ref": "#/components/responses/brand-protection-api_UNPROCESSABLE_CONTENT" }, "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "queries.bulk", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/queries/{query_id}/matches/{domain_id}/dismiss": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "query_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "post": { "operationId": "postAccountsAccountIdBrandProtectionQueriesQueryIdMatchesDomainIdDismiss", "summary": "Dismiss a match for a saved string query", "description": "Hide a matched domain from the default view of a saved query's results. Dismissal is scoped to the calling account.", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "queries.matches", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/queries/{query_id}/matches/{domain_id}/undismiss": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "query_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "post": { "operationId": "postAccountsAccountIdBrandProtectionQueriesQueryIdMatchesDomainIdUndismiss", "summary": "Undismiss a match for a saved string query", "description": "Restore a previously dismissed matched domain to the default view. Dismissal is scoped to the calling account.", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "queries.matches", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/recent-submissions": { "get": { "operationId": "getAccountsAccountIdBrandProtectionRecentSubmissions", "summary": "Read recent URL submissions", "description": "Return recent URL submissions", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "recent-submissions", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/accounts/{account_id}/brand-protection/refute": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "patch": { "operationId": "patchAccountsAccountIdBrandProtectionRefute", "summary": "Update verification statuses of submitted URLs to disproven by ID", "description": "Return a success message after updating verification statuses of submitted URLs to disproven by ID", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "refute", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/scan-logo": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "post": { "operationId": "postAccountsAccountIdBrandProtectionScanLogo", "summary": "Create new logo queries from image files", "description": "Return new logo queries created from image files", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "logo_match" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "scan-logo", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/scan-page": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "post": { "operationId": "postAccountsAccountIdBrandProtectionScanPage", "summary": "Create new logo queries from URLs", "description": "Return new logo queries created from URLs", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "logo_match" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "scan-page", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/search": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "post": { "operationId": "postAccountsAccountIdBrandProtectionSearch", "summary": "Create new string queries", "description": "Return new string queries", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "search", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/submission-info": { "get": { "operationId": "getAccountsAccountIdBrandProtectionSubmissionInfo", "summary": "Read URL submissions by ID", "description": "Return URL submissions based on ID", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "submission-info", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/accounts/{account_id}/brand-protection/submit": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "post": { "operationId": "postAccountsAccountIdBrandProtectionSubmit", "summary": "Create new URL submissions", "description": "Return new URL submissions", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_URLSubmit" } } } }, "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "submit", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/brand-protection/total-queries": { "get": { "operationId": "getAccountsAccountIdBrandProtectionTotalQueries", "summary": "Read the total number of saved string queries", "description": "Return the total number of saved string queries", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "domain_search" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "total-queries", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/accounts/{account_id}/brand-protection/tracked-domains": { "get": { "operationId": "getAccountsAccountIdBrandProtectionTrackedDomains", "summary": "Read submitted domains by pattern", "description": "Return submitted domains based on pattern", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "tracked-domains", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/accounts/{account_id}/brand-protection/url-info": { "get": { "operationId": "getAccountsAccountIdBrandProtectionUrlInfo", "summary": "Read submitted URLs by ID", "description": "Return submitted URLs based on ID", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_URLInfo" } } } }, "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "url-info", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/accounts/{account_id}/brand-protection/verify": { "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "patch": { "operationId": "patchAccountsAccountIdBrandProtectionVerify", "summary": "Update verification statuses of submitted URLs to confirmed by ID", "description": "Return a success message after updating verification statuses of submitted URLs to confirmed by ID", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "verify", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/browser-extension/config": { "delete": { "operationId": "accounts-browser-extension-config-delete", "summary": "Delete browser extension configuration", "description": "Deletes the browser extension configuration for an account.\nThe shard mapping is preserved and not deleted.\n", "responses": { "200": { "description": "Browser extension configuration deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_DeleteResponse" } } } }, "400": { "$ref": "#/components/responses/brex_BadRequest" }, "401": { "$ref": "#/components/responses/brex_Unauthorized" }, "403": { "$ref": "#/components/responses/brex_Forbidden" }, "404": { "$ref": "#/components/responses/brex_NotFound" }, "500": { "$ref": "#/components/responses/brex_InternalServerError" } }, "security": [ { "api_token": [] } ], "tags": [ "Browser Extension Config" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "browser-extension.config", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "accounts-browser-extension-config-get", "summary": "Get browser extension configuration", "description": "Returns the browser extension configuration for an account.\n", "responses": { "200": { "description": "Browser extension configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_ConfigResponse" } } } }, "401": { "$ref": "#/components/responses/brex_Unauthorized" }, "403": { "$ref": "#/components/responses/brex_Forbidden" }, "404": { "$ref": "#/components/responses/brex_NotFound" }, "500": { "$ref": "#/components/responses/brex_InternalServerError" } }, "security": [ { "api_token": [] } ], "tags": [ "Browser Extension Config" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "browser-extension.config", "x-fern-sdk-method-name": "get", "x-stability": "beta" }, "parameters": [ { "$ref": "#/components/parameters/brex_AccountId" } ], "post": { "operationId": "accounts-browser-extension-config-post", "summary": "Create browser extension configuration", "description": "Creates the browser extension configuration for an account.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_CreateConfigRequest" } } } }, "responses": { "200": { "description": "Browser extension configuration created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_ConfigResponse" } } } }, "400": { "$ref": "#/components/responses/brex_BadRequest" }, "401": { "$ref": "#/components/responses/brex_Unauthorized" }, "403": { "$ref": "#/components/responses/brex_Forbidden" }, "409": { "$ref": "#/components/responses/brex_Conflict" }, "500": { "$ref": "#/components/responses/brex_InternalServerError" } }, "security": [ { "api_token": [] } ], "tags": [ "Browser Extension Config" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "browser-extension.config", "x-fern-sdk-method-name": "create", "x-stability": "beta" }, "put": { "operationId": "accounts-browser-extension-config-put", "summary": "Update browser extension configuration", "description": "Replaces the browser extension configuration for an account.\nThe configuration must already exist. The shard mapping is immutable.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_UpdateConfigRequest" } } } }, "responses": { "200": { "description": "Browser extension configuration updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_ConfigResponse" } } } }, "400": { "$ref": "#/components/responses/brex_BadRequest" }, "401": { "$ref": "#/components/responses/brex_Unauthorized" }, "403": { "$ref": "#/components/responses/brex_Forbidden" }, "404": { "$ref": "#/components/responses/brex_NotFound" }, "500": { "$ref": "#/components/responses/brex_InternalServerError" } }, "security": [ { "api_token": [] } ], "tags": [ "Browser Extension Config" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "browser-extension.config", "x-fern-sdk-method-name": "update", "x-stability": "beta" } }, "/accounts/{account_id}/browser-extension/config/inventories": { "get": { "operationId": "accounts-browser-extension-inventories-list", "summary": "List browser extension inventories", "description": "Returns the installed extension inventory for each registered browser\nextension device in the account. Each device reports its inventory\nperiodically; this endpoint returns the latest known snapshot per device.\n\nResults are paginated by cursor. Pass the `cursor` from a previous\nresponse to fetch the next page. `per_page` controls page size\n(default 50, max 200).\n", "parameters": [ { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response to fetch the next page.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Number of results per page (default 50, max 200).", "schema": { "type": "integer", "default": 50, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "Browser extension inventories response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_InventoriesResponse" } } } }, "401": { "$ref": "#/components/responses/brex_Unauthorized" }, "403": { "$ref": "#/components/responses/brex_Forbidden" }, "500": { "$ref": "#/components/responses/brex_InternalServerError" } }, "security": [ { "api_token": [] } ], "tags": [ "Browser Extension Inventories" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "browser-extension.inventories", "x-fern-sdk-method-name": "list" }, "parameters": [ { "$ref": "#/components/parameters/brex_AccountId" } ] }, "/accounts/{account_id}/browser-extension/config/inventories/{registration_id}": { "get": { "operationId": "accounts-browser-extension-inventories-get", "summary": "Get a single browser extension inventory", "description": "Returns the installed extension inventory for a single registered browser\nextension device.\n", "responses": { "200": { "description": "Browser extension inventory response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_InventoryResponse" } } } }, "401": { "$ref": "#/components/responses/brex_Unauthorized" }, "403": { "$ref": "#/components/responses/brex_Forbidden" }, "404": { "$ref": "#/components/responses/brex_NotFound" }, "500": { "$ref": "#/components/responses/brex_InternalServerError" } }, "security": [ { "api_token": [] } ], "tags": [ "Browser Extension Inventories" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "browser-extension.inventories", "x-fern-sdk-method-name": "get" }, "parameters": [ { "$ref": "#/components/parameters/brex_AccountId" }, { "name": "registration_id", "in": "path", "description": "Browser extension registration ID.", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/accounts/{account_id}/browser-rendering/accessibilityTree": { "post": { "operationId": "brapi-post_AccessibilityTree", "summary": "Get accessibility tree page", "description": "Returns the page's accessibility tree. Use `interestingOnly` to only return semantically meaningful nodes; use `root` to scope the tree to a CSS-selector-anchored subtree. Control page loading with `gotoOptions` and `waitFor*` options.", "parameters": [ { "name": "account_id", "in": "path", "description": "Account ID.", "required": true, "schema": { "description": "Account ID.", "type": "string" } }, { "name": "cacheTTL", "in": "query", "description": "Cache TTL default is 5s. Set to 0 to disable.", "schema": { "description": "Cache TTL default is 5s. Set to 0 to disable.", "type": "number", "default": 5, "maximum": 86400, "minimum": 0 } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "example1": { "value": { "url": "https://www.example.com/" } } }, "schema": { "type": "object", "properties": { "actionTimeout": { "description": "The maximum duration allowed for the browser action to complete after the page has loaded (such as taking screenshots, extracting content, or generating PDFs). If this time limit is exceeded, the action stops and returns a timeout error.", "type": "number", "maximum": 120000 }, "addScriptTag": { "description": "Adds a `" } } } }, "4XX": { "description": "Retrieve embed Code HTML response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/stream_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Stream Videos" ], "x-api-token-group": [ "Stream Write", "Stream Read" ], "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "stream.videos", "x-fern-sdk-method-name": "embed", "x-forge-hidden": true } }, "/accounts/{account_id}/stream/{identifier}/token": { "post": { "operationId": "stream-videos-create-signed-url-tokens-for-videos", "summary": "Create signed URL tokens for videos", "description": "Creates a signed URL token for a video. If a body is not provided in the request, a token is created with default values.", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/stream_identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/stream_account_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/stream_signed_token_request" } } } }, "responses": { "200": { "description": "Create signed URL tokens for videos response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/stream_signed_token_response" } } } }, "4XX": { "description": "Create signed URL tokens for videos response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/stream_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Stream Videos" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "stream.videos.token", "x-fern-sdk-method-name": "create", "x-forge-require-confirmation": "Provision temporary token? For use at scale, consider creating a signing key instead." } }, "/accounts/{account_id}/subscriptions": { "get": { "operationId": "account-subscriptions-list-subscriptions", "summary": "List Subscriptions", "description": "Lists all of an account's subscriptions.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "responses": { "200": { "description": "List Subscriptions response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_account_subscription_response_collection" } } } }, "4XX": { "description": "List Subscriptions response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Subscriptions" ], "x-api-token-group": [ "Billing Write", "Billing Read" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts.subscriptions", "x-fern-sdk-method-name": "get" }, "post": { "operationId": "account-subscriptions-create-subscription", "summary": "Create Subscription", "description": "Creates an account subscription.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_subscription-v2" } } } }, "responses": { "200": { "description": "Create Subscription response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_account_subscription_response_single" } } } }, "4XX": { "description": "Create Subscription response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Subscriptions" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read", "#billing:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts.subscriptions", "x-fern-sdk-method-name": "create" } }, "/accounts/{account_id}/subscriptions/cancel-downgrade": { "post": { "operationId": "account-subscriptions-cancel-delayed-downgrade", "summary": "Cancel Delayed Downgrade", "description": "Cancels pending delayed downgrades for the specified subscriptions.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_ids": { "description": "List of subscription identifiers to cancel downgrades for.", "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Cancel Delayed Downgrade response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-single" } } } }, "204": { "description": "Cancel Delayed Downgrade response (no content)" }, "4XX": { "description": "Cancel Delayed Downgrade response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Subscriptions" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#subscription:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "accounts.subscriptions", "x-fern-sdk-method-name": "cancelDelayedDowngrade" } }, "/accounts/{account_id}/subscriptions/{subscription_identifier}": { "delete": { "operationId": "account-subscriptions-delete-subscription", "summary": "Delete Subscription", "description": "Deletes an account's subscription.", "parameters": [ { "name": "subscription_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_schemas-identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "responses": { "200": { "description": "Delete Subscription response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "subscription_id": { "$ref": "#/components/schemas/bill-subs-api_schemas-identifier" } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Delete Subscription response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Subscriptions" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:edit" ] }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts.subscriptions", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "account-subscriptions-get-subscription", "summary": "Get Subscription", "description": "Gets an account subscription by identifier.", "parameters": [ { "name": "subscription_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_schemas-identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "responses": { "200": { "description": "Get Subscription response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_account_subscription_response_single" } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } }, "4XX": { "description": "Get Subscription response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Subscriptions" ], "x-api-token-group": [ "Billing Write", "Billing Read" ], "x-cfPermissionsRequired": { "enum": [ "#subscription:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "accounts.subscriptions", "x-fern-sdk-method-name": "getByIdentifier" }, "put": { "operationId": "account-subscriptions-update-subscription", "summary": "Update Subscription", "description": "Updates an account subscription.", "parameters": [ { "name": "subscription_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_schemas-identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_subscription-v2" } } } }, "responses": { "200": { "description": "Update Subscription response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_account_subscription_response_single" } } } }, "4XX": { "description": "Update Subscription response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Subscriptions" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read", "#billing:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts.subscriptions", "x-fern-sdk-method-name": "update" } }, "/accounts/{account_id}/subscriptions/{subscription_identifier}/action/append": { "post": { "operationId": "account-subscriptions-action-append-subscription", "summary": "Append Subscription Action", "description": "Smartly applies the incoming subscription into the lifecycle of the subscription.", "parameters": [ { "name": "subscription_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_schemas-identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_subscription-v2" } } } }, "responses": { "200": { "description": "Append Subscription Action response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_account_subscription_response_single" } } } }, "4XX": { "description": "Append Subscription Action response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_account_subscription_response_single" }, { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Subscriptions" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read", "#billing:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "accounts.subscriptions", "x-fern-sdk-method-name": "append", "x-forge-hidden": true } }, "/accounts/{account_id}/subscriptions/{subscription_identifier}/cancel-reason": { "get": { "operationId": "account-subscriptions-get-cancel-reason", "summary": "Get Cancel Reason", "description": "Gets the cancellation reason for an account subscription.", "parameters": [ { "name": "subscription_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_schemas-identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "responses": { "200": { "description": "Get Cancel Reason response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_cancel_reason_response_single" } } } }, "4XX": { "description": "Get Cancel Reason response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Subscriptions" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "accounts.subscriptions", "x-fern-sdk-method-name": "getCancelReason" }, "post": { "operationId": "account-subscriptions-create-cancel-reason", "summary": "Create Cancel Reason", "description": "Records a cancellation reason for an account subscription.", "parameters": [ { "name": "subscription_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_schemas-identifier" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_cancel_reason_request" } } } }, "responses": { "200": { "description": "Create Cancel Reason response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_cancel_reason_response_single" } } } }, "4XX": { "description": "Create Cancel Reason response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Account Subscriptions" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#subscription:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "accounts.subscriptions", "x-fern-sdk-method-name": "createCancelReason" } }, "/accounts/{account_id}/tags": { "delete": { "operationId": "tags-delete", "summary": "Delete tags from an account-level resource", "description": "Removes all tags from a specific account-level resource.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/resource-tagging_account_id" } }, { "$ref": "#/components/parameters/resource-tagging_if_match" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_delete_tags_request_account_level" } } } }, "responses": { "204": { "description": "Tags successfully deleted (no content)." }, "412": { "description": "Precondition failed. The resource has been modified since the provided ETag was obtained.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } }, "4XX": { "description": "Delete tags response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } }, "5XX": { "description": "Delete tags response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Resource Tagging" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "account-tags", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-stability": "beta" }, "get": { "operationId": "tags-get", "summary": "Get tags for an account-level resource", "description": "Retrieves tags for a specific account-level resource.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/resource-tagging_account_id" } }, { "name": "resource_id", "in": "query", "description": "The ID of the resource to retrieve tags for.", "required": true, "schema": { "$ref": "#/components/schemas/resource-tagging_resource_id" } }, { "name": "resource_type", "in": "query", "description": "The type of the resource.", "required": true, "schema": { "$ref": "#/components/schemas/resource-tagging_account_resource_type" } }, { "name": "worker_id", "in": "query", "description": "Worker identifier. Required for worker_version resources.", "schema": { "$ref": "#/components/schemas/resource-tagging_worker_id" } } ], "responses": { "200": { "description": "Get tags for single resource response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_tagged_resource_response_single" } } } }, "4XX": { "description": "Get tags for single resource response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } }, "5XX": { "description": "Get tags for single resource response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Resource Tagging" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "account-tags", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stability": "beta" }, "put": { "operationId": "tags-set", "summary": "Set tags for an account-level resource", "description": "Creates or updates tags for a specific account-level resource.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/resource-tagging_account_id" } }, { "$ref": "#/components/parameters/resource-tagging_if_match" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_set_tags_request_account_level" } } } }, "responses": { "200": { "description": "Set tags response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_tagged_resource_response_single" } } } }, "412": { "description": "Precondition failed. The resource has been modified since the provided ETag was obtained.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } }, "4XX": { "description": "Set tags response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } }, "5XX": { "description": "Set tags response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Resource Tagging" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "account-tags", "x-fern-sdk-method-name": "update", "x-forge-hidden": true, "x-stability": "beta" } }, "/accounts/{account_id}/tags/keys": { "get": { "operationId": "tags-list-keys", "summary": "List tag keys", "description": "Lists all distinct tag keys used across resources in an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/resource-tagging_account_id" } }, { "$ref": "#/components/parameters/resource-tagging_cursor" } ], "responses": { "200": { "description": "List tag keys response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_tag_keys_response_collection" } } } }, "4XX": { "description": "List tag keys response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } }, "5XX": { "description": "List tag keys response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Resource Tagging" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "keys", "x-fern-sdk-method-name": "list", "x-forge-hidden": true, "x-stability": "beta" } }, "/accounts/{account_id}/tags/resources": { "get": { "operationId": "tags-list", "summary": "List tagged resources", "description": "Lists all tagged resources for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/resource-tagging_account_id" } }, { "name": "type", "in": "query", "description": "Filter by resource type. Can be repeated to filter by multiple types (OR logic). Example: ?type=zone&type=worker", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/resource-tagging_resource_type" } }, "explode": true, "style": "form" }, { "name": "name", "in": "query", "description": "Filter by resource name. Performs a case-insensitive substring match. Example: ?name=my-zone", "schema": { "type": "string", "maxLength": 256 } }, { "name": "id", "in": "query", "description": "Filter by resource ID. Can be repeated up to 50 times to filter by multiple IDs. Example: ?id=abc&id=def", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/resource-tagging_resource_id" }, "maxItems": 50 }, "explode": true, "style": "form" }, { "name": "case_insensitive", "in": "query", "description": "Match `tag` keys and values case-insensitively. Stored casing is unchanged. Example: ?tag=environment=production&case_insensitive=true", "schema": { "type": "boolean", "default": false } }, { "$ref": "#/components/parameters/resource-tagging_tag" }, { "$ref": "#/components/parameters/resource-tagging_cursor" } ], "responses": { "200": { "description": "List tagged resources response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_tagged_resource_response_collection" } } } }, "4XX": { "description": "List tagged resources response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } }, "5XX": { "description": "List tagged resources response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Resource Tagging" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "tags.resources", "x-fern-sdk-method-name": "list", "x-forge-hidden": true, "x-stability": "beta" } }, "/accounts/{account_id}/tags/summary": { "get": { "operationId": "tags-list-key-summary", "summary": "List tag key summary", "description": "Lists all distinct tag keys and their distinct values across resources in an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/resource-tagging_account_id" } }, { "$ref": "#/components/parameters/resource-tagging_cursor" } ], "responses": { "200": { "description": "List tag key summary response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_tag_key_summary_response_collection" } } } }, "4XX": { "description": "List tag key summary response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } }, "5XX": { "description": "List tag key summary response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Resource Tagging" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "resource-tagging.summary", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stability": "beta" } }, "/accounts/{account_id}/tags/values/{tag_key}": { "get": { "operationId": "tags-list-values", "summary": "List tag values", "description": "Lists all distinct values for a given tag key, optionally filtered by resource type.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/resource-tagging_account_id" } }, { "name": "tag_key", "in": "path", "description": "The tag key to retrieve values for.", "required": true, "schema": { "type": "string", "example": "environment" } }, { "$ref": "#/components/parameters/resource-tagging_type" }, { "$ref": "#/components/parameters/resource-tagging_cursor" } ], "responses": { "200": { "description": "List tag values response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_tag_values_response_collection" } } } }, "4XX": { "description": "List tag values response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } }, "5XX": { "description": "List tag values response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Resource Tagging" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "values", "x-fern-sdk-method-name": "list", "x-forge-hidden": true, "x-stability": "beta" } }, "/accounts/{account_id}/teamnet/routes": { "get": { "operationId": "tunnel-route-list-tunnel-routes", "summary": "List tunnel routes", "description": "Lists and filters private network routes in an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "comment", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_route_comment" } }, { "name": "is_deleted", "in": "query", "schema": { "description": "If `true`, only include deleted routes. If `false`, exclude deleted routes. If empty, all routes will be included.", "type": "boolean" } }, { "name": "network_subset", "in": "query", "schema": { "description": "If set, only list routes that are contained within this IP range.", "allOf": [ { "$ref": "#/components/schemas/tunnel_ip_network" } ] } }, { "name": "network_superset", "in": "query", "schema": { "description": "If set, only list routes that contain this IP range.", "allOf": [ { "$ref": "#/components/schemas/tunnel_ip_network" } ] } }, { "name": "existed_at", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_existed_at" } }, { "name": "tunnel_id", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_tunnel_id" } }, { "name": "route_id", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_route_id" } }, { "name": "tun_types", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_tunnel_types" } }, { "name": "virtual_network_id", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_virtual_network_id" } }, { "name": "per_page", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_per_page" } }, { "name": "page", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_page_number" } } ], "responses": { "200": { "description": "List tunnel routes response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_teamnet_response_collection" } } } }, "4XX": { "description": "List tunnel routes response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_teamnet_response_collection" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Tunnel Routing" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare One Networks Read", "Cloudflare Tunnel Write", "Cloudflare Tunnel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.routes.cidr", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "tunnel-route-create-a-tunnel-route", "summary": "Create a tunnel route", "description": "Routes a private network through a Cloudflare Tunnel.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/tunnel_route_comment" }, "network": { "$ref": "#/components/schemas/tunnel_ip_network" }, "tunnel_id": { "$ref": "#/components/schemas/tunnel_tunnel_id" }, "virtual_network_id": { "$ref": "#/components/schemas/tunnel_virtual_network_id_computed_optional" } }, "required": [ "network", "tunnel_id" ] } } } }, "responses": { "200": { "description": "Create a tunnel route response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_route_response_single" } } } }, "4XX": { "description": "Create a tunnel route response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_route_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Tunnel Routing" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare Tunnel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.routes.cidr", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/teamnet/routes/ip/{ip}": { "get": { "operationId": "tunnel-route-get-tunnel-route-by-ip", "summary": "Get tunnel route by IP", "description": "Fetches routes that contain the given IP address.", "parameters": [ { "name": "ip", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_ip" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "virtual_network_id", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_virtual_network_id" } }, { "name": "default_virtual_network_fallback", "in": "query", "description": "When the virtual_network_id parameter is not provided the request filter will default search routes that are in the default virtual network for the account. If this parameter is set to false, the search will include routes that do not have a virtual network.", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Get tunnel route by IP response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_teamnet_response_single" } } } }, "4XX": { "description": "Get tunnel route by IP response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_teamnet_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Tunnel Routing" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare One Networks Read", "Cloudflare Tunnel Write", "Cloudflare Tunnel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.routes", "x-fern-sdk-method-name": "resolve", "x-forge-hidden": true } }, "/accounts/{account_id}/teamnet/routes/network/{ip_network_encoded}": { "delete": { "operationId": "tunnel-route-delete-a-tunnel-route-with-cidr", "summary": "Delete a tunnel route (CIDR Endpoint)", "description": "Deletes a private network route from an account. The CIDR in `ip_network_encoded` must be written in URL-encoded format. If no virtual_network_id is provided it will delete the route from the default vnet. If no tun_type is provided it will fetch the type from the tunnel_id or if that is missing it will assume Cloudflare Tunnel as default. If tunnel_id is provided it will delete the route from that tunnel, otherwise it will delete the route based on the vnet and tun_type.\n", "parameters": [ { "name": "ip_network_encoded", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_ip_network_encoded" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "virtual_network_id", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_virtual_network_id" } }, { "name": "tun_type", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_tunnel_type" } }, { "name": "tunnel_id", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_tunnel_id" } } ], "responses": { "200": { "description": "Delete a tunnel route response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_route_response_single" } } } }, "4XX": { "description": "Delete a tunnel route response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_route_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Tunnel Routing" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare Tunnel Write" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "network.routes.cidr", "x-fern-sdk-method-name": "delete", "x-stainless-deprecation-message": "This endpoint and its related APIs are deprecated in favor of the equivalent Tunnel Route (without CIDR) APIs." }, "patch": { "operationId": "tunnel-route-update-a-tunnel-route-with-cidr", "summary": "Update a tunnel route (CIDR Endpoint)", "description": "Updates an existing private network route in an account. The CIDR in `ip_network_encoded` must be written in URL-encoded format.", "parameters": [ { "name": "ip_network_encoded", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_ip_network_encoded" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } } ], "responses": { "200": { "description": "Update a tunnel route response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_route_response_single" } } } }, "4XX": { "description": "Update a tunnel route response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_route_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Tunnel Routing" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare Tunnel Write" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "network.routes.cidr", "x-fern-sdk-method-name": "edit", "x-stainless-deprecation-message": "This endpoint and its related APIs are deprecated in favor of the equivalent Tunnel Route (without CIDR) APIs." }, "post": { "operationId": "tunnel-route-create-a-tunnel-route-with-cidr", "summary": "Create a tunnel route (CIDR Endpoint)", "description": "Routes a private network through a Cloudflare Tunnel. The CIDR in `ip_network_encoded` must be written in URL-encoded format.", "parameters": [ { "name": "ip_network_encoded", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_ip_network_encoded" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/tunnel_route_comment" }, "tunnel_id": { "$ref": "#/components/schemas/tunnel_tunnel_id" }, "virtual_network_id": { "$ref": "#/components/schemas/tunnel_virtual_network_id" } }, "required": [ "tunnel_id" ] } } } }, "responses": { "200": { "description": "Create a tunnel route response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_route_response_single" } } } }, "4XX": { "description": "Create a tunnel route response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_route_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Tunnel Routing" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare Tunnel Write" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "network.routes.cidr", "x-fern-sdk-method-name": "create", "x-stainless-deprecation-message": "This endpoint and its related APIs are deprecated in favor of the equivalent Tunnel Route (without CIDR) APIs." } }, "/accounts/{account_id}/teamnet/routes/{route_id}": { "delete": { "operationId": "tunnel-route-delete-a-tunnel-route", "summary": "Delete a tunnel route", "description": "Deletes a private network route from an account.\n", "parameters": [ { "name": "route_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_route_id" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } } ], "responses": { "200": { "description": "Delete a tunnel route response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_route_response_single" } } } }, "4XX": { "description": "Delete a tunnel route response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_route_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Tunnel Routing" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare Tunnel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.routes.cidr", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation permanently deletes a private network route." }, "get": { "operationId": "tunnel-route-get-tunnel-route", "summary": "Get tunnel route", "description": "Get a private network route in an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "route_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_route_id" } } ], "responses": { "200": { "description": "Get a tunnel route response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_route_response_single" } } } }, "4XX": { "description": "Get a tunnel route response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_route_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Tunnel Routing" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.routes.cidr", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "tunnel-route-update-a-tunnel-route", "summary": "Update a tunnel route", "description": "Updates an existing private network route in an account. The fields that are meant to be updated should be provided in the body of the request.", "parameters": [ { "name": "route_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_route_id" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/tunnel_route_comment" }, "network": { "$ref": "#/components/schemas/tunnel_ip_network" }, "tunnel_id": { "$ref": "#/components/schemas/tunnel_tunnel_id" }, "virtual_network_id": { "$ref": "#/components/schemas/tunnel_virtual_network_id_computed_optional" } } } } } }, "responses": { "200": { "description": "Update a tunnel route response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_route_response_single" } } } }, "4XX": { "description": "Update a tunnel route response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_route_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Tunnel Routing" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare Tunnel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.routes.cidr", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/teamnet/virtual_networks": { "get": { "operationId": "tunnel-virtual-network-list-virtual-networks", "summary": "List virtual networks", "description": "Lists and filters virtual networks in an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "id", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_virtual_network_id" } }, { "name": "name", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_virtual_network_name" } }, { "name": "is_default", "in": "query", "schema": { "description": "If `true`, only include the default virtual network. If `false`, exclude the default virtual network. If empty, all virtual networks will be included.", "type": "boolean" }, "deprecated": true, "x-stainless-deprecation-message": "Use the is_default_network property instead.", "x-stainless-ignore": true }, { "name": "is_default_network", "in": "query", "schema": { "description": "If `true`, only include the default virtual network. If `false`, exclude the default virtual network. If empty, all virtual networks will be included.", "type": "boolean" } }, { "name": "is_deleted", "in": "query", "schema": { "description": "If `true`, only include deleted virtual networks. If `false`, exclude deleted virtual networks. If empty, all virtual networks will be included.", "type": "boolean" } } ], "responses": { "200": { "description": "List virtual networks response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_vnet_response_collection" } } } }, "4XX": { "description": "List virtual networks response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_vnet_response_collection" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Tunnel Virtual Network" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare One Networks Read", "Cloudflare Tunnel Write", "Cloudflare Tunnel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.virtual-networks", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "tunnel-virtual-network-create-a-virtual-network", "summary": "Create a virtual network", "description": "Adds a new virtual network to an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/tunnel_virtual_network_comment" }, "is_default": { "description": "If `true`, this virtual network is the default for the account.", "type": "boolean", "example": true, "deprecated": true, "x-auditable": true, "x-stainless-deprecation-message": "Use the is_default_network property instead.", "x-stainless-ignore": true }, "is_default_network": { "$ref": "#/components/schemas/tunnel_is_default_network_optional" }, "name": { "$ref": "#/components/schemas/tunnel_virtual_network_name" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Create a virtual network response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_vnet_response_single" } } } }, "4XX": { "description": "Create a virtual network response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_vnet_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Tunnel Virtual Network" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare Tunnel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.virtual-networks", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/teamnet/virtual_networks/{virtual_network_id}": { "delete": { "operationId": "tunnel-virtual-network-delete", "summary": "Delete a virtual network", "description": "Deletes an existing virtual network.", "parameters": [ { "name": "virtual_network_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_virtual_network_id" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } } ], "responses": { "200": { "description": "Delete a virtual network response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_vnet_response_single" } } } }, "4XX": { "description": "Delete a virtual network response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_vnet_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Tunnel Virtual Network" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare Tunnel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.virtual-networks", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation permanently deletes a virtual network." }, "get": { "operationId": "tunnel-virtual-network-get", "summary": "Get a virtual network", "description": "Get a virtual network.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "virtual_network_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_virtual_network_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/tunnel_virtual_network_comment" }, "is_default_network": { "$ref": "#/components/schemas/tunnel_is_default_network" }, "name": { "$ref": "#/components/schemas/tunnel_virtual_network_name" } } } } } }, "responses": { "200": { "description": "A virtual network response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_vnet_response_single" } } } }, "4XX": { "description": "A virtual network response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_vnet_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Tunnel Virtual Network" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.virtual-networks", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "tunnel-virtual-network-update", "summary": "Update a virtual network", "description": "Updates an existing virtual network.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "virtual_network_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_virtual_network_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/tunnel_virtual_network_comment" }, "is_default_network": { "$ref": "#/components/schemas/tunnel_is_default_network_optional" }, "name": { "$ref": "#/components/schemas/tunnel_virtual_network_name" } } } } } }, "responses": { "200": { "description": "Update a virtual network response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_vnet_response_single" } } } }, "4XX": { "description": "Update a virtual network response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_vnet_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Tunnel Virtual Network" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare Tunnel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.virtual-networks", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/tokens": { "get": { "operationId": "account-api-tokens-list-tokens", "summary": "List Tokens", "description": "List all Account Owned API tokens created for this account. Results include active, disabled, and recently-expired tokens when include_expired is set to true.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_account_identifier" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Maximum number of results per page.", "type": "number", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "direction", "in": "query", "schema": { "description": "Direction to order results.", "type": "string", "example": "desc", "enum": [ "asc", "desc" ] } }, { "$ref": "#/components/parameters/iam_include_expired" } ], "responses": { "200": { "description": "List Tokens response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_collection_tokens_response" } } } }, "4XX": { "description": "List Tokens response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Account Owned API Tokens" ], "x-api-token-group": [ "Account API Tokens Write", "Account API Tokens Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.token.list" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts.tokens", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "account-api-tokens-create-token", "summary": "Create Token", "description": "Create a new Account Owned API token.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_account_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_create_payload" } } } }, "responses": { "200": { "description": "Create Token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_single_token_create_response" } } } }, "4XX": { "description": "Create Token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Account Owned API Tokens" ], "x-api-token-group": [ "Account API Tokens Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.token.create" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts.tokens", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/tokens/permission_groups": { "get": { "operationId": "account-api-tokens-list-permission-groups", "summary": "List Permission Groups", "description": "Find all available permission groups for Account Owned API Tokens", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_account_identifier" } }, { "name": "name", "in": "query", "description": "Filter by the name of the permission group.\nThe value must be URL-encoded.", "schema": { "type": "string", "example": "Account%20Settings%20Write" } }, { "name": "scope", "in": "query", "description": "Filter by the scope of the permission group.\nThe value must be URL-encoded.", "schema": { "type": "string", "example": "com.cloudflare.api.account.zone" } } ], "responses": { "200": { "description": "List Account Owned API Token Permission Groups response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_permissions_group_response_collection" } } } }, "4XX": { "description": "List Account Owned API Token Permission Groups response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Account Owned API Tokens" ], "x-api-token-group": [ "Account API Tokens Write", "Account API Tokens Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.token.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts.tokens.permission-groups", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/tokens/verify": { "get": { "operationId": "account-api-tokens-verify-token", "summary": "Verify Token", "description": "Test whether a token works.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_account_identifier" } } ], "responses": { "200": { "description": "Verify Token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_token_verify_response_single_segment" } } } }, "4XX": { "description": "Verify Token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Account Owned API Tokens" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts.tokens", "x-fern-sdk-method-name": "verify", "x-forge-hidden": true } }, "/accounts/{account_id}/tokens/{token_id}": { "delete": { "operationId": "account-api-tokens-delete-token", "summary": "Delete Token", "description": "Destroy an Account Owned API token.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_account_identifier" } }, { "name": "token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_token_identifier" } } ], "responses": { "200": { "description": "Delete Token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-single-id" } } } }, "4XX": { "description": "Delete Token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Account Owned API Tokens" ], "x-api-token-group": [ "Account API Tokens Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.token.delete" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts.tokens", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "Are you sure? This action cannot be undone." }, "get": { "operationId": "account-api-tokens-token-details", "summary": "Token Details", "description": "Get information about a specific Account Owned API token.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_account_identifier" } }, { "name": "token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_token_identifier" } } ], "responses": { "200": { "description": "Token Details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_single_token_response" } } } }, "4XX": { "description": "Token Details response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Account Owned API Tokens" ], "x-api-token-group": [ "Account API Tokens Write", "Account API Tokens Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.token.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts.tokens", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "account-api-tokens-update-token", "summary": "Update Token", "description": "Update an existing token.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_account_identifier" } }, { "name": "token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_token_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_token_body" } } } }, "responses": { "200": { "description": "Update Token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_single_token_response" } } } }, "4XX": { "description": "Update Token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Account Owned API Tokens" ], "x-api-token-group": [ "Account API Tokens Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.token.update" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts.tokens", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/tokens/{token_id}/value": { "put": { "operationId": "account-api-tokens-roll-token", "summary": "Roll Token", "description": "Roll the Account Owned API token secret.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_account_identifier" } }, { "name": "token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_token_identifier" } } ], "responses": { "200": { "description": "Roll Token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_response_single_value" } } } }, "4XX": { "description": "Roll Token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "Account Owned API Tokens" ], "x-api-token-group": [ "Account API Tokens Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.token.update" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "accounts.tokens", "x-fern-sdk-method-name": "roll", "x-forge-hidden": true, "x-forge-require-confirmation": "Rolling this token will invalidate the current secret and generate a new one. Any integrations using the current secret will stop working." } }, "/accounts/{account_id}/triggers/{script_name}": { "delete": { "operationId": "wor-delete-script-triggers", "summary": "Delete script triggers", "description": "Deletes all event trigger declarations owned by a Worker script.", "parameters": [ { "name": "script_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255, "minLength": 1 } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Number of deleted trigger declarations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "deleted": { "type": "integer", "maximum": 9007199254740991, "minimum": 0 } }, "required": [ "deleted" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Invalid trigger configuration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Target workflow not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "workflows.triggers", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "wor-get-script-triggers", "summary": "Get script triggers", "description": "Returns the event trigger declarations owned by a Worker script.", "parameters": [ { "name": "script_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255, "minLength": 1 } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Script trigger declarations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "script_name": { "type": "string" }, "triggers": { "type": "array", "items": { "properties": { "filter": { "type": "object", "default": {}, "additionalProperties": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "targets": { "type": "array", "items": { "properties": { "script_name": { "type": "string", "maxLength": 255, "minLength": 1 }, "type": { "type": "string", "enum": [ "workflow" ] }, "workflow_name": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "type", "script_name", "workflow_name" ], "type": "object" }, "maxItems": 100, "minItems": 1 }, "type": { "type": "string", "minLength": 1 } }, "required": [ "type", "targets" ], "type": "object" }, "maxItems": 100 } }, "required": [ "script_name", "triggers" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Invalid trigger configuration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Target workflow not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "workflows.triggers", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "wor-add-script-triggers", "summary": "Add script triggers", "description": "Adds event trigger declarations without removing existing declarations owned by the script.", "parameters": [ { "name": "script_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255, "minLength": 1 } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "filter": { "type": "object", "default": {}, "additionalProperties": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "targets": { "type": "array", "items": { "properties": { "script_name": { "type": "string", "maxLength": 255, "minLength": 1 }, "type": { "type": "string", "enum": [ "workflow" ] }, "workflow_name": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "type", "script_name", "workflow_name" ], "type": "object" }, "maxItems": 100, "minItems": 1 }, "type": { "type": "string", "minLength": 1 } }, "required": [ "type", "targets" ], "type": "object" }, "maxItems": 100 } } } }, "responses": { "200": { "description": "Effective script trigger declarations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "script_name": { "type": "string" }, "triggers": { "type": "array", "items": { "properties": { "filter": { "type": "object", "default": {}, "additionalProperties": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "targets": { "type": "array", "items": { "properties": { "script_name": { "type": "string", "maxLength": 255, "minLength": 1 }, "type": { "type": "string", "enum": [ "workflow" ] }, "workflow_name": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "type", "script_name", "workflow_name" ], "type": "object" }, "maxItems": 100, "minItems": 1 }, "type": { "type": "string", "minLength": 1 } }, "required": [ "type", "targets" ], "type": "object" }, "maxItems": 100 } }, "required": [ "script_name", "triggers" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Invalid trigger configuration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Target workflow not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "workflows.triggers", "x-fern-sdk-method-name": "add" }, "put": { "operationId": "wor-replace-script-triggers", "summary": "Replace script triggers", "description": "Replaces all event trigger declarations owned by a Worker script.", "parameters": [ { "name": "script_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 255, "minLength": 1 } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "filter": { "type": "object", "default": {}, "additionalProperties": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "targets": { "type": "array", "items": { "properties": { "script_name": { "type": "string", "maxLength": 255, "minLength": 1 }, "type": { "type": "string", "enum": [ "workflow" ] }, "workflow_name": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "type", "script_name", "workflow_name" ], "type": "object" }, "maxItems": 100, "minItems": 1 }, "type": { "type": "string", "minLength": 1 } }, "required": [ "type", "targets" ], "type": "object" }, "maxItems": 100 } } } }, "responses": { "200": { "description": "Effective script trigger declarations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "script_name": { "type": "string" }, "triggers": { "type": "array", "items": { "properties": { "filter": { "type": "object", "default": {}, "additionalProperties": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "targets": { "type": "array", "items": { "properties": { "script_name": { "type": "string", "maxLength": 255, "minLength": 1 }, "type": { "type": "string", "enum": [ "workflow" ] }, "workflow_name": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "type", "script_name", "workflow_name" ], "type": "object" }, "maxItems": 100, "minItems": 1 }, "type": { "type": "string", "minLength": 1 } }, "required": [ "type", "targets" ], "type": "object" }, "maxItems": 100 } }, "required": [ "script_name", "triggers" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Invalid trigger configuration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Target workflow not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "workflows.triggers", "x-fern-sdk-method-name": "replace" } }, "/accounts/{account_id}/tunnels": { "get": { "operationId": "cloudflare-tunnel-list-all-tunnels", "summary": "List All Tunnels", "description": "Lists and filters all types of Tunnels in an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "name", "in": "query", "schema": { "description": "A user-friendly name for the tunnel.", "type": "string", "example": "blog" } }, { "name": "is_deleted", "in": "query", "schema": { "description": "If `true`, only include deleted tunnels. If `false`, exclude deleted tunnels. If empty, all tunnels will be included.", "type": "boolean", "example": true } }, { "name": "existed_at", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_existed_at" } }, { "name": "uuid", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_tunnel_id" } }, { "name": "was_active_at", "in": "query", "schema": { "type": "string", "format": "date-time", "example": "2009-11-10T23:00:00Z" } }, { "name": "was_inactive_at", "in": "query", "schema": { "type": "string", "format": "date-time", "example": "2009-11-10T23:00:00Z" } }, { "name": "include_prefix", "in": "query", "schema": { "type": "string", "example": "vpc1-" } }, { "name": "exclude_prefix", "in": "query", "schema": { "type": "string", "example": "vpc1-" } }, { "name": "tun_types", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_tunnel_types" } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_status" } }, { "name": "per_page", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_per_page" } }, { "name": "page", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_page_number" } } ], "responses": { "200": { "description": "List Tunnels response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_tunnel-response-collection" } } } }, "4XX": { "description": "List Tunnels response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_tunnel-response-collection" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Cloudflare Tunnel" ], "x-api-token-group": [ "Cloudflare One Connectors Write", "Cloudflare One Connectors Read", "Cloudflare One Connector: cloudflared Write", "Cloudflare One Connector: cloudflared Read", "Cloudflare Tunnel Write", "Cloudflare Tunnel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "tunnels", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/urlscanner/response/{response_id}": { "get": { "operationId": "urlscanner-get-response-text", "summary": "Get raw response", "description": "Returns the plain response of the network request.", "parameters": [ { "name": "response_id", "in": "path", "description": "Response hash.", "required": true, "schema": { "description": "Response hash.", "type": "string" } }, { "name": "account_id", "in": "path", "description": "Account ID.", "required": true, "schema": { "description": "Account ID.", "type": "string" } } ], "responses": { "200": { "description": "When `har.log.entries[].response._cf.contentAvailable` is `true`, use `response._cf.hash` value to fetch the raw response.", "content": { "text/plain": { "schema": { "description": "Web resource text/image.", "type": "string" } } } }, "400": { "description": "Invalid params.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Scan ID is not a valid UUID." } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "description": "Whether request was successful or not", "type": "boolean" } }, "required": [ "messages", "errors", "success" ] } } } }, "404": { "description": "Scan not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Scan not found." } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "description": "Whether request was successful or not", "type": "boolean" } }, "required": [ "messages", "errors", "success" ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Scanner (Deprecated)" ], "x-api-token-group": [ "URL Scanner Write", "URL Scanner Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "url-scanner.response", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" }, "x-stainless-deprecation-message": "Use [V2](https://developers.cloudflare.com/api/resources/url_scanner/subresources/responses/methods/get/) instead." } }, "/accounts/{account_id}/urlscanner/scan": { "get": { "operationId": "urlscanner-search-scans", "summary": "Search URL scans", "description": "Search scans by date and webpages' requests, including full URL (after redirects), hostname, and path.
A successful scan will appear in search results a few minutes after finishing but may take much longer if the system in under load. By default, only successfully completed scans will appear in search results, unless searching by `scanId`. Please take into account that older scans may be removed from the search index at an unspecified time.", "parameters": [ { "name": "account_id", "in": "path", "description": "Account ID.", "required": true, "schema": { "description": "Account ID.", "type": "string" } }, { "name": "scan_id", "in": "query", "description": "Scan UUID.", "schema": { "description": "Scan UUID.", "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Limit the number of objects in the response.", "schema": { "description": "Limit the number of objects in the response.", "type": "integer", "example": 100 } }, { "name": "next_cursor", "in": "query", "description": "Pagination cursor to get the next set of results.", "schema": { "description": "Pagination cursor to get the next set of results.", "type": "string" } }, { "name": "date_start", "in": "query", "description": "Filter scans requested after date (inclusive).", "schema": { "description": "Filter scans requested after date (inclusive).", "type": "string", "format": "date-time" } }, { "name": "date_end", "in": "query", "description": "Filter scans requested before date (inclusive).", "schema": { "description": "Filter scans requested before date (inclusive).", "type": "string", "format": "date-time" } }, { "name": "url", "in": "query", "description": "Filter scans by URL of _any_ request made by the webpage", "schema": { "description": "Filter scans by URL of _any_ request made by the webpage", "type": "string", "example": "https://example.com/?hello" } }, { "name": "hostname", "in": "query", "description": "Filter scans by hostname of _any_ request made by the webpage.", "schema": { "description": "Filter scans by hostname of _any_ request made by the webpage.", "type": "string", "example": "example.com" } }, { "name": "path", "in": "query", "description": "Filter scans by url path of _any_ request made by the webpage.", "schema": { "description": "Filter scans by url path of _any_ request made by the webpage.", "type": "string", "example": "/samples/subresource-integrity/" } }, { "name": "ip", "in": "query", "description": "Filter scans by IP address (IPv4 or IPv6) of _any_ request made by the webpage.", "schema": { "description": "Filter scans by IP address (IPv4 or IPv6) of _any_ request made by the webpage.", "type": "string", "example": "1.1.1.1" } }, { "name": "hash", "in": "query", "description": "Filter scans by hash of any html/js/css request made by the webpage.", "schema": { "description": "Filter scans by hash of any html/js/css request made by the webpage.", "type": "string" } }, { "name": "page_url", "in": "query", "description": "Filter scans by submitted or scanned URL", "schema": { "description": "Filter scans by submitted or scanned URL", "type": "string" } }, { "name": "page_hostname", "in": "query", "description": "Filter scans by main page hostname (domain of effective URL).", "schema": { "description": "Filter scans by main page hostname (domain of effective URL).", "type": "string" } }, { "name": "page_path", "in": "query", "description": "Filter scans by exact match of effective URL path (also supports suffix search).", "schema": { "description": "Filter scans by exact match of effective URL path (also supports suffix search).", "type": "string" } }, { "name": "page_asn", "in": "query", "description": "Filter scans by main page Autonomous System Number (ASN).", "schema": { "description": "Filter scans by main page Autonomous System Number (ASN).", "type": "string" } }, { "name": "page_ip", "in": "query", "description": "Filter scans by main page IP address (IPv4 or IPv6).", "schema": { "description": "Filter scans by main page IP address (IPv4 or IPv6).", "type": "string" } }, { "name": "account_scans", "in": "query", "description": "Return only scans created by account.", "schema": { "description": "Return only scans created by account.", "type": "boolean" } }, { "name": "is_malicious", "in": "query", "description": "Filter scans by malicious verdict.", "schema": { "description": "Filter scans by malicious verdict.", "type": "boolean" } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Error" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "OK" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "properties": { "country": { "description": "Alpha-2 country code", "type": "string" }, "success": { "description": "Whether scan was successful or not", "type": "boolean" }, "time": { "description": "When scan was submitted (UTC)", "type": "string", "format": "date-time" }, "url": { "description": "Scan url (after redirects)", "type": "string", "example": "https://www.example.com/" }, "uuid": { "description": "Scan id", "type": "string", "format": "uuid" }, "visibility": { "description": "Submitted visibility status.", "type": "string", "example": "public", "enum": [ "public", "unlisted" ] } }, "required": [ "uuid", "url", "success", "time", "country", "visibility" ], "type": "object" } } }, "required": [ "tasks" ] }, "success": { "description": "Whether search request was successful or not", "type": "boolean" } }, "required": [ "messages", "errors", "success", "result" ] } } } }, "400": { "description": "Invalid params.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Scan ID is not a valid UUID." } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "description": "Whether request was successful or not", "type": "boolean" } }, "required": [ "messages", "errors", "success" ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Scanner (Deprecated)" ], "x-api-token-group": [ "URL Scanner Write", "URL Scanner Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "url-scanner.scan.get.urlscanner", "x-fern-sdk-method-name": "scans", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" }, "x-stainless-deprecation-message": "Use [V2](https://developers.cloudflare.com/api/resources/url_scanner/subresources/scans/methods/list/) instead." }, "post": { "operationId": "urlscanner-create-scan", "summary": "Create URL Scan", "description": "Submit a URL to scan. You can also set some options, like the visibility level and custom headers. Check limits at https://developers.cloudflare.com/security-center/investigate/scan-limits/.", "parameters": [ { "name": "account_id", "in": "path", "description": "Account ID.", "required": true, "schema": { "description": "Account ID.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "description": "Country to geo egress from", "type": "string", "enum": [ "AF", "AL", "DZ", "AD", "AO", "AG", "AR", "AM", "AU", "AT", "AZ", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BR", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CO", "KM", "CG", "CR", "CI", "HR", "CU", "CY", "CZ", "CD", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FJ", "FI", "FR", "GA", "GE", "DE", "GH", "GR", "GL", "GD", "GT", "GN", "GW", "GY", "HT", "HN", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IL", "IT", "JM", "JP", "JO", "KZ", "KE", "KI", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MR", "MU", "MX", "FM", "MD", "MC", "MN", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NZ", "NI", "NE", "NG", "KP", "MK", "NO", "OM", "PK", "PS", "PA", "PG", "PY", "PE", "PH", "PL", "PT", "QA", "RO", "RU", "RW", "SH", "KN", "LC", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SK", "SI", "SB", "SO", "ZA", "KR", "SS", "ES", "LK", "SD", "SR", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "BS", "GM", "TL", "TG", "TO", "TT", "TN", "TR", "TM", "UG", "UA", "AE", "GB", "US", "UY", "UZ", "VU", "VE", "VN", "YE", "ZM", "ZW" ] }, "customHeaders": { "description": "Set custom headers.", "type": "object", "additionalProperties": { "type": "string" } }, "screenshotsResolutions": { "description": "Take multiple screenshots targeting different device types.", "type": "array", "items": { "default": "desktop", "description": "Device resolutions.", "enum": [ "desktop", "mobile", "tablet" ], "type": "string" }, "default": [ "desktop" ] }, "url": { "type": "string", "example": "https://www.example.com" }, "visibility": { "description": "The option `Public` means it will be included in listings like recent scans and search results. `Unlisted` means it will not be included in the aforementioned listings, users will need to have the scan's ID to access it. A a scan will be automatically marked as unlisted if it fails, if it contains potential PII or other sensitive material.", "type": "string", "default": "Public", "enum": [ "Public", "Unlisted" ] } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Scan request accepted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Submission unsuccessful" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Submission successful" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "time": { "description": "Time when url was submitted for scanning.", "type": "string", "format": "date-time" }, "url": { "description": "Canonical form of submitted URL. Use this if you want to later search by URL.", "type": "string" }, "uuid": { "description": "Scan ID.", "type": "string", "format": "uuid" }, "visibility": { "description": "Submitted visibility status.", "type": "string", "example": "public", "enum": [ "public", "unlisted" ] } }, "required": [ "visibility", "uuid", "url", "time" ] }, "success": { "type": "boolean" } }, "required": [ "messages", "errors", "success", "result" ] } } } }, "400": { "description": "Invalid params.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Scan ID is not a valid UUID." } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "description": "Whether request was successful or not", "type": "boolean" } }, "required": [ "messages", "errors", "success" ] } } } }, "409": { "description": "Scan request denied: hostname was recently scanned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Submission unsuccessful" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "properties": { "clientLocation": { "description": "Submitter location", "type": "string", "example": "PT" }, "clientType": { "type": "string", "enum": [ "Site", "Automatic", "Api" ] }, "effectiveUrl": { "description": "URL of the primary request, after all HTTP redirects", "type": "string", "example": "http://example.com/" }, "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "scannedFrom": { "type": "object", "properties": { "colo": { "description": "IATA code of Cloudflare datacenter", "type": "string", "example": "MAD" } }, "required": [ "colo" ] }, "status": { "type": "string", "enum": [ "Queued", "InProgress", "InPostProcessing", "Finished" ] }, "success": { "type": "boolean", "example": true }, "time": { "type": "string", "example": "2023-05-03T17:05:04.843Z" }, "timeEnd": { "type": "string", "example": "2023-05-03T17:05:19.374Z" }, "url": { "description": "Submitted URL", "type": "string", "example": "http://example.com" }, "uuid": { "description": "Scan ID", "type": "string", "example": "2ee568d0-bf70-4827-b922-b7088c0f056f" }, "visibility": { "type": "string", "enum": [ "Public", "Unlisted" ] } }, "required": [ "uuid", "url", "status", "success", "errors", "time", "timeEnd", "visibility", "clientLocation", "clientType", "effectiveUrl", "scannedFrom" ], "type": "object" } } }, "required": [ "tasks" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "messages", "errors", "success", "result" ] } } } }, "429": { "description": "Scan request denied: rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Submission unsuccessful" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "example": true } }, "required": [ "messages", "errors", "success" ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Scanner (Deprecated)" ], "x-api-token-group": [ "URL Scanner Write", "URL Scanner Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "url-scanner.scan", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" }, "x-stainless-deprecation-message": "Use [V2](https://developers.cloudflare.com/api/resources/url_scanner/subresources/scans/methods/create/) instead." } }, "/accounts/{account_id}/urlscanner/scan/{scan_id}": { "get": { "operationId": "urlscanner-get-scan", "summary": "Get URL scan", "description": "Get URL scan by uuid", "parameters": [ { "name": "scan_id", "in": "path", "description": "Scan UUID.", "required": true, "schema": { "description": "Scan UUID.", "type": "string", "format": "uuid" } }, { "name": "account_id", "in": "path", "description": "Account ID.", "required": true, "schema": { "description": "Account ID.", "type": "string" } }, { "name": "full", "in": "query", "description": "Whether to return full report (scan summary and network log).", "schema": { "description": "Whether to return full report (scan summary and network log).", "type": "boolean" } } ], "responses": { "200": { "description": "Scan has finished. It may or may not have been successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Error" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "OK" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "scan": { "type": "object", "properties": { "asns": { "description": "Dictionary of Autonomous System Numbers where ASN's are the keys", "type": "object", "properties": { "asn": { "description": "ASN's contacted", "type": "object", "properties": { "asn": { "type": "string", "example": "15133" }, "description": { "type": "string", "example": "EDGECAST" }, "location_alpha2": { "type": "string", "example": "US" }, "name": { "type": "string", "example": "EDGECAST" }, "org_name": { "type": "string", "example": "Edgecast Inc." } }, "required": [ "asn", "name", "description", "org_name", "location_alpha2" ] } } }, "certificates": { "type": "array", "items": { "properties": { "issuer": { "type": "string" }, "subjectName": { "type": "string", "example": "rkmod.somee.com" }, "validFrom": { "type": "number", "example": 1682684400 }, "validTo": { "type": "number", "example": 1696698000 } }, "required": [ "issuer", "subjectName", "validFrom", "validTo" ], "type": "object" } }, "domains": { "type": "object", "properties": { "example.com": { "type": "object", "properties": { "categories": { "type": "object", "properties": { "content": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string", "example": "Technology" }, "super_category_id": { "type": "integer" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "inherited": { "type": "object", "properties": { "content": { "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string", "example": "Technology" }, "super_category_id": { "type": "integer" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "from": { "type": "string", "example": "example.com" }, "risks": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string", "example": "Technology" }, "super_category_id": { "type": "integer" } }, "required": [ "id", "name" ], "type": "object" } } } }, "risks": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "name": { "type": "string", "example": "Technology" }, "super_category_id": { "type": "integer" } }, "required": [ "id", "name" ], "type": "object" } } }, "required": [ "inherited" ] }, "dns": { "type": "array", "items": { "properties": { "address": { "type": "string", "example": "93.184.216.34" }, "dnssec_valid": { "type": "boolean" }, "name": { "type": "string", "example": "example.com" }, "type": { "type": "string", "example": "A" } }, "required": [ "name", "address", "type", "dnssec_valid" ], "type": "object" } }, "name": { "type": "string", "example": "example.com" }, "rank": { "type": "object", "properties": { "bucket": { "type": "string", "example": "500" }, "name": { "type": "string", "example": "example.com" }, "rank": { "description": "Rank in the Global Radar Rank, if set. See more at https://blog.cloudflare.com/radar-domain-rankings/", "type": "integer" } }, "required": [ "name", "bucket" ] }, "type": { "type": "string", "example": "Apex domain" } }, "required": [ "name", "type", "categories", "dns", "rank" ] } } }, "geo": { "type": "object", "properties": { "continents": { "type": "array", "items": { "description": "GeoIP continent location", "example": "North America", "type": "string" } }, "locations": { "type": "array", "items": { "description": "GeoIP country location", "example": "US", "type": "string" } } }, "required": [ "locations", "continents" ] }, "ips": { "type": "object", "properties": { "ip": { "type": "object", "properties": { "asn": { "type": "string", "example": "15133" }, "asnDescription": { "type": "string", "example": "EDGECAST" }, "asnLocationAlpha2": { "type": "string", "example": "US" }, "asnName": { "type": "string", "example": "EDGECAST" }, "asnOrgName": { "type": "string", "example": "Edgecast Inc." }, "continent": { "type": "string", "example": "North America" }, "geonameId": { "type": "string", "example": "6252001" }, "ip": { "type": "string", "example": "2606:2800:220:1:248:1893:25c8:1946" }, "ipVersion": { "type": "string", "example": "IPv6" }, "latitude": { "type": "string", "example": "39.76" }, "locationAlpha2": { "type": "string", "example": "US" }, "locationName": { "type": "string", "example": "United States" }, "longitude": { "type": "string", "example": "-98.5" }, "subdivision1Name": { "type": "string" }, "subdivision2Name": { "type": "string" } }, "required": [ "ip", "ipVersion", "locationAlpha2", "locationName", "subdivision1Name", "subdivision2Name", "latitude", "longitude", "continent", "geonameId", "asn", "asnName", "asnOrgName", "asnDescription", "asnLocationAlpha2" ] } } }, "links": { "type": "object", "properties": { "link": { "type": "object", "properties": { "href": { "description": "Outgoing link detected in the DOM", "type": "string", "example": "https://www.iana.org/domains/example" }, "text": { "type": "string", "example": "More information..." } }, "required": [ "href", "text" ] } } }, "meta": { "type": "object", "properties": { "processors": { "type": "object", "properties": { "categories": { "type": "object", "properties": { "content": { "items": { "properties": { "id": { "type": "integer", "example": 155 }, "name": { "type": "string", "example": "Technology" }, "super_category_id": { "type": "integer" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "risks": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 17 }, "name": { "type": "string", "example": "Newly Seen Domains" }, "super_category_id": { "type": "integer", "example": 32 } }, "required": [ "id", "super_category_id", "name" ], "type": "object" } } }, "required": [ "content", "risks" ] }, "phishing": { "type": "array", "items": { "example": "CredentialHarvester", "type": "string" } }, "rank": { "type": "object", "properties": { "bucket": { "type": "string", "example": "500" }, "name": { "type": "string", "example": "example.com" }, "rank": { "description": "Rank in the Global Radar Rank, if set. See more at https://blog.cloudflare.com/radar-domain-rankings/", "type": "integer" } }, "required": [ "name", "bucket" ] }, "tech": { "type": "array", "items": { "properties": { "categories": { "type": "array", "items": { "properties": { "groups": { "type": "array", "items": { "type": "integer" } }, "id": { "type": "integer", "example": 63 }, "name": { "type": "string", "example": "IAAS" }, "priority": { "type": "integer", "example": 8 }, "slug": { "type": "string", "example": "iaas" } }, "required": [ "id", "slug", "groups", "name", "priority" ], "type": "object" } }, "confidence": { "type": "integer", "example": 100 }, "description": { "type": "string" }, "evidence": { "type": "object", "properties": { "impliedBy": { "type": "array", "items": { "type": "string" } }, "patterns": { "type": "array", "items": { "properties": { "confidence": { "type": "integer", "example": 100 }, "excludes": { "type": "array", "items": { "type": "string" } }, "implies": { "type": "array", "items": { "type": "string" } }, "match": { "type": "string", "example": "ECS" }, "name": { "description": "Header or Cookie name when set", "type": "string", "example": "server" }, "regex": { "type": "string", "example": "^ECS" }, "type": { "type": "string", "example": "headers" }, "value": { "type": "string", "example": "ECS (dcb/7EEE)" }, "version": { "type": "string" } }, "required": [ "type", "regex", "value", "match", "name", "confidence", "version", "implies", "excludes" ], "type": "object" } } }, "required": [ "patterns", "impliedBy" ] }, "icon": { "type": "string", "example": "Amazon ECS.svg" }, "name": { "type": "string", "example": "Amazon ECS" }, "slug": { "type": "string", "example": "amazon-ecs" }, "website": { "type": "string", "example": "https://aws.amazon.com/ecs/" } }, "required": [ "name", "slug", "categories", "confidence", "icon", "website", "evidence" ], "type": "object" } } }, "required": [ "tech", "categories", "rank", "phishing" ] } }, "required": [ "processors" ] }, "page": { "type": "object", "properties": { "asn": { "type": "string", "example": "15133" }, "asnLocationAlpha2": { "type": "string", "example": "US" }, "asnname": { "type": "string", "example": "EDGECAST" }, "console": { "type": "array", "items": { "properties": { "category": { "type": "string", "example": "network" }, "text": { "type": "string", "example": "Failed to load resource: the server responded with a status of 404 (Not Found)" }, "type": { "type": "string", "example": "error" }, "url": { "type": "string", "example": "http://example.com/favicon.ico" } }, "required": [ "type", "text", "category" ], "type": "object" } }, "cookies": { "type": "array", "items": { "properties": { "domain": { "type": "string", "example": "rkmod.somee.com" }, "expires": { "type": "number", "example": -1 }, "httpOnly": { "type": "boolean" }, "name": { "type": "string", "example": "b" }, "path": { "type": "string", "example": "/" }, "priority": { "type": "string", "example": "Medium" }, "sameParty": { "type": "boolean" }, "secure": { "type": "boolean" }, "session": { "type": "boolean", "example": true }, "size": { "type": "number", "example": 2 }, "sourcePort": { "type": "number", "example": 443 }, "sourceScheme": { "type": "string", "example": "Secure" }, "value": { "type": "string", "example": "b" } }, "required": [ "name", "value", "domain", "path", "expires", "size", "httpOnly", "secure", "session", "sameParty", "sourceScheme", "sourcePort" ], "type": "object" } }, "country": { "type": "string", "example": "United States" }, "countryLocationAlpha2": { "type": "string", "example": "US" }, "domain": { "type": "string", "example": "example.com" }, "headers": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Content-Length" }, "value": { "type": "string", "example": "648" } }, "required": [ "name", "value" ], "type": "object" } }, "ip": { "type": "string", "example": "2606:2800:220:1:248:1893:25c8:1946" }, "js": { "type": "object", "properties": { "variables": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "checkFrame" }, "type": { "type": "string", "example": "string" } }, "required": [ "name", "type" ], "type": "object" } } }, "required": [ "variables" ] }, "securityViolations": { "type": "array", "items": { "properties": { "category": { "type": "string", "example": "csp" }, "text": { "type": "string", "example": "[Report Only] Refused to load the stylesheet 'https://netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap.min.css' because it violates the following Content Security Policy directive: ... " }, "url": { "type": "string", "example": "http://example.com/" } }, "required": [ "text", "category", "url" ], "type": "object" } }, "status": { "type": "number", "example": 200 }, "subdivision1Name": { "type": "string" }, "subdivision2name": { "type": "string" }, "url": { "type": "string", "example": "http://example.com/" } }, "required": [ "url", "domain", "country", "countryLocationAlpha2", "subdivision1Name", "subdivision2name", "ip", "asn", "asnname", "asnLocationAlpha2", "cookies", "headers", "status", "js", "console", "securityViolations" ] }, "performance": { "type": "array", "items": { "properties": { "connectEnd": { "type": "number", "example": 82.59999999403954 }, "connectStart": { "type": "number", "example": 72.79999999701977 }, "decodedBodySize": { "type": "number", "example": 1256 }, "domComplete": { "type": "number", "example": 306 }, "domContentLoadedEventEnd": { "type": "number", "example": 305.8999999910593 }, "domContentLoadedEventStart": { "type": "number", "example": 305.8999999910593 }, "domInteractive": { "type": "number", "example": 305.8999999910593 }, "domainLookupEnd": { "type": "number", "example": 72.79999999701977 }, "domainLookupStart": { "type": "number", "example": 2.199999988079071 }, "duration": { "type": "number", "example": 306 }, "encodedBodySize": { "type": "number", "example": 648 }, "entryType": { "type": "string", "example": "navigation" }, "fetchStart": { "type": "number", "example": 0.8999999910593033 }, "initiatorType": { "type": "string", "example": "navigation" }, "loadEventEnd": { "type": "number", "example": 306 }, "loadEventStart": { "type": "number", "example": 306 }, "name": { "type": "string", "example": "http://example.com/" }, "nextHopProtocol": { "type": "string", "example": "http/1.1" }, "redirectCount": { "type": "number" }, "redirectEnd": { "type": "number" }, "redirectStart": { "type": "number" }, "requestStart": { "type": "number", "example": 82.69999998807907 }, "responseEnd": { "type": "number", "example": 270.8999999910593 }, "responseStart": { "type": "number", "example": 265.69999998807907 }, "secureConnectionStart": { "type": "number" }, "startTime": { "type": "number" }, "transferSize": { "type": "number", "example": 948 }, "type": { "type": "string", "example": "navigate" }, "unloadEventEnd": { "type": "number" }, "unloadEventStart": { "type": "number" }, "workerStart": { "type": "number" } }, "required": [ "name", "entryType", "startTime", "duration", "initiatorType", "nextHopProtocol", "workerStart", "redirectStart", "redirectEnd", "fetchStart", "domainLookupStart", "domainLookupEnd", "connectStart", "connectEnd", "secureConnectionStart", "requestStart", "responseStart", "responseEnd", "transferSize", "encodedBodySize", "decodedBodySize", "unloadEventStart", "unloadEventEnd", "domInteractive", "domContentLoadedEventStart", "domContentLoadedEventEnd", "domComplete", "loadEventStart", "loadEventEnd", "type", "redirectCount" ], "type": "object" } }, "task": { "type": "object", "properties": { "clientLocation": { "description": "Submitter location", "type": "string", "example": "PT" }, "clientType": { "type": "string", "enum": [ "Site", "Automatic", "Api" ] }, "effectiveUrl": { "description": "URL of the primary request, after all HTTP redirects", "type": "string", "example": "http://example.com/" }, "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "scannedFrom": { "type": "object", "properties": { "colo": { "description": "IATA code of Cloudflare datacenter", "type": "string", "example": "MAD" } }, "required": [ "colo" ] }, "status": { "type": "string", "enum": [ "Queued", "InProgress", "InPostProcessing", "Finished" ] }, "success": { "type": "boolean", "example": true }, "time": { "type": "string", "example": "2023-05-03T17:05:04.843Z" }, "timeEnd": { "type": "string", "example": "2023-05-03T17:05:19.374Z" }, "url": { "description": "Submitted URL", "type": "string", "example": "http://example.com" }, "uuid": { "description": "Scan ID", "type": "string", "example": "2ee568d0-bf70-4827-b922-b7088c0f056f" }, "visibility": { "type": "string", "enum": [ "Public", "Unlisted" ] } }, "required": [ "uuid", "url", "status", "success", "errors", "time", "timeEnd", "visibility", "clientLocation", "clientType", "effectiveUrl", "scannedFrom" ] }, "verdicts": { "type": "object", "properties": { "overall": { "type": "object", "properties": { "categories": { "type": "array", "items": { "properties": { "id": { "type": "number", "example": 117 }, "name": { "type": "string", "example": "Malware" }, "super_category_id": { "type": "number", "example": 32 } }, "required": [ "id", "super_category_id", "name" ], "type": "object" } }, "malicious": { "description": "At least one of our subsystems marked the site as potentially malicious at the time of the scan.", "type": "boolean", "example": true }, "phishing": { "type": "array", "items": { "example": "Credential Harvester", "type": "string" } } }, "required": [ "malicious", "categories", "phishing" ] } }, "required": [ "overall" ] } }, "required": [ "task", "meta", "page", "geo", "certificates", "performance", "verdicts" ] } }, "required": [ "scan" ] }, "success": { "description": "Whether request was successful or not", "type": "boolean" } }, "required": [ "messages", "errors", "success", "result" ] } } } }, "202": { "description": "Scan is in progress. Check current status in `result.scan.task.status`. Possible statuses: `Queued`,`InProgress`,`InPostProcessing`,`Finished`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "In Progress" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "scan": { "type": "object", "properties": { "task": { "type": "object", "properties": { "effectiveUrl": { "type": "string", "example": "http://example.com/" }, "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "location": { "type": "string", "example": "PT" }, "region": { "type": "string", "example": "enam" }, "status": { "type": "string", "example": "InProgress" }, "success": { "type": "boolean", "example": true }, "time": { "type": "string", "example": "2023-05-03T17:05:04.843Z" }, "url": { "type": "string", "example": "http://example.com" }, "uuid": { "type": "string", "example": "2ee568d0-bf70-4827-b922-b7088c0f056f" }, "visibility": { "type": "string", "example": "Public" } }, "required": [ "uuid", "url", "status", "success", "errors", "time", "visibility", "location", "region", "effectiveUrl" ] } }, "required": [ "task" ] } }, "required": [ "scan" ] }, "success": { "description": "Whether request was successful or not", "type": "boolean" } }, "required": [ "messages", "errors", "success", "result" ] } } } }, "400": { "description": "Invalid params.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Scan ID is not a valid UUID." } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "description": "Whether request was successful or not", "type": "boolean" } }, "required": [ "messages", "errors", "success" ] } } } }, "404": { "description": "Scan not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Scan not found." } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "description": "Whether request was successful or not", "type": "boolean" } }, "required": [ "messages", "errors", "success" ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Scanner (Deprecated)" ], "x-api-token-group": [ "URL Scanner Write", "URL Scanner Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "url-scanner.scan.get.urlscanner", "x-fern-sdk-method-name": "scan", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" }, "x-stainless-deprecation-message": "Use [V2](https://developers.cloudflare.com/api/resources/url_scanner/subresources/scans/methods/get/) instead." } }, "/accounts/{account_id}/urlscanner/scan/{scan_id}/har": { "get": { "operationId": "urlscanner-get-scan-har", "summary": "Get URL scan's HAR", "description": "Get a URL scan's HAR file. See HAR spec at http://www.softwareishard.com/blog/har-12-spec/.", "parameters": [ { "name": "scan_id", "in": "path", "description": "Scan UUID.", "required": true, "schema": { "description": "Scan UUID.", "type": "string", "format": "uuid" } }, { "name": "account_id", "in": "path", "description": "Account ID.", "required": true, "schema": { "description": "Account ID.", "type": "string" } } ], "responses": { "200": { "description": "Returns the scan's har.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Error" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "OK" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "har": { "type": "object", "properties": { "log": { "type": "object", "properties": { "creator": { "type": "object", "properties": { "comment": { "type": "string", "example": "https://github.com/sitespeedio/chrome-har" }, "name": { "type": "string", "example": "chrome-har" }, "version": { "type": "string", "example": "0.13.1" } }, "required": [ "name", "version", "comment" ] }, "entries": { "type": "array", "items": { "properties": { "_initialPriority": { "type": "string", "example": "VeryHigh" }, "_initiator_type": { "type": "string", "example": "other" }, "_priority": { "type": "string", "example": "VeryHigh" }, "_requestId": { "type": "string", "example": "DDC779F0CB3746BAF283EC1A51B0F2F8" }, "_requestTime": { "type": "number", "example": 114135.331081 }, "_resourceType": { "type": "string", "example": "document" }, "cache": { "type": "object" }, "connection": { "type": "string", "example": "33" }, "pageref": { "type": "string", "example": "page_1" }, "request": { "type": "object", "properties": { "bodySize": { "type": "number" }, "headers": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Upgrade-Insecure-Requests" }, "value": { "type": "string", "example": "1" } }, "required": [ "name", "value" ], "type": "object" } }, "headersSize": { "type": "number", "example": 197 }, "httpVersion": { "type": "string", "example": "http/1.1" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "http://example.com/" } }, "required": [ "method", "url", "headersSize", "bodySize", "headers", "httpVersion" ] }, "response": { "type": "object", "properties": { "_transferSize": { "type": "number", "example": 1071 }, "bodySize": { "type": "number", "example": 648 }, "content": { "properties": { "compression": { "type": "integer", "example": 608 }, "mimeType": { "type": "string", "example": "text/html" }, "size": { "type": "number", "example": 1256 } }, "required": [ "mimeType", "size" ], "type": "object" }, "headers": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Content-Encoding" }, "value": { "type": "string", "example": "gzip" } }, "required": [ "name", "value" ], "type": "object" } }, "headersSize": { "type": "number", "example": 423 }, "httpVersion": { "type": "string", "example": "http/1.1" }, "redirectURL": { "type": "string" }, "status": { "type": "number", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "httpVersion", "redirectURL", "status", "statusText", "content", "headersSize", "bodySize", "headers", "_transferSize" ] }, "serverIPAddress": { "type": "string", "example": "2606:2800:220:1:248:1893:25c8:1946" }, "startedDateTime": { "type": "string", "example": "2023-05-03T17:05:13.196Z" }, "time": { "type": "number", "example": 268.64 } }, "required": [ "cache", "startedDateTime", "_requestId", "_initialPriority", "_priority", "pageref", "request", "time", "_initiator_type", "_resourceType", "response", "connection", "serverIPAddress", "_requestTime" ], "type": "object" } }, "pages": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "page_1" }, "pageTimings": { "type": "object", "properties": { "onContentLoad": { "type": "number", "example": 305.408 }, "onLoad": { "type": "number", "example": 305.169 } }, "required": [ "onLoad", "onContentLoad" ] }, "startedDateTime": { "type": "string", "example": "2023-05-03T17:05:13.195Z" }, "title": { "type": "string", "example": "http://example.com/" } }, "required": [ "id", "startedDateTime", "title", "pageTimings" ], "type": "object" } }, "version": { "type": "string", "example": "1.2" } }, "required": [ "version", "creator", "pages", "entries" ] } }, "required": [ "log" ] } }, "required": [ "har" ] }, "success": { "description": "Whether search request was successful or not", "type": "boolean" } }, "required": [ "messages", "errors", "success", "result" ] } } } }, "202": { "description": "Scan is in progress. Check current status in `result.scan.task.status`. Possible statuses: `Queued`,`InProgress`,`InPostProcessing`,`Finished`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "In Progress" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "scan": { "type": "object", "properties": { "task": { "type": "object", "properties": { "effectiveUrl": { "type": "string", "example": "http://example.com/" }, "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "location": { "type": "string", "example": "PT" }, "region": { "type": "string", "example": "enam" }, "status": { "type": "string", "example": "InProgress" }, "success": { "type": "boolean", "example": true }, "time": { "type": "string", "example": "2023-05-03T17:05:04.843Z" }, "url": { "type": "string", "example": "http://example.com" }, "uuid": { "type": "string", "example": "2ee568d0-bf70-4827-b922-b7088c0f056f" }, "visibility": { "type": "string", "example": "Public" } }, "required": [ "uuid", "url", "status", "success", "errors", "time", "visibility", "location", "region", "effectiveUrl" ] } }, "required": [ "task" ] } }, "required": [ "scan" ] }, "success": { "description": "Whether request was successful or not", "type": "boolean" } }, "required": [ "messages", "errors", "success", "result" ] } } } }, "400": { "description": "Invalid params.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Scan ID is not a valid UUID." } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "description": "Whether request was successful or not", "type": "boolean" } }, "required": [ "messages", "errors", "success" ] } } } }, "404": { "description": "Scan not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Scan not found." } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "description": "Whether request was successful or not", "type": "boolean" } }, "required": [ "messages", "errors", "success" ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Scanner (Deprecated)" ], "x-api-token-group": [ "URL Scanner Write", "URL Scanner Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "url-scanner.scan.har", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" }, "x-stainless-deprecation-message": "Use [V2](https://developers.cloudflare.com/api/resources/url_scanner/subresources/scans/methods/har/) instead." } }, "/accounts/{account_id}/urlscanner/scan/{scan_id}/screenshot": { "get": { "operationId": "urlscanner-get-scan-screenshot", "summary": "Get screenshot", "description": "Get scan's screenshot by resolution (desktop/mobile/tablet).", "parameters": [ { "name": "scan_id", "in": "path", "description": "Scan UUID.", "required": true, "schema": { "description": "Scan UUID.", "type": "string", "format": "uuid" } }, { "name": "account_id", "in": "path", "description": "Account ID.", "required": true, "schema": { "description": "Account ID.", "type": "string" } }, { "name": "resolution", "in": "query", "description": "Target device type.", "schema": { "description": "Target device type.", "type": "string", "default": "desktop", "enum": [ "desktop", "mobile", "tablet" ] } } ], "responses": { "200": { "description": "Returns the scan's requested screenshot.", "content": { "image/png": { "schema": { "description": "PNG Image.", "type": "string" } } } }, "202": { "description": "Scan is in progress. Check current status in `result.scan.task.status`. Possible statuses: `Queued`,`InProgress`,`InPostProcessing`,`Finished`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "In Progress" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "scan": { "type": "object", "properties": { "task": { "type": "object", "properties": { "effectiveUrl": { "type": "string", "example": "http://example.com/" }, "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "location": { "type": "string", "example": "PT" }, "region": { "type": "string", "example": "enam" }, "status": { "type": "string", "example": "InProgress" }, "success": { "type": "boolean", "example": true }, "time": { "type": "string", "example": "2023-05-03T17:05:04.843Z" }, "url": { "type": "string", "example": "http://example.com" }, "uuid": { "type": "string", "example": "2ee568d0-bf70-4827-b922-b7088c0f056f" }, "visibility": { "type": "string", "example": "Public" } }, "required": [ "uuid", "url", "status", "success", "errors", "time", "visibility", "location", "region", "effectiveUrl" ] } }, "required": [ "task" ] } }, "required": [ "scan" ] }, "success": { "description": "Whether request was successful or not", "type": "boolean" } }, "required": [ "messages", "errors", "success", "result" ] } } } }, "400": { "description": "Invalid params.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Scan ID is not a valid UUID." } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "description": "Whether request was successful or not", "type": "boolean" } }, "required": [ "messages", "errors", "success" ] } } } }, "404": { "description": "Scan not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string", "example": "Scan not found." } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "description": "Whether request was successful or not", "type": "boolean" } }, "required": [ "messages", "errors", "success" ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Scanner (Deprecated)" ], "x-api-token-group": [ "URL Scanner Write", "URL Scanner Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "url-scanner.scan.screenshot", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" }, "x-stainless-deprecation-message": "Use [V2](https://developers.cloudflare.com/api/resources/url_scanner/subresources/scans/methods/screenshot/) instead." } }, "/accounts/{account_id}/urlscanner/v2/bulk": { "post": { "operationId": "urlscanner-create-scan-bulk-v2", "summary": "Bulk create URL Scans", "description": "Submit URLs to scan. Check limits at https://developers.cloudflare.com/security-center/investigate/scan-limits/ and take into account scans submitted in bulk have lower priority and may take longer to finish.", "parameters": [ { "name": "account_id", "in": "path", "description": "Account ID.", "required": true, "schema": { "description": "Account ID.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "List of urls to scan (up to a 100).", "type": "array", "items": { "properties": { "agentReadiness": { "description": "Enable agent readiness checks.", "type": "boolean" }, "customHeaders": { "description": "Set custom headers.", "type": "object", "additionalProperties": { "type": "string" } }, "customagent": { "type": "string", "maxLength": 4096 }, "referer": { "type": "string", "maxLength": 4096 }, "screenshotsResolutions": { "description": "Take multiple screenshots targeting different device types.", "type": "array", "items": { "default": "desktop", "description": "Device resolutions.", "enum": [ "desktop", "mobile", "tablet" ], "type": "string" }, "default": [ "desktop" ] }, "url": { "type": "string", "example": "https://www.example.com" }, "visibility": { "description": "The option `Public` means it will be included in listings like recent scans and search results. `Unlisted` means it will not be included in the aforementioned listings, users will need to have the scan's ID to access it. A a scan will be automatically marked as unlisted if it fails, if it contains potential PII or other sensitive material.", "type": "string", "default": "Public", "enum": [ "Public", "Unlisted" ] } }, "required": [ "url" ], "type": "object" } } } } }, "responses": { "200": { "description": "Scan bulk request accepted successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "api": { "description": "URL to api report.", "type": "string" }, "options": { "type": "object", "properties": { "useragent": { "type": "string" } } }, "result": { "description": "URL to report.", "type": "string" }, "url": { "description": "Submitted URL", "type": "string" }, "uuid": { "description": "Scan ID.", "type": "string", "format": "uuid" }, "visibility": { "description": "Submitted visibility status.", "type": "string", "example": "public", "enum": [ "public", "unlisted" ] } }, "required": [ "uuid", "result", "api", "visibility", "url" ], "type": "object" } } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "status": { "description": "Status code.", "type": "integer", "example": 400 }, "title": { "type": "string", "example": "Invalid url" } }, "required": [ "title", "detail", "status" ], "type": "object" } }, "message": { "type": "string" }, "status": { "description": "Status code.", "type": "integer", "example": 400 } }, "required": [ "message", "status", "errors" ] } } } }, "429": { "description": "Scan request denied: rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string" }, "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string", "example": "DNS Error - Could not resolve domain." }, "status": { "type": "number", "example": 400 }, "title": { "type": "string", "example": "DNS Error - Could not resolve domain." } }, "required": [ "title", "detail", "status" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "number", "example": 429 } }, "required": [ "message", "status", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Scanner" ], "x-api-token-group": [ "URL Scanner Write", "URL Scanner Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "url-scanner.scans", "x-fern-sdk-method-name": "bulk-create", "x-forge-hidden": true } }, "/accounts/{account_id}/urlscanner/v2/dom/{scan_id}": { "get": { "operationId": "urlscanner-get-scan-dom-v2", "summary": "Get URL scan's DOM", "description": "Returns a plain text response, with the scan's DOM content as rendered by Chrome.", "parameters": [ { "name": "scan_id", "in": "path", "description": "Scan UUID.", "required": true, "schema": { "description": "Scan UUID.", "type": "string", "format": "uuid" } }, { "name": "account_id", "in": "path", "description": "Account ID.", "required": true, "schema": { "description": "Account ID.", "type": "string" } } ], "responses": { "200": { "description": "Returns a plain text response, with the scan's DOM content as rendered by Chrome.", "content": { "text/plain": { "schema": { "description": "HTML of webpage.", "type": "string" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "status": { "description": "Status code.", "type": "integer", "example": 400 }, "title": { "type": "string", "example": "Invalid url" } }, "required": [ "title", "detail", "status" ], "type": "object" } }, "message": { "type": "string" }, "status": { "description": "Status code.", "type": "integer", "example": 400 } }, "required": [ "message", "status", "errors" ] } } } }, "404": { "description": "Scan not found or in progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string", "example": "Queued" }, "status": { "description": "Status code.", "type": "integer", "example": 404 }, "title": { "type": "string", "example": "Scan is not finished yet." } }, "required": [ "title", "detail", "status" ], "type": "object" } }, "message": { "description": "Scan not found or in progress.", "type": "string", "example": "Scan is not finished yet." }, "status": { "description": "Status code.", "type": "integer", "example": 404 }, "task": { "type": "object", "properties": { "status": { "type": "string", "example": "Queued" }, "time": { "type": "string" }, "url": { "type": "string" }, "uuid": { "type": "string" }, "visibility": { "type": "string", "example": "public" } }, "required": [ "uuid", "url", "time", "status", "visibility" ] } }, "required": [ "message", "status", "errors", "task" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Scanner" ], "x-api-token-group": [ "URL Scanner Write", "URL Scanner Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "url-scanner.scans", "x-fern-sdk-method-name": "dom", "x-forge-hidden": true } }, "/accounts/{account_id}/urlscanner/v2/har/{scan_id}": { "get": { "operationId": "urlscanner-get-scan-har-v2", "summary": "Get URL scan's HAR", "description": "Get a URL scan's HAR file. See HAR spec at http://www.softwareishard.com/blog/har-12-spec/.", "parameters": [ { "name": "scan_id", "in": "path", "description": "Scan UUID.", "required": true, "schema": { "description": "Scan UUID.", "type": "string", "format": "uuid" } }, { "name": "account_id", "in": "path", "description": "Account ID.", "required": true, "schema": { "description": "Account ID.", "type": "string" } } ], "responses": { "200": { "description": "Returns the scan's har.", "content": { "application/json": { "schema": { "type": "object", "properties": { "log": { "type": "object", "properties": { "creator": { "type": "object", "properties": { "comment": { "type": "string", "example": "https://github.com/sitespeedio/chrome-har" }, "name": { "type": "string", "example": "chrome-har" }, "version": { "type": "string", "example": "0.13.1" } }, "required": [ "name", "version", "comment" ] }, "entries": { "type": "array", "items": { "properties": { "_initialPriority": { "type": "string", "example": "VeryHigh" }, "_initiator_type": { "type": "string", "example": "other" }, "_priority": { "type": "string", "example": "VeryHigh" }, "_requestId": { "type": "string", "example": "DDC779F0CB3746BAF283EC1A51B0F2F8" }, "_requestTime": { "type": "number", "example": 114135.331081 }, "_resourceType": { "type": "string", "example": "document" }, "cache": { "type": "object" }, "connection": { "type": "string", "example": "33" }, "pageref": { "type": "string", "example": "page_1" }, "request": { "type": "object", "properties": { "bodySize": { "type": "number" }, "headers": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Upgrade-Insecure-Requests" }, "value": { "type": "string", "example": "1" } }, "required": [ "name", "value" ], "type": "object" } }, "headersSize": { "type": "number", "example": 197 }, "httpVersion": { "type": "string", "example": "http/1.1" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "http://example.com/" } }, "required": [ "method", "url", "headersSize", "bodySize", "headers", "httpVersion" ] }, "response": { "type": "object", "properties": { "_transferSize": { "type": "number", "example": 1071 }, "bodySize": { "type": "number", "example": 648 }, "content": { "properties": { "compression": { "type": "integer", "example": 608 }, "mimeType": { "type": "string", "example": "text/html" }, "size": { "type": "number", "example": 1256 } }, "required": [ "mimeType", "size" ], "type": "object" }, "headers": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Content-Encoding" }, "value": { "type": "string", "example": "gzip" } }, "required": [ "name", "value" ], "type": "object" } }, "headersSize": { "type": "number", "example": 423 }, "httpVersion": { "type": "string", "example": "http/1.1" }, "redirectURL": { "type": "string" }, "status": { "type": "number", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "httpVersion", "redirectURL", "status", "statusText", "content", "headersSize", "bodySize", "headers", "_transferSize" ] }, "serverIPAddress": { "type": "string", "example": "2606:2800:220:1:248:1893:25c8:1946" }, "startedDateTime": { "type": "string", "example": "2023-05-03T17:05:13.196Z" }, "time": { "type": "number", "example": 268.64 } }, "required": [ "cache", "startedDateTime", "_requestId", "_initialPriority", "_priority", "pageref", "request", "time", "_initiator_type", "_resourceType", "response", "connection", "serverIPAddress", "_requestTime" ], "type": "object" } }, "pages": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "page_1" }, "pageTimings": { "type": "object", "properties": { "onContentLoad": { "type": "number", "example": 305.408 }, "onLoad": { "type": "number", "example": 305.169 } }, "required": [ "onLoad", "onContentLoad" ] }, "startedDateTime": { "type": "string", "example": "2023-05-03T17:05:13.195Z" }, "title": { "type": "string", "example": "http://example.com/" } }, "required": [ "id", "startedDateTime", "title", "pageTimings" ], "type": "object" } }, "version": { "type": "string", "example": "1.2" } }, "required": [ "version", "creator", "pages", "entries" ] } }, "required": [ "log" ] } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "status": { "description": "Status code.", "type": "integer", "example": 400 }, "title": { "type": "string", "example": "Invalid url" } }, "required": [ "title", "detail", "status" ], "type": "object" } }, "message": { "type": "string" }, "status": { "description": "Status code.", "type": "integer", "example": 400 } }, "required": [ "message", "status", "errors" ] } } } }, "404": { "description": "Scan not found or in progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string", "example": "Queued" }, "status": { "description": "Status code.", "type": "integer", "example": 404 }, "title": { "type": "string", "example": "Scan is not finished yet." } }, "required": [ "title", "detail", "status" ], "type": "object" } }, "message": { "description": "Scan not found or in progress.", "type": "string", "example": "Scan is not finished yet." }, "status": { "description": "Status code.", "type": "integer", "example": 404 }, "task": { "type": "object", "properties": { "status": { "type": "string", "example": "Queued" }, "time": { "type": "string" }, "url": { "type": "string" }, "uuid": { "type": "string" }, "visibility": { "type": "string", "example": "public" } }, "required": [ "uuid", "url", "time", "status", "visibility" ] } }, "required": [ "message", "status", "errors", "task" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Scanner" ], "x-api-token-group": [ "URL Scanner Write", "URL Scanner Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "url-scanner.scans", "x-fern-sdk-method-name": "har", "x-forge-hidden": true } }, "/accounts/{account_id}/urlscanner/v2/responses/{response_id}": { "get": { "operationId": "urlscanner-get-response-v2", "summary": "Get raw response", "description": "Returns the raw response of the network request. Find the `response_id` in the `data.requests.response.hash`.", "parameters": [ { "name": "response_id", "in": "path", "description": "Response hash.", "required": true, "schema": { "description": "Response hash.", "type": "string" } }, { "name": "account_id", "in": "path", "description": "Account ID.", "required": true, "schema": { "description": "Account ID.", "type": "string" } } ], "responses": { "200": { "description": "Get the raw response by its hash.", "content": { "text/plain": { "schema": { "description": "Web resource or image.", "type": "string" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "status": { "description": "Status code.", "type": "integer", "example": 400 }, "title": { "type": "string", "example": "Invalid url" } }, "required": [ "title", "detail", "status" ], "type": "object" } }, "message": { "type": "string" }, "status": { "description": "Status code.", "type": "integer", "example": 400 } }, "required": [ "message", "status", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Scanner" ], "x-api-token-group": [ "URL Scanner Write", "URL Scanner Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "url-scanner.responses", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/urlscanner/v2/result/{scan_id}": { "get": { "operationId": "urlscanner-get-scan-v2", "summary": "Get URL scan", "description": "Get URL scan by uuid", "parameters": [ { "name": "scan_id", "in": "path", "description": "Scan UUID.", "required": true, "schema": { "description": "Scan UUID.", "type": "string", "format": "uuid" } }, { "name": "account_id", "in": "path", "description": "Account ID.", "required": true, "schema": { "description": "Account ID.", "type": "string" } } ], "responses": { "200": { "description": "Scan has finished. It may or may not have been successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "console": { "type": "array", "items": { "properties": { "message": { "type": "object", "properties": { "level": { "type": "string" }, "source": { "type": "string" }, "text": { "type": "string" }, "url": { "type": "string" } }, "required": [ "source", "level", "text", "url" ] } }, "required": [ "message" ], "type": "object" } }, "cookies": { "type": "array", "items": { "properties": { "domain": { "type": "string" }, "expires": { "type": "number" }, "httpOnly": { "type": "boolean" }, "name": { "type": "string" }, "path": { "type": "string" }, "priority": { "type": "string" }, "sameParty": { "type": "boolean" }, "secure": { "type": "boolean" }, "session": { "type": "boolean" }, "size": { "type": "number" }, "sourcePort": { "type": "number" }, "sourceScheme": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value", "domain", "path", "expires", "size", "httpOnly", "secure", "session", "priority", "sameParty", "sourceScheme", "sourcePort" ], "type": "object" } }, "globals": { "type": "array", "items": { "properties": { "prop": { "type": "string" }, "type": { "type": "string" } }, "required": [ "prop", "type" ], "type": "object" } }, "links": { "type": "array", "items": { "properties": { "href": { "type": "string" }, "text": { "type": "string" } }, "required": [ "href", "text" ], "type": "object" } }, "performance": { "type": "array", "items": { "properties": { "duration": { "type": "number" }, "entryType": { "type": "string" }, "name": { "type": "string" }, "startTime": { "type": "number" } }, "required": [ "name", "entryType", "startTime", "duration" ], "type": "object" } }, "requests": { "type": "array", "items": { "properties": { "request": { "type": "object", "properties": { "documentURL": { "type": "string" }, "frameId": { "type": "string" }, "hasUserGesture": { "type": "boolean" }, "initiator": { "type": "object", "properties": { "host": { "type": "string" }, "type": { "type": "string" }, "url": { "type": "string" } }, "required": [ "type", "url", "host" ] }, "loaderId": { "type": "string" }, "primaryRequest": { "type": "boolean" }, "redirectHasExtraInfo": { "type": "boolean" }, "redirectResponse": { "type": "object", "properties": { "charset": { "type": "string" }, "headers": { "type": "object" }, "mimeType": { "type": "string" }, "protocol": { "type": "string" }, "remoteIPAddress": { "type": "string" }, "remotePort": { "type": "number" }, "securityHeaders": { "type": "array", "items": { "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ], "type": "object" } }, "securityState": { "type": "string" }, "status": { "type": "number" }, "statusText": { "type": "string" }, "url": { "type": "string" } }, "required": [ "url", "status", "statusText", "mimeType", "charset", "remoteIPAddress", "remotePort", "protocol", "securityState", "securityHeaders" ] }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "initialPriority": { "type": "string" }, "isSameSite": { "type": "boolean" }, "method": { "type": "string" }, "mixedContentType": { "type": "string" }, "referrerPolicy": { "type": "string" }, "url": { "type": "string" } }, "required": [ "url", "method", "mixedContentType", "initialPriority", "referrerPolicy", "isSameSite" ] }, "requestId": { "type": "string" }, "type": { "type": "string" }, "wallTime": { "type": "number" } }, "required": [ "requestId", "documentURL", "request", "wallTime", "initiator", "redirectHasExtraInfo", "type", "hasUserGesture" ] }, "requests": { "type": "array", "items": { "properties": { "documentURL": { "type": "string" }, "frameId": { "type": "string" }, "hasUserGesture": { "type": "boolean" }, "initiator": { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ] }, "loaderId": { "type": "string" }, "redirectHasExtraInfo": { "type": "boolean" }, "request": { "type": "object", "properties": { "headers": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "initialPriority": { "type": "string" }, "isSameSite": { "type": "boolean" }, "method": { "type": "string" }, "mixedContentType": { "type": "string" }, "referrerPolicy": { "type": "string" }, "url": { "type": "string" } }, "required": [ "url", "method", "headers", "mixedContentType", "initialPriority", "referrerPolicy", "isSameSite" ] }, "requestId": { "type": "string" }, "type": { "type": "string" }, "wallTime": { "type": "number" } }, "required": [ "requestId", "loaderId", "frameId", "documentURL", "wallTime", "request", "type", "initiator", "hasUserGesture", "redirectHasExtraInfo" ], "type": "object" } }, "response": { "type": "object", "properties": { "asn": { "type": "object", "properties": { "asn": { "type": "string" }, "country": { "type": "string" }, "description": { "type": "string" }, "ip": { "type": "string" }, "name": { "type": "string" }, "org": { "type": "string" } }, "required": [ "ip", "asn", "country", "description", "name", "org" ] }, "contentAvailable": { "type": "boolean" }, "dataLength": { "type": "number" }, "encodedDataLength": { "type": "number" }, "geoip": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "country_name": { "type": "string" }, "geonameId": { "type": "string" }, "ll": { "type": "array", "items": { "type": "number" } }, "region": { "type": "string" } }, "required": [ "country", "region", "city", "ll", "country_name", "geonameId" ] }, "hasExtraInfo": { "type": "boolean" }, "hash": { "type": "string" }, "requestId": { "type": "string" }, "response": { "type": "object", "properties": { "charset": { "type": "string" }, "headers": { "type": "object" }, "mimeType": { "type": "string" }, "protocol": { "type": "string" }, "remoteIPAddress": { "type": "string" }, "remotePort": { "type": "number" }, "securityDetails": { "type": "object", "properties": { "certificateId": { "type": "number" }, "certificateTransparencyCompliance": { "type": "string" }, "cipher": { "type": "string" }, "encryptedClientHello": { "type": "boolean" }, "issuer": { "type": "string" }, "keyExchange": { "type": "string" }, "keyExchangeGroup": { "type": "string" }, "protocol": { "type": "string" }, "sanList": { "type": "array", "items": { "type": "string" } }, "serverSignatureAlgorithm": { "type": "number" }, "subjectName": { "type": "string" }, "validFrom": { "type": "number" }, "validTo": { "type": "number" } }, "required": [ "protocol", "keyExchange", "keyExchangeGroup", "cipher", "certificateId", "subjectName", "sanList", "issuer", "validFrom", "validTo", "certificateTransparencyCompliance", "serverSignatureAlgorithm", "encryptedClientHello" ] }, "securityHeaders": { "type": "array", "items": { "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ], "type": "object" } }, "securityState": { "type": "string" }, "status": { "type": "number" }, "statusText": { "type": "string" }, "url": { "type": "string" } }, "required": [ "url", "status", "statusText", "mimeType", "charset", "remoteIPAddress", "remotePort", "protocol", "securityState", "securityDetails", "securityHeaders" ] }, "size": { "type": "number" }, "type": { "type": "string" } }, "required": [ "encodedDataLength", "dataLength", "requestId", "type", "response", "hasExtraInfo", "size", "asn", "geoip" ] } }, "required": [ "request", "response" ], "type": "object" } } }, "required": [ "requests", "cookies", "console", "links", "globals", "performance" ] }, "lists": { "type": "object", "properties": { "asns": { "type": "array", "items": { "type": "string" } }, "certificates": { "type": "array", "items": { "properties": { "issuer": { "type": "string" }, "subjectName": { "type": "string" }, "validFrom": { "type": "number" }, "validTo": { "type": "number" } }, "required": [ "issuer", "subjectName", "validFrom", "validTo" ], "type": "object" } }, "continents": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "string" } }, "domains": { "type": "array", "items": { "type": "string" } }, "hashes": { "type": "array", "items": { "type": "string" } }, "ips": { "type": "array", "items": { "type": "string" } }, "linkDomains": { "type": "array", "items": { "type": "string" } }, "servers": { "type": "array", "items": { "type": "string" } }, "urls": { "type": "array", "items": { "type": "string" } } }, "required": [ "ips", "countries", "continents", "asns", "domains", "servers", "urls", "linkDomains", "certificates", "hashes" ] }, "meta": { "type": "object", "properties": { "processors": { "type": "object", "properties": { "agentReadiness": { "type": "object", "properties": { "checks": { "type": "object", "properties": { "botAccessControl": { "type": "object", "properties": { "contentSignals": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "pass" } }, "required": [ "status" ] }, "robotsTxtAiRules": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "pass" } }, "required": [ "status" ] }, "webBotAuth": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] } }, "required": [ "robotsTxtAiRules", "contentSignals", "webBotAuth" ] }, "commerce": { "type": "object", "properties": { "acp": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] }, "ap2": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] }, "mpp": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] }, "ucp": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] }, "x402": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] } }, "required": [ "ucp", "x402", "mpp", "acp", "ap2" ] }, "contentAccessibility": { "type": "object", "properties": { "markdownNegotiation": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] } }, "required": [ "markdownNegotiation" ] }, "discoverability": { "type": "object", "properties": { "dnsAid": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] }, "linkHeaders": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] }, "robotsTxt": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "pass" } }, "required": [ "status" ] }, "sitemap": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "pass" } }, "required": [ "status" ] } }, "required": [ "robotsTxt", "sitemap", "linkHeaders", "dnsAid" ] }, "discovery": { "type": "object", "properties": { "a2aAgentCard": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] }, "agentSkills": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] }, "apiCatalog": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] }, "ard": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] }, "authMd": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] }, "mcpServerCard": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] }, "oauthDiscovery": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] }, "oauthProtectedResource": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "fail" } }, "required": [ "status" ] }, "webMcp": { "type": "object", "properties": { "details": { "type": "object" }, "durationMs": { "type": "number" }, "evidence": { "type": "array", "items": { "properties": { "action": { "type": "string", "example": "fetch" }, "finding": { "type": "object", "properties": { "outcome": { "type": "string", "example": "positive" }, "summary": { "type": "string", "example": "Found valid robots.txt" } }, "required": [ "outcome", "summary" ] }, "label": { "type": "string", "example": "GET /robots.txt" }, "request": { "type": "object", "properties": { "headers": { "type": "object" }, "method": { "type": "string", "example": "GET" }, "url": { "type": "string", "example": "https://example.com/robots.txt" } }, "required": [ "url", "method" ] }, "response": { "type": "object", "properties": { "bodyPreview": { "type": "string" }, "bodySize": { "type": "integer" }, "headers": { "type": "object" }, "redirectedTo": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" } }, "required": [ "status", "statusText" ] } }, "required": [ "action", "label" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "string", "example": "neutral" } }, "required": [ "status" ] } }, "required": [ "apiCatalog", "oauthDiscovery", "oauthProtectedResource", "authMd", "mcpServerCard", "a2aAgentCard", "agentSkills", "webMcp", "ard" ] } }, "required": [ "discoverability", "contentAccessibility", "botAccessControl", "discovery", "commerce" ] }, "commerceSignals": { "type": "array", "items": { "type": "string" } }, "isCommerce": { "type": "boolean" }, "level": { "type": "integer", "example": 2 }, "levelName": { "type": "string", "example": "Bot-Aware" }, "nextLevel": { "type": "object", "properties": { "name": { "type": "string", "example": "Agent-Readable" }, "requirements": { "type": "array", "items": { "properties": { "check": { "type": "string", "example": "markdownNegotiation" }, "description": { "type": "string", "example": "Support content negotiation with Accept: text/markdown" }, "prompt": { "type": "string", "example": "Add markdown content negotiation support" }, "skillUrl": { "type": "string", "example": "https://agentready.cloudflare.com/.well-known/skills/markdown-negotiation" }, "specUrls": { "type": "array", "items": { "example": "https://markdownforagents.org", "type": "string" } } }, "required": [ "check", "description", "specUrls", "prompt", "skillUrl" ], "type": "object" } }, "target": { "type": "integer", "example": 3 } }, "required": [ "target", "name", "requirements" ] } }, "required": [ "level", "levelName", "checks" ] }, "asn": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "asn": { "type": "string" }, "country": { "type": "string" }, "description": { "type": "string" }, "ip": { "type": "string" }, "name": { "type": "string" } }, "required": [ "ip", "asn", "country", "description", "name" ], "type": "object" } } }, "required": [ "data" ] }, "dns": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "address": { "type": "string" }, "dnssec_valid": { "type": "boolean" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "address", "type", "dnssec_valid" ], "type": "object" } } }, "required": [ "data" ] }, "domainCategories": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "inherited": { "type": "object" }, "isPrimary": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "name", "isPrimary", "inherited" ], "type": "object" } } }, "required": [ "data" ] }, "geoip": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "geoip": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "country_name": { "type": "string" }, "ll": { "type": "array", "items": { "type": "number" } }, "region": { "type": "string" } }, "required": [ "country", "region", "city", "ll", "country_name" ] }, "ip": { "type": "string" } }, "required": [ "ip", "geoip" ], "type": "object" } } }, "required": [ "data" ] }, "phishing": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } } }, "required": [ "data" ] }, "phishing_v2": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" } } }, "required": [ "data" ] }, "radarRank": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "bucket": { "type": "string" }, "hostname": { "type": "string" }, "rank": { "type": "number" } }, "required": [ "hostname", "bucket" ], "type": "object" } } }, "required": [ "data" ] }, "robotsTxt": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "hash": { "type": "string" }, "rules": { "type": "object", "properties": { "*": { "type": "object", "properties": { "allow": { "type": "array", "items": { "type": "string" } }, "contentSignal": { "type": "object", "properties": { "ai-input": { "type": "string", "example": "no" }, "ai-train": { "type": "string", "example": "yes" }, "search": { "type": "string", "example": "yes" } } }, "crawlDelay": { "type": "number" }, "disallow": { "type": "array", "items": { "type": "string" } } }, "required": [ "allow", "disallow" ] } }, "required": [ "*" ] }, "sitemaps": { "type": "array", "items": { "type": "string" } } }, "required": [ "rules", "sitemaps" ], "type": "object" } } }, "required": [ "data" ] }, "urlCategories": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "content": { "items": { "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "super_category_id": { "type": "number" } }, "required": [ "id", "name", "super_category_id" ], "type": "object" }, "type": "array" }, "inherited": { "type": "object", "properties": { "content": { "items": { "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "super_category_id": { "type": "number" } }, "required": [ "id", "name", "super_category_id" ], "type": "object" }, "type": "array" }, "from": { "type": "string" }, "risks": { "type": "array", "items": { "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "super_category_id": { "type": "number" } }, "required": [ "id", "name", "super_category_id" ], "type": "object" } } }, "required": [ "from", "content", "risks" ] }, "name": { "type": "string" }, "risks": { "type": "array", "items": { "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "super_category_id": { "type": "number" } }, "required": [ "id", "name", "super_category_id" ], "type": "object" } } }, "required": [ "name", "content", "risks", "inherited" ], "type": "object" } } }, "required": [ "data" ] }, "wappa": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "app": { "type": "string" }, "categories": { "type": "array", "items": { "properties": { "name": { "type": "string" }, "priority": { "type": "number" } }, "required": [ "name", "priority" ], "type": "object" } }, "confidence": { "type": "array", "items": { "properties": { "confidence": { "type": "number" }, "name": { "type": "string" }, "pattern": { "type": "string" }, "patternType": { "type": "string" } }, "required": [ "confidence", "pattern", "patternType", "name" ], "type": "object" } }, "confidenceTotal": { "type": "number" }, "icon": { "type": "string" }, "website": { "type": "string" } }, "required": [ "confidence", "confidenceTotal", "app", "icon", "website", "categories" ], "type": "object" } } }, "required": [ "data" ] } }, "required": [ "geoip", "asn", "wappa", "domainCategories", "dns", "radarRank", "phishing" ] } }, "required": [ "processors" ] }, "page": { "type": "object", "properties": { "apexDomain": { "type": "string" }, "asn": { "type": "string" }, "asnname": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "domain": { "type": "string" }, "ip": { "type": "string" }, "mimeType": { "type": "string" }, "screenshot": { "type": "object", "properties": { "dhash": { "type": "string" }, "mm3Hash": { "type": "number" }, "name": { "type": "string" }, "phash": { "type": "string" } }, "required": [ "phash", "dhash", "mm3Hash", "name" ] }, "server": { "type": "string" }, "status": { "type": "string", "example": "200" }, "title": { "type": "string" }, "tlsAgeDays": { "type": "number" }, "tlsIssuer": { "type": "string" }, "tlsValidDays": { "type": "number" }, "tlsValidFrom": { "type": "string" }, "url": { "type": "string" } }, "required": [ "asn", "asnname", "city", "country", "domain", "ip", "server", "url", "mimeType", "apexDomain", "status", "title", "tlsIssuer", "tlsValidFrom", "tlsAgeDays", "tlsValidDays" ] }, "scanner": { "type": "object", "properties": { "colo": { "type": "string" }, "country": { "type": "string" } }, "required": [ "country", "colo" ] }, "stats": { "type": "object", "properties": { "IPv6Percentage": { "type": "number" }, "domainStats": { "type": "array", "items": { "properties": { "count": { "type": "number" }, "countries": { "type": "array", "items": { "type": "string" } }, "domain": { "type": "string" }, "encodedSize": { "type": "number" }, "index": { "type": "number" }, "initiators": { "type": "array", "items": { "type": "string" } }, "ips": { "type": "array", "items": { "type": "string" } }, "redirects": { "type": "number" }, "size": { "type": "number" } }, "required": [ "count", "ips", "domain", "size", "encodedSize", "countries", "index", "initiators", "redirects" ], "type": "object" } }, "ipStats": { "type": "array", "items": { "properties": { "asn": { "type": "object", "properties": { "asn": { "type": "string" }, "country": { "type": "string" }, "description": { "type": "string" }, "ip": { "type": "string" }, "name": { "type": "string" }, "org": { "type": "string" } }, "required": [ "ip", "asn", "country", "description", "name", "org" ] }, "count": { "type": "number" }, "countries": { "type": "array", "items": { "type": "string" } }, "domains": { "type": "array", "items": { "type": "string" } }, "encodedSize": { "type": "number" }, "geoip": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "country_name": { "type": "string" }, "ll": { "type": "array", "items": { "type": "number" } }, "region": { "type": "string" } }, "required": [ "country", "region", "city", "ll", "country_name" ] }, "index": { "type": "number" }, "ip": { "type": "string" }, "ipv6": { "type": "boolean" }, "redirects": { "type": "number" }, "requests": { "type": "number" }, "size": { "type": "number" } }, "required": [ "requests", "domains", "ip", "size", "encodedSize", "countries", "index", "ipv6", "redirects", "geoip", "asn" ], "type": "object" } }, "malicious": { "type": "number" }, "protocolStats": { "type": "array", "items": { "properties": { "count": { "type": "number" }, "countries": { "type": "array", "items": { "type": "string" } }, "encodedSize": { "type": "number" }, "ips": { "type": "array", "items": { "type": "string" } }, "protocol": { "type": "string" }, "size": { "type": "number" } }, "required": [ "count", "size", "encodedSize", "ips", "countries", "protocol" ], "type": "object" } }, "resourceStats": { "type": "array", "items": { "properties": { "compression": { "type": "number" }, "count": { "type": "number" }, "countries": { "type": "array", "items": { "type": "string" } }, "encodedSize": { "type": "number" }, "ips": { "type": "array", "items": { "type": "string" } }, "percentage": { "type": "number" }, "size": { "type": "number" }, "type": { "type": "string" } }, "required": [ "count", "size", "encodedSize", "ips", "countries", "compression", "percentage", "type" ], "type": "object" } }, "securePercentage": { "type": "number" }, "secureRequests": { "type": "number" }, "serverStats": { "type": "array", "items": { "properties": { "count": { "type": "number" }, "countries": { "type": "array", "items": { "type": "string" } }, "encodedSize": { "type": "number" }, "ips": { "type": "array", "items": { "type": "string" } }, "server": { "type": "string" }, "size": { "type": "number" } }, "required": [ "count", "size", "encodedSize", "ips", "countries", "server" ], "type": "object" } }, "tlsStats": { "type": "array", "items": { "properties": { "count": { "type": "number" }, "countries": { "type": "array", "items": { "type": "string" } }, "encodedSize": { "type": "number" }, "ips": { "type": "array", "items": { "type": "string" } }, "protocols": { "type": "object", "properties": { "TLS 1.3 / AES_128_GCM": { "type": "number" } }, "required": [ "TLS 1.3 / AES_128_GCM" ] }, "securityState": { "type": "string" }, "size": { "type": "number" } }, "required": [ "count", "size", "encodedSize", "ips", "countries", "protocols", "securityState" ], "type": "object" } }, "totalLinks": { "type": "number" }, "uniqASNs": { "type": "number" }, "uniqCountries": { "type": "number" } }, "required": [ "IPv6Percentage", "domainStats", "ipStats", "malicious", "protocolStats", "resourceStats", "secureRequests", "tlsStats", "serverStats", "securePercentage", "totalLinks", "uniqCountries", "uniqASNs" ] }, "task": { "type": "object", "properties": { "apexDomain": { "type": "string" }, "domURL": { "type": "string" }, "domain": { "type": "string" }, "method": { "type": "string" }, "options": { "type": "object", "properties": { "customHeaders": { "description": "Custom headers set.", "type": "object" }, "screenshotsResolutions": { "type": "array", "items": { "type": "string" } } } }, "reportURL": { "type": "string" }, "screenshotURL": { "type": "string" }, "source": { "type": "string" }, "success": { "type": "boolean" }, "time": { "type": "string" }, "url": { "type": "string" }, "uuid": { "type": "string" }, "visibility": { "type": "string" } }, "required": [ "uuid", "url", "time", "visibility", "source", "method", "domain", "apexDomain", "reportURL", "screenshotURL", "domURL", "options", "success" ] }, "verdicts": { "type": "object", "properties": { "overall": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "string" } }, "hasVerdicts": { "type": "boolean" }, "malicious": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "malicious", "hasVerdicts", "categories", "tags" ] } }, "required": [ "overall" ] } }, "required": [ "data", "page", "lists", "meta", "scanner", "stats", "task", "verdicts" ] } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "status": { "description": "Status code.", "type": "integer", "example": 400 }, "title": { "type": "string", "example": "Invalid url" } }, "required": [ "title", "detail", "status" ], "type": "object" } }, "message": { "type": "string" }, "status": { "description": "Status code.", "type": "integer", "example": 400 } }, "required": [ "message", "status", "errors" ] } } } }, "404": { "description": "Scan not found or in progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string", "example": "Queued" }, "status": { "description": "Status code.", "type": "integer", "example": 404 }, "title": { "type": "string", "example": "Scan is not finished yet." } }, "required": [ "title", "detail", "status" ], "type": "object" } }, "message": { "description": "Scan not found or in progress.", "type": "string", "example": "Scan is not finished yet." }, "status": { "description": "Status code.", "type": "integer", "example": 404 }, "task": { "type": "object", "properties": { "status": { "type": "string", "example": "Queued" }, "time": { "type": "string" }, "url": { "type": "string" }, "uuid": { "type": "string" }, "visibility": { "type": "string", "example": "public" } }, "required": [ "uuid", "url", "time", "status", "visibility" ] } }, "required": [ "message", "status", "errors", "task" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Scanner" ], "x-api-token-group": [ "URL Scanner Write", "URL Scanner Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "url-scanner.scans", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/urlscanner/v2/scan": { "post": { "operationId": "urlscanner-create-scan-v2", "summary": "Create URL Scan", "description": "Submit a URL to scan. Check limits at https://developers.cloudflare.com/security-center/investigate/scan-limits/.", "parameters": [ { "name": "account_id", "in": "path", "description": "Account ID.", "required": true, "schema": { "description": "Account ID.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "agentReadiness": { "description": "Enable agent readiness checks.", "type": "boolean" }, "country": { "description": "Country to geo egress from", "type": "string", "enum": [ "AF", "AL", "DZ", "AD", "AO", "AG", "AR", "AM", "AU", "AT", "AZ", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BR", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CO", "KM", "CG", "CR", "CI", "HR", "CU", "CY", "CZ", "CD", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FJ", "FI", "FR", "GA", "GE", "DE", "GH", "GR", "GL", "GD", "GT", "GN", "GW", "GY", "HT", "HN", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IL", "IT", "JM", "JP", "JO", "KZ", "KE", "KI", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MR", "MU", "MX", "FM", "MD", "MC", "MN", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NZ", "NI", "NE", "NG", "KP", "MK", "NO", "OM", "PK", "PS", "PA", "PG", "PY", "PE", "PH", "PL", "PT", "QA", "RO", "RU", "RW", "SH", "KN", "LC", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SK", "SI", "SB", "SO", "ZA", "KR", "SS", "ES", "LK", "SD", "SR", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "BS", "GM", "TL", "TG", "TO", "TT", "TN", "TR", "TM", "UG", "UA", "AE", "GB", "US", "UY", "UZ", "VU", "VE", "VN", "YE", "ZM", "ZW" ] }, "customHeaders": { "description": "Set custom headers.", "type": "object", "additionalProperties": { "type": "string" } }, "customagent": { "type": "string", "maxLength": 4096 }, "referer": { "type": "string", "maxLength": 4096 }, "screenshotsResolutions": { "description": "Take multiple screenshots targeting different device types.", "type": "array", "items": { "default": "desktop", "description": "Device resolutions.", "enum": [ "desktop", "mobile", "tablet" ], "type": "string" }, "default": [ "desktop" ] }, "url": { "type": "string", "example": "https://www.example.com" }, "visibility": { "description": "The option `Public` means it will be included in listings like recent scans and search results. `Unlisted` means it will not be included in the aforementioned listings, users will need to have the scan's ID to access it. A a scan will be automatically marked as unlisted if it fails, if it contains potential PII or other sensitive material.", "type": "string", "default": "Public", "enum": [ "Public", "Unlisted" ] } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Scan request accepted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "api": { "description": "URL to api report.", "type": "string" }, "message": { "type": "string", "example": "Submission successful" }, "options": { "type": "object", "properties": { "useragent": { "type": "string" } } }, "result": { "description": "Public URL to report.", "type": "string" }, "url": { "description": "Canonical form of submitted URL. Use this if you want to later search by URL.", "type": "string", "x-auditable": true }, "uuid": { "description": "Scan ID.", "type": "string", "format": "uuid", "x-auditable": true }, "visibility": { "description": "Submitted visibility status.", "type": "string", "example": "public", "enum": [ "public", "unlisted" ] } }, "required": [ "message", "uuid", "result", "api", "visibility", "url" ] } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "status": { "description": "Status code.", "type": "integer", "example": 400 }, "title": { "type": "string", "example": "Invalid url" } }, "required": [ "title", "detail", "status" ], "type": "object" } }, "message": { "type": "string" }, "status": { "description": "Status code.", "type": "integer", "example": 400 } }, "required": [ "message", "status", "errors" ] } } } }, "409": { "description": "Scan request denied: hostname was recently scanned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "example": "Scan request denied: hostname was recently scanned" }, "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string", "example": "DNS Error - Could not resolve domain." }, "status": { "type": "number", "example": 400 }, "title": { "type": "string", "example": "DNS Error - Could not resolve domain." } }, "required": [ "title", "detail", "status" ], "type": "object" } }, "message": { "type": "string", "example": "Scan prevented ..." }, "status": { "type": "number", "example": 409 } }, "required": [ "message", "status", "errors" ] } } } }, "429": { "description": "Scan request denied: rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string" }, "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string", "example": "DNS Error - Could not resolve domain." }, "status": { "type": "number", "example": 400 }, "title": { "type": "string", "example": "DNS Error - Could not resolve domain." } }, "required": [ "title", "detail", "status" ], "type": "object" } }, "message": { "type": "string" }, "status": { "type": "number", "example": 429 } }, "required": [ "message", "status", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Scanner" ], "x-api-token-group": [ "URL Scanner Write", "URL Scanner Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "url-scanner.scans", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/urlscanner/v2/screenshots/{scan_id}.png": { "get": { "operationId": "urlscanner-get-scan-screenshot-v2", "summary": "Get screenshot", "description": "Get scan's screenshot by resolution (desktop/mobile/tablet).", "parameters": [ { "name": "scan_id", "in": "path", "description": "Scan UUID.", "required": true, "schema": { "description": "Scan UUID.", "type": "string", "format": "uuid" } }, { "name": "account_id", "in": "path", "description": "Account ID.", "required": true, "schema": { "description": "Account ID.", "type": "string" } }, { "name": "resolution", "in": "query", "description": "Target device type.", "schema": { "description": "Target device type.", "type": "string", "default": "desktop", "enum": [ "desktop", "mobile", "tablet" ] } } ], "responses": { "200": { "description": "Returns the scan's requested screenshot.", "content": { "image/png": { "schema": { "description": "PNG Image.", "type": "string" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "status": { "description": "Status code.", "type": "integer", "example": 400 }, "title": { "type": "string", "example": "Invalid url" } }, "required": [ "title", "detail", "status" ], "type": "object" } }, "message": { "type": "string" }, "status": { "description": "Status code.", "type": "integer", "example": 400 } }, "required": [ "message", "status", "errors" ] } } } }, "404": { "description": "Scan not found or in progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string", "example": "Queued" }, "status": { "description": "Status code.", "type": "integer", "example": 404 }, "title": { "type": "string", "example": "Scan is not finished yet." } }, "required": [ "title", "detail", "status" ], "type": "object" } }, "message": { "description": "Scan not found or in progress.", "type": "string", "example": "Scan is not finished yet." }, "status": { "description": "Status code.", "type": "integer", "example": 404 }, "task": { "type": "object", "properties": { "status": { "type": "string", "example": "Queued" }, "time": { "type": "string" }, "url": { "type": "string" }, "uuid": { "type": "string" }, "visibility": { "type": "string", "example": "public" } }, "required": [ "uuid", "url", "time", "status", "visibility" ] } }, "required": [ "message", "status", "errors", "task" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Scanner" ], "x-api-token-group": [ "URL Scanner Write", "URL Scanner Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "url-scanner.scans", "x-fern-sdk-method-name": "screenshot", "x-forge-hidden": true } }, "/accounts/{account_id}/urlscanner/v2/search": { "get": { "operationId": "urlscanner-search-scans-v2", "summary": "Search URL scans", "description": "Use a subset of ElasticSearch Query syntax to filter scans. Some example queries:

- 'path:\"/bundles/jquery.js\"': Searches for scans who requested resources with the given path.
- 'page.asn:AS24940 AND hash:xxx': Websites hosted in AS24940 where a resource with the given hash was downloaded.
- 'page.domain:microsoft* AND verdicts.malicious:true AND NOT page.domain:microsoft.com': malicious scans whose hostname starts with \"microsoft\".
- 'apikey:me AND date:[2025-01 TO 2025-02]': my scans from 2025 January to 2025 February.", "parameters": [ { "name": "account_id", "in": "path", "description": "Account ID.", "required": true, "schema": { "description": "Account ID.", "type": "string" } }, { "name": "size", "in": "query", "description": "Limit the number of objects in the response.", "schema": { "description": "Limit the number of objects in the response.", "type": "integer", "example": 100 } }, { "name": "q", "in": "query", "description": "Filter scans", "schema": { "description": "Filter scans", "type": "string" } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "properties": { "_id": { "type": "string", "example": "9626f773-9ffb-4cfb-89d3-30b120fc8011" }, "page": { "type": "object", "properties": { "asn": { "type": "string", "example": "AS15133" }, "country": { "type": "string", "example": "US" }, "ip": { "type": "string", "example": "93.184.215.14" }, "url": { "type": "string", "example": "https://example.com" } }, "required": [ "country", "ip", "url", "asn" ] }, "result": { "type": "string", "example": "https://radar.clouflare.com/scan/9626f773-9ffb-4cfb-89d3-30b120fc8011" }, "stats": { "type": "object", "properties": { "dataLength": { "type": "number", "example": 2512 }, "requests": { "type": "number", "example": 2 }, "uniqCountries": { "type": "number", "example": 1 }, "uniqIPs": { "type": "number", "example": 1 } }, "required": [ "uniqIPs", "uniqCountries", "dataLength", "requests" ] }, "task": { "type": "object", "properties": { "time": { "type": "string", "example": "2024-09-30T23:54:02.881Z" }, "url": { "type": "string", "example": "https://example.com" }, "uuid": { "type": "string", "example": "9626f773-9ffb-4cfb-89d3-30b120fc8011" }, "visibility": { "type": "string", "example": "public" } }, "required": [ "visibility", "time", "uuid", "url" ] }, "verdicts": { "type": "object", "properties": { "malicious": { "type": "boolean" } }, "required": [ "malicious" ] } }, "required": [ "task", "stats", "page", "verdicts", "_id", "result" ], "type": "object" } } }, "required": [ "results" ] } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "status": { "description": "Status code.", "type": "integer", "example": 400 }, "title": { "type": "string", "example": "Invalid url" } }, "required": [ "title", "detail", "status" ], "type": "object" } }, "message": { "type": "string" }, "status": { "description": "Status code.", "type": "integer", "example": 400 } }, "required": [ "message", "status", "errors" ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Scanner" ], "x-api-token-group": [ "URL Scanner Write", "URL Scanner Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "url-scanner.scans", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/vectorize/indexes": { "get": { "operationId": "vectorize-(-deprecated)-list-vectorize-indexes", "summary": "List Vectorize Indexes (Deprecated)", "description": "Returns a list of Vectorize Indexes", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } } ], "responses": { "200": { "description": "List Vectorize Index Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/vectorize_create-index-response" } } } } ] } } } }, "4XX": { "description": "List Vectorize Index Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize Beta (Deprecated)" ], "x-api-token-group": [ "Vectorize Write", "Vectorize Read" ], "x-cfDeprecation": { "description": "This endpoint is deprecated in favor of the GET `/accounts/{account_id}/vectorize/v2/indexes` endpoint.", "display": true, "id": "vectorize_list_index_deprecation" }, "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.edge.vectorize.index.list" ] }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "vectorize.deprecated-indexes", "x-fern-sdk-method-name": "list", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" } }, "post": { "operationId": "vectorize-(-deprecated)-create-vectorize-index", "summary": "Create Vectorize Index (Deprecated)", "description": "Creates and returns a new Vectorize Index.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorize_create-index-request" } } } }, "responses": { "200": { "description": "Create Vectorize Index Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_create-index-response" } } } ] } } } }, "4XX": { "description": "Create Vectorize Index Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize Beta (Deprecated)" ], "x-api-token-group": [ "Vectorize Write" ], "x-cfDeprecation": { "description": "This endpoint is deprecated in favor of the POST `/accounts/{account_id}/vectorize/v2/indexes` endpoint.", "display": true, "id": "vectorize_create_index_deprecation" }, "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.edge.vectorize.index.create" ] }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "vectorize.deprecated-indexes", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" } } }, "/accounts/{account_id}/vectorize/indexes/{index_name}": { "delete": { "operationId": "vectorize-(-deprecated)-delete-vectorize-index", "summary": "Delete Vectorize Index (Deprecated)", "description": "Deletes the specified Vectorize Index.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "responses": { "200": { "description": "Delete Vectorize Index Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } } } ] } } } }, "4XX": { "description": "Delete Vectorize Index Failure", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize Beta (Deprecated)" ], "x-api-token-group": [ "Vectorize Write" ], "x-cfDeprecation": { "description": "This endpoint is deprecated in favor of the DELETE `/accounts/{account_id}/vectorize/v2/indexes/{index_name}` endpoint.", "display": true, "id": "vectorize_delete_index_deprecation" }, "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.edge.vectorize.index.delete" ] }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "vectorize.deprecated-indexes", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" } }, "get": { "operationId": "vectorize-(-deprecated)-get-vectorize-index", "summary": "Get Vectorize Index (Deprecated)", "description": "Returns the specified Vectorize Index.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "responses": { "200": { "description": "Get Vectorize Index Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_create-index-response" } } } ] } } } }, "4XX": { "description": "Get Vectorize Index Failure", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize Beta (Deprecated)" ], "x-api-token-group": [ "Vectorize Write", "Vectorize Read" ], "x-cfDeprecation": { "description": "This endpoint is deprecated in favor of the GET `/accounts/{account_id}/vectorize/v2/indexes/{index_name}` endpoint.", "display": true, "id": "vectorize_get_index_deprecation" }, "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.edge.vectorize.index.read" ] }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "vectorize.deprecated-indexes", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" } }, "put": { "operationId": "vectorize-(-deprecated)-update-vectorize-index", "summary": "Update Vectorize Index (Deprecated)", "description": "Updates and returns the specified Vectorize Index.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorize_update-index-request" } } } }, "responses": { "200": { "description": "Update Vectorize Index Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_create-index-response" } } } ] } } } }, "4XX": { "description": "Update Vectorize Index Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize Beta (Deprecated)" ], "x-api-token-group": [ "Vectorize Write" ], "x-cfDeprecation": { "description": "This endpoint has been deprecated and will soon be removed.", "display": true, "id": "vectorize_update_index_deprecation" }, "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.edge.vectorize.index.update" ] }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "vectorize.deprecated-indexes", "x-fern-sdk-method-name": "update", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" } } }, "/accounts/{account_id}/vectorize/indexes/{index_name}/delete-by-ids": { "post": { "operationId": "vectorize-(-deprecated)-delete-vectors-by-id", "summary": "Delete Vectors By Identifier (Deprecated)", "description": "Delete a set of vectors from an index by their vector identifiers.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorize_index-delete-vectors-by-id-request" } } } }, "responses": { "200": { "description": "Delete Vector Identifiers Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_index-delete-vectors-by-id-response" } } } ] } } } }, "4XX": { "description": "Delete Vector Identifiers Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize Beta (Deprecated)" ], "x-api-token-group": [ "Vectorize Write" ], "x-cfDeprecation": { "description": "This endpoint is deprecated in favor of the POST `/accounts/{account_id}/vectorize/v2/indexes/{index_name}/delete_by_ids` endpoint.", "display": true, "id": "vectorize_delete_by_ids_deprecation" }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "vectorize.deprecated-indexes.delete-by.ids", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" } } }, "/accounts/{account_id}/vectorize/indexes/{index_name}/get-by-ids": { "post": { "operationId": "vectorize-(-deprecated)-get-vectors-by-id", "summary": "Get Vectors By Identifier (Deprecated)", "description": "Get a set of vectors from an index by their vector identifiers.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorize_index-get-vectors-by-id-request" } } } }, "responses": { "200": { "description": "Get Vectors By Identifier Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_index-get-vectors-by-id-response" } } } ] } } } }, "4XX": { "description": "Get Vectors By Identifier Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize Beta (Deprecated)" ], "x-api-token-group": [ "Vectorize Write", "Vectorize Read" ], "x-cfDeprecation": { "description": "This endpoint is deprecated in favor of the POST `/accounts/{account_id}/vectorize/v2/indexes/{index_name}/get_by_ids` endpoint.", "display": true, "id": "vectorize_get_by_ids_deprecation" }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "vectorize.deprecated-indexes.get-by.ids", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" } } }, "/accounts/{account_id}/vectorize/indexes/{index_name}/insert": { "post": { "operationId": "vectorize-(-deprecated)-insert-vector", "summary": "Insert Vectors (Deprecated)", "description": "Inserts vectors into the specified index and returns the count of the vectors successfully inserted.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "requestBody": { "required": true, "content": { "application/x-ndjson": { "schema": { "description": "ndjson file containing vectors to insert.", "type": "string", "format": "binary", "example": "@/path/to/vectors.ndjson" } } } }, "responses": { "200": { "description": "Insert Vectors Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_index-insert-response" } } } ] } } } }, "4XX": { "description": "Insert Vectors Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize Beta (Deprecated)" ], "x-api-token-group": [ "Vectorize Write" ], "x-cfDeprecation": { "description": "This endpoint is deprecated in favor of the POST `/accounts/{account_id}/vectorize/v2/indexes/{index_name}/insert` endpoint.", "display": true, "id": "vectorize_insert_deprecation" }, "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.edge.vectorize.index.update" ] }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "vectorize.deprecated-indexes.insert", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" } } }, "/accounts/{account_id}/vectorize/indexes/{index_name}/query": { "post": { "operationId": "vectorize-(-deprecated)-query-vector", "summary": "Query Vectors (Deprecated)", "description": "Finds vectors closest to a given vector in an index.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorize_index-query-request" } } } }, "responses": { "200": { "description": "Query Vectors Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_index-query-response" } } } ] } } } }, "4XX": { "description": "Query Vectors Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize Beta (Deprecated)" ], "x-api-token-group": [ "Vectorize Write", "Vectorize Read" ], "x-cfDeprecation": { "description": "This endpoint is deprecated in favor of the POST `/accounts/{account_id}/vectorize/v2/indexes/{index_name}/query` endpoint.", "display": true, "id": "vectorize_query_deprecation" }, "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.edge.vectorize.index.read" ] }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "vectorize.deprecated-indexes.query", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" } } }, "/accounts/{account_id}/vectorize/indexes/{index_name}/upsert": { "post": { "operationId": "vectorize-(-deprecated)-upsert-vector", "summary": "Upsert Vectors (Deprecated)", "description": "Upserts vectors into the specified index, creating them if they do not exist and returns the count of values and ids successfully inserted.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "requestBody": { "required": true, "content": { "application/x-ndjson": { "schema": { "description": "ndjson file containing vectors to upsert.", "type": "string", "format": "binary", "example": "@/path/to/vectors.ndjson" } } } }, "responses": { "200": { "description": "Insert Vectors Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_index-upsert-response" } } } ] } } } }, "4XX": { "description": "Insert Vectors Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize Beta (Deprecated)" ], "x-api-token-group": [ "Vectorize Write" ], "x-cfDeprecation": { "description": "This endpoint is deprecated in favor of the POST `/accounts/{account_id}/vectorize/v2/indexes/{index_name}/upsert` endpoint.", "display": true, "id": "vectorize_upsert_deprecation" }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "vectorize.deprecated-indexes.upsert", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" } } }, "/accounts/{account_id}/vectorize/v2/indexes": { "get": { "operationId": "vectorize-list-vectorize-indexes", "summary": "List Vectorize Indexes", "description": "Returns a list of Vectorize Indexes", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } } ], "responses": { "200": { "description": "List Vectorize Index Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/vectorize_create-index-response" } } } } ] } } } }, "4XX": { "description": "List Vectorize Index Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize" ], "x-api-token-group": [ "Vectorize Write", "Vectorize Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.edge.vectorize.index.list" ] }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "vectorize", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "vectorize-create-vectorize-index", "summary": "Create Vectorize Index", "description": "Creates and returns a new Vectorize Index.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorize_create-index-request" } } } }, "responses": { "200": { "description": "Create Vectorize Index Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_create-index-response" } } } ] } } } }, "4XX": { "description": "Create Vectorize Index Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize" ], "x-api-token-group": [ "Vectorize Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.edge.vectorize.index.create" ] }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "vectorize", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/vectorize/v2/indexes/{index_name}": { "delete": { "operationId": "vectorize-delete-vectorize-index", "summary": "Delete Vectorize Index", "description": "Deletes the specified Vectorize Index.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "responses": { "200": { "description": "Delete Vectorize Index Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } } } ] } } } }, "4XX": { "description": "Delete Vectorize Index Failure", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize" ], "x-api-token-group": [ "Vectorize Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.edge.vectorize.index.delete" ] }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "vectorize", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "vectorize-get-vectorize-index", "summary": "Get Vectorize Index", "description": "Returns the specified Vectorize Index.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "responses": { "200": { "description": "Get Vectorize Index Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_create-index-response" } } } ] } } } }, "4XX": { "description": "Get Vectorize Index Failure", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize" ], "x-api-token-group": [ "Vectorize Write", "Vectorize Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.edge.vectorize.index.read" ] }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "vectorize", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/vectorize/v2/indexes/{index_name}/delete_by_ids": { "post": { "operationId": "vectorize-delete-vectors-by-id", "summary": "Delete Vectors By Identifier", "description": "Delete a set of vectors from an index by their vector identifiers.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorize_index-delete-vectors-by-id-request" } } } }, "responses": { "200": { "description": "Delete Vector Identifiers Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_index-delete-vectors-by-id-v2-response" } } } ] } } } }, "4XX": { "description": "Delete Vector Identifiers Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize" ], "x-api-token-group": [ "Vectorize Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.edge.vectorize.index.delete" ] }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "vectorize", "x-fern-sdk-method-name": "delete-by-ids", "x-forge-hidden": true } }, "/accounts/{account_id}/vectorize/v2/indexes/{index_name}/get_by_ids": { "post": { "operationId": "vectorize-get-vectors-by-id", "summary": "Get Vectors By Identifier", "description": "Get a set of vectors from an index by their vector identifiers.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorize_index-get-vectors-by-id-request" } } } }, "responses": { "200": { "description": "Get Vectors By Identifier Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_index-get-vectors-by-id-response" } } } ] } } } }, "4XX": { "description": "Get Vectors By Identifier Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize" ], "x-api-token-group": [ "Vectorize Write", "Vectorize Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "vectorize", "x-fern-sdk-method-name": "get-by-ids", "x-forge-hidden": true } }, "/accounts/{account_id}/vectorize/v2/indexes/{index_name}/info": { "get": { "operationId": "vectorize-index-info", "summary": "Get Vectorize Index Info", "description": "Get information about a vectorize index.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "responses": { "200": { "description": "Get Vectorize Index Info Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_index-info-response" } } } ] } } } }, "4XX": { "description": "Get Vectorize Index Info Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize" ], "x-api-token-group": [ "Vectorize Write", "Vectorize Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.edge.vectorize.index.read" ] }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "vectorize", "x-fern-sdk-method-name": "info", "x-forge-hidden": true } }, "/accounts/{account_id}/vectorize/v2/indexes/{index_name}/insert": { "post": { "operationId": "vectorize-insert-vector", "summary": "Insert Vectors", "description": "Inserts vectors into the specified index and returns a mutation id corresponding to the vectors enqueued for insertion.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } }, { "name": "unparsable-behavior", "in": "query", "schema": { "description": "Behavior for ndjson parse failures.", "type": "string", "enum": [ "error", "discard" ] } } ], "requestBody": { "required": true, "content": { "application/x-ndjson": { "schema": { "description": "ndjson file containing vectors to insert.", "type": "string", "format": "binary", "example": "@/path/to/vectors.ndjson" } } } }, "responses": { "200": { "description": "Insert Vectors Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_index-insert-v2-response" } } } ] } } } }, "4XX": { "description": "Insert Vectors Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize" ], "x-api-token-group": [ "Vectorize Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "vectorize", "x-fern-sdk-method-name": "insert", "x-forge-hidden": true } }, "/accounts/{account_id}/vectorize/v2/indexes/{index_name}/list": { "get": { "operationId": "vectorize-list-vectors", "summary": "List Vectors", "description": "Returns a paginated list of vector identifiers from the specified index.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } }, { "name": "count", "in": "query", "schema": { "description": "Maximum number of vectors to return", "type": "integer", "example": 50, "default": 100, "maximum": 1000, "minimum": 1 } }, { "name": "cursor", "in": "query", "schema": { "description": "Cursor for pagination to get the next page of results", "type": "string", "example": "suUTaDY5PFUiRweVccnzyt9n75suNPbXHPshvCzue5mHjtj7Letjvzlza9eGj099" } } ], "responses": { "200": { "description": "List Vectors Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_index-list-vectors-response" } } } ] } } } }, "4XX": { "description": "List Vectors Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize" ], "x-api-token-group": [ "Vectorize Write", "Vectorize Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.edge.vectorize.index.read" ] }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "vectorize", "x-fern-sdk-method-name": "list-vectors", "x-forge-hidden": true } }, "/accounts/{account_id}/vectorize/v2/indexes/{index_name}/metadata_index/create": { "post": { "operationId": "vectorize-create-metadata-index", "summary": "Create Metadata Index", "description": "Enable metadata filtering based on metadata property. Limited to 10 properties.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorize_create-metadata-index-request" } } } }, "responses": { "200": { "description": "Create Metadata Index Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_create-metadata-index-response" } } } ] } } } }, "4XX": { "description": "Create Metadata Index Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize" ], "x-api-token-group": [ "Vectorize Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.edge.vectorize.index.create" ] }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "vectorize.metadata-index", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/vectorize/v2/indexes/{index_name}/metadata_index/delete": { "post": { "operationId": "vectorize-delete-metadata-index", "summary": "Delete Metadata Index", "description": "Allow Vectorize to delete the specified metadata index.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorize_delete-metadata-index-request" } } } }, "responses": { "200": { "description": "Delete Metadata Index Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_delete-metadata-index-response" } } } ] } } } }, "4XX": { "description": "Delete Metadata Index Failure", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize" ], "x-api-token-group": [ "Vectorize Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.edge.vectorize.index.delete" ] }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "vectorize.metadata-index", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes a metadata index destructively." } }, "/accounts/{account_id}/vectorize/v2/indexes/{index_name}/metadata_index/list": { "get": { "operationId": "vectorize-list-metadata-indexes", "summary": "List Metadata Indexes", "description": "List Metadata Indexes for the specified Vectorize Index.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "responses": { "200": { "description": "List Metadata Index Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_list-metadata-index-response" } } } ] } } } }, "4XX": { "description": "List Metadata Index Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize" ], "x-api-token-group": [ "Vectorize Write", "Vectorize Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "vectorize.metadata-index", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/vectorize/v2/indexes/{index_name}/query": { "post": { "operationId": "vectorize-query-vector", "summary": "Query Vectors", "description": "Finds vectors closest to a given vector in an index.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vectorize_index-query-v2-request" } } } }, "responses": { "200": { "description": "Query Vectors Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_index-query-v2-response" } } } ] } } } }, "4XX": { "description": "Query Vectors Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize" ], "x-api-token-group": [ "Vectorize Write", "Vectorize Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "vectorize", "x-fern-sdk-method-name": "query", "x-forge-hidden": true } }, "/accounts/{account_id}/vectorize/v2/indexes/{index_name}/upsert": { "post": { "operationId": "vectorize-upsert-vector", "summary": "Upsert Vectors", "description": "Upserts vectors into the specified index, creating them if they do not exist and returns a mutation id corresponding to the vectors enqueued for upsertion.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_identifier" } }, { "name": "index_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/vectorize_index-name" } }, { "name": "unparsable-behavior", "in": "query", "schema": { "description": "Behavior for ndjson parse failures.", "type": "string", "enum": [ "error", "discard" ] } } ], "requestBody": { "required": true, "content": { "application/x-ndjson": { "schema": { "description": "ndjson file containing vectors to upsert.", "type": "string", "format": "binary", "example": "@/path/to/vectors.ndjson" } } } }, "responses": { "200": { "description": "Upsert Vectors Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/vectorize_index-upsert-v2-response" } } } ] } } } }, "4XX": { "description": "Upsert Vectors Failure Response", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, { "$ref": "#/components/schemas/vectorize_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Vectorize" ], "x-api-token-group": [ "Vectorize Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "vectorize", "x-fern-sdk-method-name": "upsert", "x-forge-hidden": true } }, "/accounts/{account_id}/vuln_scanner/credential_sets": { "get": { "operationId": "list-credential-sets", "summary": "List credential sets", "description": "Returns all credential sets for the account.", "parameters": [ { "$ref": "#/components/parameters/vuln_scanner_page" }, { "$ref": "#/components/parameters/vuln_scanner_per_page" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/vuln_scanner_credential-set" } } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Credential Sets" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.credential-sets", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/vuln_scanner_account_id" } ], "post": { "operationId": "create-credential-set", "summary": "Create credential set", "description": "Creates a new credential set.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vuln_scanner_create-credential-set-request" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/vuln_scanner_credential-set" }, "result_info": { "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Credential Sets" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.credential-sets", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/vuln_scanner/credential_sets/{credential_set_id}": { "delete": { "operationId": "delete-credential-set", "summary": "Delete credential set", "description": "Deletes a credential set and all of its credentials.", "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vuln_scanner_empty-response" } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Credential Sets" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.credential-sets", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation permanently deletes the credential set and every credential it contains." }, "get": { "operationId": "get-credential-set", "summary": "Get credential set", "description": "Returns a single credential set by ID.", "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/vuln_scanner_credential-set" }, "result_info": { "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Credential Sets" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.credential-sets", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/vuln_scanner_account_id" }, { "$ref": "#/components/parameters/vuln_scanner_credential_set_id" } ], "patch": { "operationId": "edit-credential-set", "summary": "Edit credential set", "description": "Updates a credential set with only the provided fields; omitted fields remain unchanged.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vuln_scanner_patch-credential-set-request" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/vuln_scanner_credential-set" }, "result_info": { "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Credential Sets" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.credential-sets", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "update-credential-set", "summary": "Update credential set", "description": "Replaces a credential set. All fields must be provided.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vuln_scanner_update-credential-set-request" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/vuln_scanner_credential-set" }, "result_info": { "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Credential Sets" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.credential-sets", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/vuln_scanner/credential_sets/{credential_set_id}/credentials": { "get": { "operationId": "list-credentials", "summary": "List credentials", "description": "Returns all credentials within a credential set.", "parameters": [ { "$ref": "#/components/parameters/vuln_scanner_page" }, { "$ref": "#/components/parameters/vuln_scanner_per_page" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/vuln_scanner_credential" } } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Credentials" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.credential-sets.credentials", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/vuln_scanner_account_id" }, { "$ref": "#/components/parameters/vuln_scanner_credential_set_id" } ], "post": { "operationId": "create-credential", "summary": "Create credential", "description": "Creates a new credential within a credential set.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vuln_scanner_create-credential-request" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/vuln_scanner_credential" }, "result_info": { "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Credentials" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.credential-sets.credentials", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/vuln_scanner/credential_sets/{credential_set_id}/credentials/{credential_id}": { "delete": { "operationId": "delete-credential", "summary": "Delete credential", "description": "Deletes a credential.", "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vuln_scanner_empty-response" } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Credentials" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.credential-sets.credentials", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation permanently deletes the credential from the credential set." }, "get": { "operationId": "get-credential", "summary": "Get credential", "description": "Returns a single credential by ID.", "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/vuln_scanner_credential" }, "result_info": { "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Credentials" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.credential-sets.credentials", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/vuln_scanner_account_id" }, { "$ref": "#/components/parameters/vuln_scanner_credential_set_id" }, { "$ref": "#/components/parameters/vuln_scanner_credential_id" } ], "patch": { "operationId": "edit-credential", "summary": "Edit credential", "description": "Updates a credential with only the provided fields; omitted fields remain unchanged.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vuln_scanner_patch-credential-request" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/vuln_scanner_credential" }, "result_info": { "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Credentials" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.credential-sets.credentials", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "update-credential", "summary": "Update credential", "description": "Replaces a credential. All fields must be provided.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vuln_scanner_update-credential-request" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/vuln_scanner_credential" }, "result_info": { "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Credentials" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.credential-sets.credentials", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/vuln_scanner/scans": { "get": { "operationId": "list-scans", "summary": "List scans", "description": "Returns all scans for the account.", "parameters": [ { "$ref": "#/components/parameters/vuln_scanner_page" }, { "$ref": "#/components/parameters/vuln_scanner_per_page" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/vuln_scanner_scan" } } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Scans" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.scans", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/vuln_scanner_account_id" } ], "post": { "operationId": "create-scan", "summary": "Create scan", "description": "Creates and starts a new vulnerability scan. The response may include non-fatal warnings in the `messages` array.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vuln_scanner_create-scan-request" } } } }, "responses": { "200": { "description": "Successful response. Check the `messages` array for non-fatal\nwarnings that arose during scan creation.\n", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/vuln_scanner_scan" }, "result_info": { "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Scans" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.scans", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/vuln_scanner/scans/{scan_id}": { "delete": { "operationId": "delete-scan", "summary": "Delete scan", "description": "Deletes a scan and all associated data. Only scans in a terminal state (`finished`, `failed`) may be deleted. Attempting to delete a scan that is still being created or executed (`created`, `scheduled`, `planning`, `running`) returns `400`.", "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/vuln_scanner_delete-scan-response" }, "result_info": { "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Scans" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.scans", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation permanently deletes the completed or failed scan and all associated scan data." }, "get": { "operationId": "get-scan", "summary": "Get scan", "description": "Returns a single scan by ID.", "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/vuln_scanner_scan" }, "result_info": { "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Scans" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.scans", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/vuln_scanner_account_id" }, { "$ref": "#/components/parameters/vuln_scanner_scan_id" } ] }, "/accounts/{account_id}/vuln_scanner/target_environments": { "get": { "operationId": "list-target-environments", "summary": "List target environments", "description": "Returns all target environments for the account.", "parameters": [ { "$ref": "#/components/parameters/vuln_scanner_page" }, { "$ref": "#/components/parameters/vuln_scanner_per_page" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/vuln_scanner_target-environment" } } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Target Environments" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.target-environments", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/vuln_scanner_account_id" } ], "post": { "operationId": "create-target-environment", "summary": "Create target environment", "description": "Creates a new target environment for the account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vuln_scanner_create-target-environment-request" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/vuln_scanner_target-environment" }, "result_info": { "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Target Environments" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.target-environments", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/vuln_scanner/target_environments/{target_environment_id}": { "delete": { "operationId": "delete-target-environment", "summary": "Delete target environment", "description": "Removes a target environment.", "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vuln_scanner_empty-response" } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Target Environments" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.target-environments", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation permanently deletes the target environment from Vulnerability Scanner." }, "get": { "operationId": "get-target-environment", "summary": "Get target environment", "description": "Returns a single target environment by ID.", "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/vuln_scanner_target-environment" }, "result_info": { "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Target Environments" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.target-environments", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/vuln_scanner_account_id" }, { "$ref": "#/components/parameters/vuln_scanner_target_environment_id" } ], "patch": { "operationId": "edit-target-environment", "summary": "Edit target environment", "description": "Updates a target environment with only the provided fields; omitted fields remain unchanged.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vuln_scanner_patch-target-environment-request" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/vuln_scanner_target-environment" }, "result_info": { "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Target Environments" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.target-environments", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "update-target-environment", "summary": "Update target environment", "description": "Replaces a target environment. All fields must be provided.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vuln_scanner_update-target-environment-request" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/vuln_scanner_target-environment" }, "result_info": { "type": "object", "nullable": true } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/vuln_scanner_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Target Environments" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "api-security.vulnerability-scanner.target-environments", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/waiting_rooms": { "get": { "operationId": "waiting-room-list-waiting-rooms-account", "summary": "List waiting rooms for account", "description": "Lists waiting rooms for account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } }, { "$ref": "#/components/parameters/waitingroom_page" }, { "$ref": "#/components/parameters/waitingroom_per_page" } ], "responses": { "200": { "description": "List waiting rooms for account response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_response_collection" } } } }, "4XX": { "description": "List waiting rooms for account response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_response_collection" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Account Waiting Rooms Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.account-waiting-rooms", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/warp_connector": { "get": { "operationId": "cloudflare-tunnel-list-warp-connector-tunnels", "summary": "List Warp Connector Tunnels", "description": "Lists and filters Warp Connector Tunnels in an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "name", "in": "query", "schema": { "description": "A user-friendly name for the tunnel.", "type": "string", "example": "blog" } }, { "name": "is_deleted", "in": "query", "schema": { "description": "If `true`, only include deleted tunnels. If `false`, exclude deleted tunnels. If empty, all tunnels will be included.", "type": "boolean", "example": true } }, { "name": "existed_at", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_existed_at" } }, { "name": "uuid", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_tunnel_id" } }, { "name": "was_active_at", "in": "query", "schema": { "type": "string", "format": "date-time", "example": "2009-11-10T23:00:00Z" } }, { "name": "was_inactive_at", "in": "query", "schema": { "type": "string", "format": "date-time", "example": "2009-11-10T23:00:00Z" } }, { "name": "include_prefix", "in": "query", "schema": { "type": "string", "example": "vpc1-" } }, { "name": "exclude_prefix", "in": "query", "schema": { "type": "string", "example": "vpc1-" } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_status" } }, { "name": "per_page", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_per_page" } }, { "name": "page", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_page_number" } } ], "responses": { "200": { "description": "List Warp Connector Tunnels response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_warp-connector-response-collection" } } } }, "4XX": { "description": "List Warp Connector Tunnels response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_warp-connector-response-collection" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Cloudflare Tunnel" ], "x-api-token-group": [ "Cloudflare One Connectors Write", "Cloudflare One Connectors Read", "Cloudflare One Connector: WARP Write", "Cloudflare One Connector: WARP Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "mesh.nodes", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "cloudflare-tunnel-create-a-warp-connector-tunnel", "summary": "Create a Warp Connector Tunnel", "description": "Creates a new Warp Connector Tunnel in an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ha": { "description": "Indicates that the tunnel will be created to be highly available. If omitted, defaults to false.", "type": "boolean", "default": false }, "name": { "$ref": "#/components/schemas/tunnel_tunnel_name" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Create a Warp Connector Tunnel response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_warp-connector-response-single" } } } }, "4XX": { "description": "Create a Warp Connector Tunnel response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_warp-connector-response-single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Cloudflare Tunnel" ], "x-api-token-group": [ "Cloudflare One Connectors Write", "Cloudflare One Connector: WARP Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "mesh.nodes", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/warp_connector/{tunnel_id}": { "delete": { "operationId": "cloudflare-tunnel-delete-a-warp-connector-tunnel", "summary": "Delete a Warp Connector Tunnel", "description": "Deletes a Warp Connector Tunnel from an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "tunnel_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_tunnel_id" } } ], "responses": { "200": { "description": "Delete a Warp Connector Tunnel response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_warp-connector-response-single" } } } }, "4XX": { "description": "Delete a Warp Connector Tunnel response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_warp-connector-response-single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Cloudflare Tunnel" ], "x-api-token-group": [ "Cloudflare One Connectors Write", "Cloudflare One Connector: WARP Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "mesh.nodes", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-params": { "tunnel_id": { "flagName": "node-id" } }, "x-forge-require-confirmation": "This operation permanently deletes a Mesh node (Warp Connector Tunnel)." }, "get": { "operationId": "cloudflare-tunnel-get-a-warp-connector-tunnel", "summary": "Get a Warp Connector Tunnel", "description": "Fetches a single Warp Connector Tunnel.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "tunnel_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_tunnel_id" } } ], "responses": { "200": { "description": "Get a Warp Connector Tunnel response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_warp-connector-response-single" } } } }, "4XX": { "description": "Get a Warp Connector Tunnel response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_warp-connector-response-single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Cloudflare Tunnel" ], "x-api-token-group": [ "Cloudflare One Connectors Write", "Cloudflare One Connectors Read", "Cloudflare One Connector: WARP Write", "Cloudflare One Connector: WARP Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "mesh.nodes", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-forge-params": { "tunnel_id": { "flagName": "node-id" } } }, "patch": { "operationId": "cloudflare-tunnel-update-a-warp-connector-tunnel", "summary": "Update a Warp Connector Tunnel", "description": "Updates an existing Warp Connector Tunnel.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "tunnel_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_tunnel_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/tunnel_tunnel_name" }, "tunnel_secret": { "$ref": "#/components/schemas/tunnel_tunnel_secret" } } } } } }, "responses": { "200": { "description": "Update a Warp Connector Tunnel response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_warp-connector-response-single" } } } }, "4XX": { "description": "Update a Warp Connector Tunnel response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_warp-connector-response-single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Cloudflare Tunnel" ], "x-api-token-group": [ "Cloudflare One Connectors Write", "Cloudflare One Connector: WARP Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "mesh.nodes", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true, "x-forge-params": { "tunnel_id": { "flagName": "node-id" } } } }, "/accounts/{account_id}/warp_connector/{tunnel_id}/configurations": { "get": { "operationId": "cloudflare-tunnel-configuration-get-warp-connector-configuration", "summary": "Get WARP Connector HA configuration", "description": "Gets the high-availability configuration for a WARP Connector tunnel.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_identifier" } }, { "name": "tunnel_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_tunnel_id-2" } } ], "responses": { "200": { "description": "Get WARP Connector HA configuration response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_mesh_configuration_response_single" } } } }, "4XX": { "description": "Get WARP Connector HA configuration response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_api-response-common-failure-2" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Cloudflare Tunnel Configuration" ], "x-api-token-group": [ "Cloudflare One Connectors Write", "Cloudflare One Connectors Read", "Cloudflare One Connector: WARP Write", "Cloudflare One Connector: WARP Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "mesh.nodes.configurations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "cloudflare-tunnel-configuration-update-warp-connector-configuration", "summary": "Update WARP Connector HA configuration", "description": "Adds or updates the high-availability configuration for a WARP Connector tunnel.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_identifier" } }, { "name": "tunnel_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_tunnel_id-2" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_mesh_configuration_request_body" } } } }, "responses": { "200": { "description": "Update WARP Connector HA configuration response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_mesh_configuration_response_single" } } } }, "4XX": { "description": "Update WARP Connector HA configuration response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_api-response-common-failure-2" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Cloudflare Tunnel Configuration" ], "x-api-token-group": [ "Cloudflare One Connectors Write", "Cloudflare One Connector: WARP Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "mesh.nodes.configurations", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/warp_connector/{tunnel_id}/connections": { "get": { "operationId": "cloudflare-tunnel-list-warp-connector-tunnel-connections", "summary": "List WARP Connector Tunnel connections", "description": "Fetches connection details for a WARP Connector Tunnel.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "tunnel_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_tunnel_id" } } ], "responses": { "200": { "description": "List WARP Connector Tunnel connections response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_tunnel_warp_connector_connections_response" } } } }, "4XX": { "description": "List WARP Connector connections response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_tunnel_warp_connector_connections_response" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Cloudflare Tunnel" ], "x-api-token-group": [ "Cloudflare One Connectors Write", "Cloudflare One Connectors Read", "Cloudflare One Connector: WARP Write", "Cloudflare One Connector: WARP Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "mesh.nodes.connections", "x-fern-sdk-method-name": "list", "x-forge-hidden": true, "x-forge-params": { "tunnel_id": { "flagName": "node-id" } } } }, "/accounts/{account_id}/warp_connector/{tunnel_id}/connectors/{connector_id}": { "get": { "operationId": "cloudflare-tunnel-get-warp-connector-tunnel-connector", "summary": "Get WARP Connector Tunnel connector", "description": "Fetches connector and connection details for a WARP Connector Tunnel.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "tunnel_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_tunnel_id" } }, { "name": "connector_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_client_id" } } ], "responses": { "200": { "description": "Get WARP Connector Tunnel connector response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_tunnel_warp_connector_client_response" } } } }, "4XX": { "description": "Get WARP Connector Tunnel connector response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_tunnel_warp_connector_client_response" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Cloudflare Tunnel" ], "x-api-token-group": [ "Cloudflare One Connectors Write", "Cloudflare One Connectors Read", "Cloudflare One Connector: WARP Write", "Cloudflare One Connector: WARP Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "mesh.nodes.connectors", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-forge-params": { "tunnel_id": { "flagName": "node-id" } } } }, "/accounts/{account_id}/warp_connector/{tunnel_id}/failover": { "put": { "operationId": "cloudflare-tunnel-manual-failover-warp-connector-tunnel", "summary": "Trigger a manual failover for a WARP Connector Tunnel", "description": "Triggers a manual failover for a specific WARP Connector Tunnel, setting the specified client as the active connector. The tunnel must be configured for high availability (HA) and the client must be linked to the tunnel.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "tunnel_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_tunnel_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "$ref": "#/components/schemas/tunnel_client_id_input" } }, "required": [ "client_id" ] } } } }, "responses": { "200": { "description": "Manual failover response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_empty_response" } } } }, "4XX": { "description": "Manual failover response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_empty_response" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Cloudflare Tunnel" ], "x-api-token-group": [ "Cloudflare One Connectors Write", "Cloudflare One Connector: WARP Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "mesh.nodes", "x-fern-sdk-method-name": "failover", "x-forge-hidden": true, "x-forge-params": { "client_id": { "flagName": "connector-id" }, "tunnel_id": { "flagName": "node-id" } }, "x-forge-require-confirmation": "This operation triggers a manual failover, changing the active connector for a Mesh node." } }, "/accounts/{account_id}/warp_connector/{tunnel_id}/token": { "get": { "operationId": "cloudflare-tunnel-get-a-warp-connector-tunnel-token", "summary": "Get a Warp Connector Tunnel token", "description": "Gets the token used to associate warp device with a specific Warp Connector tunnel.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "tunnel_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_tunnel_id" } } ], "responses": { "200": { "description": "Get a Warp Connector Tunnel token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_tunnel_response_token" } } } }, "4XX": { "description": "Get a Warp Connector Tunnel token response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_tunnel_response_token" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Cloudflare Tunnel" ], "x-api-token-group": [ "Cloudflare One Connectors Write", "Cloudflare One Connector: cloudflared Write", "Cloudflare Tunnel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "mesh.nodes.token", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-forge-params": { "tunnel_id": { "flagName": "node-id" } } } }, "/accounts/{account_id}/workers/account-settings": { "get": { "operationId": "worker-account-settings-fetch-worker-account-settings", "summary": "Fetch Worker Account Settings", "description": "Fetches Worker account settings for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } } ], "responses": { "200": { "description": "Fetch Worker Account Settings response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_account-settings" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Fetch Worker Account Settings response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Account Settings" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read", "DNS View Write", "DNS View Read", "SCIM Provisioning", "Load Balancers Account Write", "Load Balancers Account Read", "Zero Trust: PII Read", "DDoS Botnet Feed Write", "DDoS Botnet Feed Read", "Workers R2 Storage Write", "Workers R2 Storage Read", "DDoS Protection Write", "DDoS Protection Read", "Workers Tail Read", "Workers KV Storage Write", "Workers KV Storage Read", "Workers Scripts Write", "Workers Scripts Read", "Load Balancing: Monitors and Pools Write", "Load Balancing: Monitors and Pools Read", "Account Firewall Access Rules Write", "Account Firewall Access Rules Read", "DNS Firewall Write", "DNS Firewall Read", "Billing Write", "Billing Read", "Account Settings Write", "Account Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.account-settings", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "worker-account-settings-create-worker-account-settings", "summary": "Create Worker Account Settings", "description": "Creates Worker account settings for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_account-settings" } } } }, "responses": { "200": { "description": "Create Worker Account Settings response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_account-settings" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Create Worker Account Settings response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Account Settings" ], "x-api-token-group": [ "Account Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.account-settings", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/assets/upload": { "post": { "operationId": "worker-assets-upload", "summary": "Upload Assets", "description": "Upload assets ahead of creating a Worker version. To learn more about the direct uploads of assets, see https://developers.cloudflare.com/workers/static-assets/direct-upload/.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "base64", "in": "query", "required": true, "schema": { "description": "Whether the file contents are base64-encoded. Must be `true`.", "type": "boolean", "enum": [ true ] } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "encoding": { "*": { "contentType": "*/*" } }, "schema": { "type": "object", "additionalProperties": { "description": "Base-64 encoded contents of the file. The content type of the file should be included to ensure a valid \"Content-Type\" header is included in asset responses.", "type": "string" } } } } }, "responses": { "201": { "description": "Upload Assets response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_completed-upload-assets-response" } } } }, "202": { "description": "Upload Assets response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_upload-assets-response" } } } }, "4XX": { "description": "Upload Assets response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "assets_jwt": [] } ], "tags": [ "Worker Script" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.assets.upload", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/dispatch/namespaces": { "get": { "operationId": "namespace-worker-list", "summary": "List dispatch namespaces", "description": "Fetch a list of Workers for Platforms namespaces.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } } ], "responses": { "200": { "description": "Fetch a list of Workers for Platforms namespaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_namespace-list-response" } } } }, "4XX": { "description": "Failure to get list of Workers for Platforms namespaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "namespace-worker-create", "summary": "Create dispatch namespace", "description": "Create a new Workers for Platforms namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The name of the dispatch namespace.", "type": "string", "example": "my-dispatch-namespace", "x-auditable": true } } } } } }, "responses": { "200": { "description": "Fetch a list of Workers for Platforms namespaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_namespace-single-response" } } } }, "4XX": { "description": "Failure to get list of Workers for Platforms namespaces.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/dispatch/namespaces/{dispatch_namespace}": { "delete": { "operationId": "namespace-worker-delete-namespace", "summary": "Delete dispatch namespace", "description": "Delete a Workers for Platforms namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } } ], "responses": { "200": { "description": "Delete a Workers for Platforms namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-null-result" } } } }, "4XX": { "description": "Failure to delete Workers for Platforms namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "namespace-worker-get-namespace", "summary": "Get dispatch namespace", "description": "Get a Workers for Platforms namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } } ], "responses": { "200": { "description": "Get a Workers for Platforms namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_namespace-single-response" } } } }, "4XX": { "description": "Failure to get Workers for Platforms namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "namespace-worker-patch-namespace", "summary": "Patch dispatch namespace", "description": "Patch a Workers for Platforms namespace. Omitted fields are left unchanged.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The name of the dispatch namespace.", "type": "string", "example": "my-dispatch-namespace", "x-auditable": true }, "trusted_workers": { "$ref": "#/components/schemas/workers_trusted_workers" } } } } } }, "responses": { "200": { "description": "Patch a Workers for Platforms namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_namespace-single-response" } } } }, "4XX": { "description": "Failure to patch Workers for Platforms namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "namespace-worker-put-namespace", "summary": "Update dispatch namespace", "description": "Update a Workers for Platforms namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The name of the dispatch namespace.", "type": "string", "example": "my-dispatch-namespace", "x-auditable": true }, "trusted_workers": { "$ref": "#/components/schemas/workers_trusted_workers" } } } } } }, "responses": { "200": { "description": "Update a Workers for Platforms namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_namespace-single-response" } } } }, "4XX": { "description": "Failure to update Workers for Platforms namespace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/dispatch/namespaces/{dispatch_namespace}/scripts": { "delete": { "operationId": "namespace-worker-delete-scripts", "summary": "Delete Scripts in Namespace", "description": "Delete multiple scripts from a Workers for Platforms namespace based on optional tag filters.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "tags", "in": "query", "description": "Filter scripts by tags before deletion. Format: comma-separated list of tag:allowed pairs where allowed is 'yes' or 'no'.", "schema": { "type": "string", "example": "production:yes,staging:no" } }, { "name": "limit", "in": "query", "description": "Limit the number of scripts to delete.", "schema": { "type": "integer", "example": 1000 } } ], "responses": { "200": { "description": "Delete scripts in namespace response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_namespace-script-delete-bulk-response" } } } }, "4XX": { "description": "Delete scripts in namespace response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts", "x-fern-sdk-method-name": "bulk-delete", "x-forge-hidden": true }, "get": { "operationId": "namespace-worker-list-scripts", "summary": "List Scripts in Namespace", "description": "Fetch a list of scripts uploaded to a Workers for Platforms namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "tags", "in": "query", "description": "Filter scripts by tags. Format: comma-separated list of tag:allowed pairs where allowed is 'yes' or 'no'.", "schema": { "type": "string", "example": "production:yes,staging:no" } } ], "responses": { "200": { "description": "List scripts in namespace response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/workers_namespace-script-response" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "List scripts in namespace response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/dispatch/namespaces/{dispatch_namespace}/scripts/{script_name}": { "delete": { "operationId": "namespace-worker-script-delete-worker", "summary": "Delete Worker", "description": "Delete a worker from a Workers for Platforms namespace. This call has no response body on a successful delete.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } }, { "name": "force", "in": "query", "description": "If set to true, delete will not be stopped by associated service binding, durable object, or other binding. Any of these associated bindings/durable objects will be deleted along with the script.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Delete Worker response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-null-result" } } } }, "4XX": { "description": "Delete Worker response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "namespace-worker-script-worker-details", "summary": "Worker Details", "description": "Fetch information about a script uploaded to a Workers for Platforms namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "Worker Details Response (Workers for Platforms).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_namespace-script-response-single" } } } }, "4XX": { "description": "Worker Details Failure (Workers for Platforms).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "namespace-worker-script-upload-worker-module", "summary": "Upload Worker Module", "description": "Upload a worker module to a Workers for Platforms namespace. You can find more about the multipart metadata on our docs: https://developers.cloudflare.com/workers/configuration/multipart-upload-metadata/.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } }, { "name": "bindings_inherit", "in": "query", "description": "When set to \"strict\", the upload will fail if any `inherit` type bindings cannot be resolved against the previous version of the script. Without this, unresolvable inherit bindings are silently dropped.", "schema": { "type": "string", "enum": [ "strict" ] } } ], "requestBody": { "$ref": "#/components/requestBodies/workers_namespace_upload" }, "responses": { "200": { "$ref": "#/components/responses/workers_200" }, "4XX": { "$ref": "#/components/responses/workers_4XX" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/dispatch/namespaces/{dispatch_namespace}/scripts/{script_name}/assets-upload-session": { "post": { "operationId": "namespace-worker-script-update-create-assets-upload-session", "summary": "Create Assets Upload Session", "description": "Start uploading a collection of assets for use in a Worker version. To learn more about the direct uploads of assets, see https://developers.cloudflare.com/workers/static-assets/direct-upload/.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_create-assets-upload-session-object" } } } }, "responses": { "200": { "description": "Create Assets Upload Session response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_create-assets-upload-session-response" } } } }, "4XX": { "description": "Create Assets Upload Session response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts.asset-upload", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/dispatch/namespaces/{dispatch_namespace}/scripts/{script_name}/bindings": { "get": { "operationId": "namespace-worker-get-script-bindings", "summary": "Get Script Bindings", "description": "Fetch script bindings from a script uploaded to a Workers for Platforms namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "Fetch script bindings (Workers for Platforms).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_bindings" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Fetch script bindings failure (Workers for Platforms).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts.bindings", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/dispatch/namespaces/{dispatch_namespace}/scripts/{script_name}/content": { "get": { "operationId": "namespace-worker-get-script-content", "summary": "Get Script Content", "description": "Fetch script content from a script uploaded to a Workers for Platforms namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "Get script content.", "content": { "string": { "schema": { "type": "string", "example": "export default {\n async fetch(request, env, ctx) {\n return new Response(\"Hello, world!\");\n }\n};\n" } } } }, "4XX": { "description": "Get script content failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts.content", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "namespace-worker-put-script-content", "summary": "Put Script Content", "description": "Put script content for a script uploaded to a Workers for Platforms namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } }, { "name": "CF-WORKER-BODY-PART", "in": "header", "description": "The multipart name of a script upload part containing script content in service worker format. Alternative to including in a metadata part.", "schema": { "type": "string" } }, { "name": "CF-WORKER-MAIN-MODULE-PART", "in": "header", "description": "The multipart name of a script upload part containing script content in es module format. Alternative to including in a metadata part.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "encoding": { "files": { "contentType": "application/javascript+module, text/javascript+module, application/javascript, text/javascript, text/x-python, text/x-python-requirement, application/wasm, text/plain, application/octet-stream, application/source-map" }, "metadata": { "contentType": "application/json" } }, "schema": { "type": "object", "properties": { "files": { "description": "An array of modules (often JavaScript files) comprising a Worker script. At least one module must be present and referenced in the metadata as `main_module` or `body_part` by filename.
Possible Content-Type(s) are: `application/javascript+module`, `text/javascript+module`, `application/javascript`, `text/javascript`, `text/x-python`, `text/x-python-requirement`, `application/wasm`, `text/plain`, `application/octet-stream`, `application/source-map`.", "type": "array", "items": { "format": "binary", "type": "string" }, "x-stainless-collection-type": "set" }, "metadata": { "description": "JSON-encoded metadata about the uploaded parts and Worker configuration.", "type": "object", "properties": { "body_part": { "description": "Name of the part in the multipart request that contains the script (e.g. the file adding a listener to the `fetch` event). Indicates a `service worker syntax` Worker.", "type": "string", "example": "worker.js" }, "main_module": { "description": "Name of the part in the multipart request that contains the main module (e.g. the file exporting a `fetch` handler). Indicates a `module syntax` Worker.", "type": "string", "example": "worker.js" } } } }, "required": [ "metadata" ] } } } }, "responses": { "200": { "description": "Put script content (Workers for Platforms).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_script-response-single" } } } }, "4XX": { "description": "Put script content failure (Workers for Platforms).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts.content", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/dispatch/namespaces/{dispatch_namespace}/scripts/{script_name}/secrets": { "get": { "operationId": "namespace-worker-list-script-secrets", "summary": "List Script Secrets", "description": "List secrets bound to a script uploaded to a Workers for Platforms namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "List script secrets.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/workers_secret" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "List script secrets failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts.secrets", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "put": { "operationId": "namespace-worker-put-script-secrets", "summary": "Add script secret", "description": "Add a secret to a script by creating a new version with that secret.\n\nWhen changing more than one secret at a time, prefer the \"Patch multiple\nscript secrets\" API instead of changing many secrets individually.\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_secret" } } } }, "responses": { "200": { "description": "Fetch script bindings (Workers for Platforms).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_secret" } }, "required": [ "result" ], "type": "object" } ] } } } }, "429": { "description": "Too many requests are currently modifying the script.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } }, "4XX": { "description": "Fetch script bindings failure (Workers for Platforms).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts.secrets", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/dispatch/namespaces/{dispatch_namespace}/scripts/{script_name}/secrets-bulk": { "patch": { "operationId": "namespace-worker-patch-script-secrets-bulk", "summary": "Patch multiple script secrets", "description": "Create, update, or delete multiple secrets on a script in a single operation using JSON Merge Patch (RFC 7396).\nThis operation creates a single version with all changes included.\nPrefer this API instead of changing many secrets individually.\n\nUsage:\n\n- To create or update a secret, set its value to a secret object.\n- To delete a secret, set its value to `null`.\n- Secrets not included in the request are left unchanged.\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_secret-patch-request" } }, "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/workers_secret-patch-request" } } } }, "responses": { "200": { "description": "Patch script secrets bulk success (Workers for Platforms).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_secret-patch-response" } }, "required": [ "result" ], "type": "object" } ] } } } }, "429": { "description": "Too many requests are currently modifying the script.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } }, "4XX": { "description": "Patch script secrets bulk failure (Workers for Platforms).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts.secrets", "x-fern-sdk-method-name": "bulk-edit", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/dispatch/namespaces/{dispatch_namespace}/scripts/{script_name}/secrets/{secret_name}": { "delete": { "operationId": "namespace-worker-delete-script-secret", "summary": "Delete script secret", "description": "Remove a secret from a script by creating a new version without that\nsecret.\n\nWhen changing more than one secret at a time, prefer the \"Patch multiple\nscript secrets\" API instead of changing many secrets individually.\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } }, { "name": "secret_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_secret_name" } }, { "name": "url_encoded", "in": "query", "schema": { "$ref": "#/components/schemas/workers_secret_name_url_encoded" } } ], "responses": { "200": { "description": "Delete script secret binding (Workers for Platforms).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-null-result" } } } }, "4XX": { "description": "Delete script secret failure (Workers for Platforms).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts.secrets", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "namespace-worker-get-script-secrets", "summary": "Get secret binding", "description": "Get a given secret binding (value omitted) on a script uploaded to a Workers for Platforms namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } }, { "name": "secret_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_secret_name" } }, { "name": "url_encoded", "in": "query", "schema": { "$ref": "#/components/schemas/workers_secret_name_url_encoded" } } ], "responses": { "200": { "description": "Get script secret (Workers for Platforms).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_secret" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Get script secret failure (Workers for Platforms).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts.secrets", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/dispatch/namespaces/{dispatch_namespace}/scripts/{script_name}/settings": { "get": { "operationId": "namespace-worker-get-script-settings", "summary": "Get Script Settings", "description": "Get script settings from a script uploaded to a Workers for Platforms namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "Fetch script settings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_namespace-script-and-version-settings-item" } }, "type": "object" } ] } } } }, "4XX": { "description": "Fetch script settings failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts.settings", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "namespace-worker-patch-script-settings", "summary": "Patch Script Settings", "description": "Patch script metadata, such as bindings.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "encoding": { "settings": { "contentType": "application/json" } }, "schema": { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/workers_namespace-script-and-version-settings-item" } } } } } }, "responses": { "200": { "description": "Patch script settings.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_namespace-script-and-version-settings-item" } }, "type": "object" } ] } } } }, "4XX": { "description": "Patch script settings failure. When the patch uses the\ndeclarative `exports` field and one or more entries fail\nreconciliation, the response is the exports reconciliation\nerror envelope (error code 100402) with per-class detail in\n`errors[].meta.details`.\n", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "$ref": "#/components/schemas/workers_exports_reconciliation_error_response" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts.settings", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/dispatch/namespaces/{dispatch_namespace}/scripts/{script_name}/tags": { "get": { "operationId": "namespace-worker-get-script-tags", "summary": "Get Script Tags", "description": "Fetch tags from a script uploaded to a Workers for Platforms namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "Fetch script tags.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/workers_tag" }, "example": [ "free", "customer" ] } }, "type": "object" } ] } } } }, "4XX": { "description": "Fetch script tags failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts.tags", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "put": { "operationId": "namespace-worker-put-script-tags", "summary": "Put Script Tags", "description": "Put script tags for a script uploaded to a Workers for Platforms namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_tags" } } } }, "responses": { "200": { "description": "Fetch script tags.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/workers_tag" }, "example": [ "my-tag" ] } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Fetch script tags failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts.tags", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/dispatch/namespaces/{dispatch_namespace}/scripts/{script_name}/tags/{tag}": { "delete": { "operationId": "namespace-worker-delete-script-tag", "summary": "Delete Script Tag", "description": "Delete script tag for a script uploaded to a Workers for Platforms namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } }, { "name": "tag", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_tag" } } ], "responses": { "200": { "description": "Delete script tag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-null-result" } } } }, "4XX": { "description": "Delete script tag failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts.tags", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "put": { "operationId": "namespace-worker-put-script-tag", "summary": "Put Script Tag", "description": "Put a single tag on a script uploaded to a Workers for Platforms namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "dispatch_namespace", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } }, { "name": "tag", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_tag" } } ], "responses": { "200": { "description": "Put script tag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-null-result" } } } }, "4XX": { "description": "Put script tag failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers for Platforms" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dispatch-namespaces.scripts.tags", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/domains": { "get": { "operationId": "workers.domains.list", "summary": "List Domains", "description": "Lists all domains for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "zone_id", "in": "query", "schema": { "description": "ID of the zone containing the domain hostname.", "type": "string", "example": "593c9c94de529bbbfaac7c53ced0447d" } }, { "name": "zone_name", "in": "query", "schema": { "description": "Name of the zone containing the domain hostname.", "type": "string", "example": "example.com" } }, { "name": "service", "in": "query", "schema": { "description": "Name of the Worker associated with the domain.", "type": "string", "example": "my-worker" } }, { "name": "hostname", "in": "query", "schema": { "description": "Hostname of the domain.", "type": "string", "example": "app.example.com" } }, { "name": "environment", "in": "query", "schema": { "description": "Worker environment associated with the domain.", "type": "string", "example": "production" }, "deprecated": true } ], "responses": { "200": { "description": "List domains response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/workers_Domain" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "List domains failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Domains" ], "x-api-token-group": [ "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.domains", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "put": { "operationId": "workers.domains.update", "summary": "Attach Domain", "description": "Attaches a domain that routes traffic to a Worker.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_Domain" }, { "required": [ "hostname", "service" ], "type": "object" } ] } } } }, "responses": { "200": { "description": "Attach domain response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_Domain" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Attach domain failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Domains" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.domains", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/domains/{domain_id}": { "delete": { "operationId": "workers.domains.delete", "summary": "Detach Domain", "description": "Detaches a domain from a Worker. Both the Worker and all of its previews are no longer routable using this domain.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "description": "ID of the domain.", "type": "string", "example": "dbe10b4bc17c295377eabd600e1787fd" } } ], "responses": { "200": { "description": "Detach domain response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common" } } } }, "4XX": { "description": "Detach domain failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Domains" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.domains", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "workers.domains.get", "summary": "Get Domain", "description": "Gets information about a domain.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "description": "ID of the domain.", "type": "string", "example": "dbe10b4bc17c295377eabd600e1787fd" } } ], "responses": { "200": { "description": "Get domain response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_Domain" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Get domain failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Domains" ], "x-api-token-group": [ "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.domains", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/durable_objects/namespaces": { "get": { "operationId": "durable-objects-namespace-list-namespaces", "summary": "List Namespaces", "description": "Returns the Durable Object namespaces owned by an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "page", "in": "query", "description": "Current page.", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per-page.", "schema": { "type": "integer", "default": 20, "maximum": 1000, "minimum": 1 } } ], "responses": { "200": { "description": "List Namespaces response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/workers_namespace" } } }, "type": "object" } ] } } } }, "4XX": { "description": "List Namespaces response failure.", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/workers_namespace" } } }, "type": "object" } ] }, { "$ref": "#/components/schemas/workers_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Durable Objects Namespace" ], "x-api-token-group": [ "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "durable-objects.namespaces", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/durable_objects/namespaces/{id}/objects": { "get": { "operationId": "durable-objects-namespace-list-objects", "summary": "List Objects", "description": "Returns the Durable Objects in a given namespace.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_schemas-id" } }, { "name": "limit", "in": "query", "schema": { "description": "The number of objects to return. The cursor attribute may be used to iterate over the next batch of objects if there are more than the limit.", "type": "number", "default": 1000, "maximum": 10000, "minimum": 10 } }, { "name": "cursor", "in": "query", "schema": { "description": "Opaque token indicating the position from which to continue when requesting the next set of records. A valid value for the cursor can be obtained from the cursors object in the result_info structure.", "type": "string", "example": "AAAAANuhDN7SjacTnSVsDu3WW1Lvst6dxJGTjRY5BhxPXdf6L6uTcpd_NVtjhn11OUYRsVEykxoUwF-JQU4dn6QylZSKTOJuG0indrdn_MlHpMRtsxgXjs-RPdHYIVm3odE_uvEQ_dTQGFm8oikZMohns34DLBgrQpc" } } ], "responses": { "200": { "description": "List Objects response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/workers_object" } }, "result_info": { "type": "object", "properties": { "count": { "description": "Total results returned based on your list parameters.", "type": "number", "example": 1 }, "cursor": { "$ref": "#/components/schemas/workers_cursor" } } } }, "type": "object" } ] } } } }, "4XX": { "description": "List Objects response failure.", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/workers_object" } }, "result_info": { "type": "object", "properties": { "count": { "description": "Total results returned based on your list parameters.", "type": "number", "example": 1 }, "cursor": { "$ref": "#/components/schemas/workers_cursor" } } } }, "type": "object" } ] }, { "$ref": "#/components/schemas/workers_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Durable Objects Namespace" ], "x-api-token-group": [ "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "durable-objects.namespaces.objects", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/observability/destinations": { "get": { "operationId": "destination.list", "summary": "Get Destinations", "description": "List your Workers Observability Telemetry Destinations.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "number", "default": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "number", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "order", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "orderBy", "in": "query", "schema": { "type": "string", "default": "updated", "enum": [ "created", "updated" ] } } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "array", "items": { "properties": { "configuration": { "type": "object", "properties": { "destination_conf": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "jobStatus": { "type": "object", "properties": { "error_message": { "type": "string" }, "last_complete": { "type": "string" }, "last_error": { "type": "string" } }, "required": [ "last_complete", "last_error", "error_message" ] }, "logpushDataset": { "anyOf": [ { "enum": [ "opentelemetry-traces" ], "type": "string" }, { "enum": [ "opentelemetry-logs" ], "type": "string" }, { "enum": [ "opentelemetry-metrics" ], "type": "string" } ] }, "type": { "type": "string", "enum": [ "logpush" ] }, "url": { "type": "string" } }, "required": [ "type", "logpushDataset", "destination_conf", "url", "headers", "jobStatus" ] }, "enabled": { "type": "boolean" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$" }, "scripts": { "type": "array", "items": { "type": "string" } }, "slug": { "type": "string" } }, "required": [ "slug", "name", "enabled", "configuration", "scripts" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Not found" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Destinations" ], "x-api-token-group": [ "Workers Observability Write", "Workers Observability Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "observability.destinations", "x-fern-sdk-method-name": "list" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Your Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "destination.create", "summary": "Create Destination", "description": "Create a new Workers Observability Telemetry Destination.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "configuration": { "type": "object", "properties": { "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "logpushDataset": { "anyOf": [ { "enum": [ "opentelemetry-traces" ], "type": "string" }, { "enum": [ "opentelemetry-logs" ], "type": "string" }, { "enum": [ "opentelemetry-metrics" ], "type": "string" } ] }, "type": { "type": "string", "enum": [ "logpush" ] }, "url": { "type": "string" } }, "required": [ "type", "logpushDataset", "url", "headers" ] }, "enabled": { "type": "boolean" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$" }, "skipPreflightCheck": { "type": "boolean" } }, "required": [ "name", "enabled", "configuration" ] } } } }, "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Resource created" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "configuration": { "type": "object", "properties": { "destination_conf": { "type": "string" }, "logpushDataset": { "anyOf": [ { "enum": [ "opentelemetry-traces" ], "type": "string" }, { "enum": [ "opentelemetry-logs" ], "type": "string" }, { "enum": [ "opentelemetry-metrics" ], "type": "string" } ] }, "logpushJob": { "type": "number" }, "type": { "type": "string", "enum": [ "logpush" ] }, "url": { "type": "string" } }, "required": [ "type", "logpushDataset", "logpushJob", "destination_conf", "url" ] }, "enabled": { "type": "boolean" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$" }, "scripts": { "type": "array", "items": { "type": "string" } }, "slug": { "type": "string" } }, "required": [ "slug", "name", "enabled", "configuration", "scripts" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Bad Request" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Forbidden" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Destinations" ], "x-api-token-group": [ "Workers Observability Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "observability.destinations", "x-fern-sdk-method-name": "create" } }, "/accounts/{account_id}/workers/observability/destinations/{slug}": { "delete": { "operationId": "destinations.delete", "summary": "Delete Destination", "description": "Delete a Workers Observability Telemetry Destination.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "configuration": { "type": "object", "properties": { "destination_conf": { "type": "string" }, "logpushDataset": { "anyOf": [ { "enum": [ "opentelemetry-traces" ], "type": "string" }, { "enum": [ "opentelemetry-logs" ], "type": "string" }, { "enum": [ "opentelemetry-metrics" ], "type": "string" } ] }, "logpushJob": { "type": "number" }, "type": { "type": "string", "enum": [ "logpush" ] }, "url": { "type": "string" } }, "required": [ "type", "logpushDataset", "logpushJob", "destination_conf", "url" ] }, "enabled": { "type": "boolean" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$" }, "scripts": { "type": "array", "items": { "type": "string" } }, "slug": { "type": "string" } }, "required": [ "slug", "name", "enabled", "configuration", "scripts" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Not found" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Conflict" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Destinations" ], "x-api-token-group": [ "Workers Observability Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "observability.destinations", "x-fern-sdk-method-name": "delete", "x-forge-require-confirmation": "This operation deletes the destination." }, "parameters": [ { "name": "account_id", "in": "path", "description": "Your Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "patch": { "operationId": "destination.update", "summary": "Update Destination", "description": "Update an existing Workers Observability Telemetry Destination.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "configuration": { "type": "object", "properties": { "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "type": { "type": "string", "enum": [ "logpush" ] }, "url": { "type": "string" } }, "required": [ "type", "url", "headers" ] }, "enabled": { "type": "boolean" } }, "required": [ "enabled", "configuration" ] } } } }, "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "configuration": { "type": "object", "properties": { "destination_conf": { "type": "string" }, "logpushDataset": { "anyOf": [ { "enum": [ "opentelemetry-traces" ], "type": "string" }, { "enum": [ "opentelemetry-logs" ], "type": "string" }, { "enum": [ "opentelemetry-metrics" ], "type": "string" } ] }, "logpushJob": { "type": "number" }, "type": { "type": "string", "enum": [ "logpush" ] }, "url": { "type": "string" } }, "required": [ "type", "logpushDataset", "logpushJob", "destination_conf", "url" ] }, "enabled": { "type": "boolean" }, "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$" }, "scripts": { "type": "array", "items": { "type": "string" } }, "slug": { "type": "string" } }, "required": [ "slug", "name", "enabled", "configuration", "scripts" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Bad Request" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Not found" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Destinations" ], "x-api-token-group": [ "Workers Observability Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "observability.destinations", "x-fern-sdk-method-name": "update" } }, "/accounts/{account_id}/workers/observability/metricsexport": { "get": { "operationId": "metricsExport.list", "summary": "List Metrics Exports", "description": "List resources configured for Workers Observability metrics export.", "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "array", "items": { "additionalProperties": false, "properties": { "createdAt": { "type": "string" }, "destinations": { "type": "array", "items": { "minLength": 1, "type": "string" }, "minItems": 1 }, "resourceId": { "type": "string", "minLength": 1 }, "resourceType": { "type": "string", "enum": [ "workers", "d1", "r2", "containers" ] }, "updatedAt": { "type": "string" } }, "required": [ "resourceType", "resourceId", "destinations", "createdAt", "updatedAt" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Metrics Export" ], "x-api-token-group": [ "Workers Observability Write", "Workers Observability Read" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "observability.metrics-export", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "description": "Your Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "metricsExport.upsert", "summary": "Upsert Metrics Exports", "description": "Create or replace resources configured for Workers Observability metrics export.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "requester": { "type": "object", "additionalProperties": false, "properties": { "requesterId": { "type": "string", "minLength": 1 }, "requesterType": { "type": "string", "enum": [ "workers" ] } }, "required": [ "requesterType", "requesterId" ] }, "resources": { "type": "array", "items": { "additionalProperties": false, "properties": { "destinations": { "type": "array", "items": { "minLength": 1, "type": "string" }, "minItems": 1 }, "resourceId": { "type": "string", "minLength": 1 }, "resourceType": { "type": "string", "enum": [ "workers", "d1", "r2", "containers" ] } }, "required": [ "resourceType", "resourceId", "destinations" ], "type": "object" } } }, "additionalProperties": false, "required": [ "requester", "resources" ] } } } }, "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Resource created" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "array", "items": { "additionalProperties": false, "properties": { "createdAt": { "type": "string" }, "destinations": { "type": "array", "items": { "minLength": 1, "type": "string" }, "minItems": 1 }, "resourceId": { "type": "string", "minLength": 1 }, "resourceType": { "type": "string", "enum": [ "workers", "d1", "r2", "containers" ] }, "updatedAt": { "type": "string" } }, "required": [ "resourceType", "resourceId", "destinations", "createdAt", "updatedAt" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Bad Request" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Metrics Export" ], "x-api-token-group": [ "Workers Observability Write" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "observability.metrics-export", "x-fern-sdk-method-name": "upsert", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/observability/queries": { "get": { "operationId": "queries.list", "summary": "List queries", "description": "List saved queries.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "number", "default": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "number", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "order", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "orderBy", "in": "query", "schema": { "type": "string", "default": "updated", "enum": [ "created", "updated" ] } } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/workers-observability_query" } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Not found" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Saved Queries" ], "x-api-token-group": [ "Workers Observability Write", "Workers Observability Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "observability.queries", "x-fern-sdk-method-name": "list" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Your Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "queries.post", "summary": "Save query", "description": "Persist query for later use.", "requestBody": { "description": "Specify the new contents of the query.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "example": "Query description", "maxLength": 1000, "nullable": true }, "name": { "description": "Query name", "type": "string", "maxLength": 250, "minLength": 1 }, "parameters": { "properties": { "calculations": { "description": "Create Calculations to compute as part of the query.", "type": "array", "items": { "discriminator": { "propertyName": "operator" }, "oneOf": [ { "properties": { "alias": { "type": "string" }, "key": { "type": "string" }, "keyType": { "type": "string", "enum": [ "string", "number", "boolean" ] }, "operator": { "type": "string", "enum": [ "count", "COUNT" ] } }, "required": [ "operator" ], "type": "object" }, { "properties": { "alias": { "type": "string" }, "key": { "type": "string", "pattern": "\\S" }, "keyType": { "type": "string", "enum": [ "string", "number", "boolean" ] }, "operator": { "type": "string", "enum": [ "uniq", "max", "min", "sum", "avg", "median", "p001", "p01", "p05", "p10", "p25", "p75", "p90", "p95", "p99", "p999", "stddev", "variance", "COUNT_DISTINCT", "MAX", "MIN", "SUM", "AVG", "MEDIAN", "P001", "P01", "P05", "P10", "P25", "P75", "P90", "P95", "P99", "P999", "STDDEV", "VARIANCE" ] } }, "required": [ "key", "operator" ], "type": "object" } ] } }, "datasets": { "description": "Set the Datasets to query. Leave it empty to query all the datasets.", "type": "array", "items": { "type": "string" }, "example": [] }, "filterCombination": { "description": "Set a Flag to describe how to combine the filters on the query.", "type": "string", "enum": [ "and", "or", "AND", "OR" ] }, "filters": { "description": "Configure the Filters to apply to the query. Supports nested groups via kind: 'group'.", "type": "array", "items": { "$ref": "#/components/schemas/workers-observability_filter_node" } }, "groupBys": { "description": "Define how to group the results of the query.", "type": "array", "items": { "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean" ] }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" } }, "havings": { "description": "Configure the Having clauses that filter on calculations in the query result.", "type": "array", "items": { "properties": { "key": { "type": "string" }, "operation": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte" ] }, "value": { "type": "number" } }, "required": [ "key", "operation", "value" ], "type": "object" } }, "limit": { "description": "Set a limit on the number of results / records returned by the query", "type": "integer", "maximum": 100, "minimum": 0 }, "needle": { "description": "Define an expression to search using full-text search.", "type": "object", "properties": { "isRegex": { "type": "boolean" }, "matchCase": { "type": "boolean" }, "value": { "allOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "maxLength": 1000, "type": "string" } ] } }, "required": [ "value" ] }, "orderBy": { "description": "Configure the order of the results returned by the query.", "type": "object", "properties": { "order": { "description": "Set the order of the results", "type": "string", "enum": [ "asc", "desc" ] }, "value": { "description": "Configure which Calculation to order the results by.", "type": "string" } }, "required": [ "value" ] } }, "type": "object" } }, "required": [ "description", "name", "parameters" ] } } } }, "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/workers-observability_query" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Conflict" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Saved Queries" ], "x-api-token-group": [ "Workers Observability Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "observability.queries", "x-fern-sdk-method-name": "create" } }, "/accounts/{account_id}/workers/observability/queries/{queryId}": { "delete": { "operationId": "queries.delete", "summary": "Delete query", "description": "Delete a saved query.", "parameters": [ { "name": "queryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/workers-observability_query" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Not found" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Saved Queries" ], "x-api-token-group": [ "Workers Observability Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "observability.queries", "x-fern-sdk-method-name": "delete", "x-forge-require-confirmation": "This operation deletes the saved query." }, "get": { "operationId": "queries.get", "summary": "Get query", "description": "Retrieve a saved query.", "parameters": [ { "name": "queryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/workers-observability_query" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Not found" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Saved Queries" ], "x-api-token-group": [ "Workers Observability Write", "Workers Observability Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "observability.queries", "x-fern-sdk-method-name": "get" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Your Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "patch": { "operationId": "queries.patch", "summary": "Update query", "description": "Update saved query.", "parameters": [ { "name": "queryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Specify the new contents of the query.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "example": "Query description", "maxLength": 1000, "nullable": true }, "name": { "description": "Query name", "type": "string", "maxLength": 250, "minLength": 1 }, "parameters": { "properties": { "calculations": { "description": "Create Calculations to compute as part of the query.", "type": "array", "items": { "discriminator": { "propertyName": "operator" }, "oneOf": [ { "properties": { "alias": { "type": "string" }, "key": { "type": "string" }, "keyType": { "type": "string", "enum": [ "string", "number", "boolean" ] }, "operator": { "type": "string", "enum": [ "count", "COUNT" ] } }, "required": [ "operator" ], "type": "object" }, { "properties": { "alias": { "type": "string" }, "key": { "type": "string", "pattern": "\\S" }, "keyType": { "type": "string", "enum": [ "string", "number", "boolean" ] }, "operator": { "type": "string", "enum": [ "uniq", "max", "min", "sum", "avg", "median", "p001", "p01", "p05", "p10", "p25", "p75", "p90", "p95", "p99", "p999", "stddev", "variance", "COUNT_DISTINCT", "MAX", "MIN", "SUM", "AVG", "MEDIAN", "P001", "P01", "P05", "P10", "P25", "P75", "P90", "P95", "P99", "P999", "STDDEV", "VARIANCE" ] } }, "required": [ "key", "operator" ], "type": "object" } ] } }, "datasets": { "description": "Set the Datasets to query. Leave it empty to query all the datasets.", "type": "array", "items": { "type": "string" }, "example": [] }, "filterCombination": { "description": "Set a Flag to describe how to combine the filters on the query.", "type": "string", "enum": [ "and", "or", "AND", "OR" ] }, "filters": { "description": "Configure the Filters to apply to the query. Supports nested groups via kind: 'group'.", "type": "array", "items": { "$ref": "#/components/schemas/workers-observability_filter_node" } }, "groupBys": { "description": "Define how to group the results of the query.", "type": "array", "items": { "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean" ] }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" } }, "havings": { "description": "Configure the Having clauses that filter on calculations in the query result.", "type": "array", "items": { "properties": { "key": { "type": "string" }, "operation": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte" ] }, "value": { "type": "number" } }, "required": [ "key", "operation", "value" ], "type": "object" } }, "limit": { "description": "Set a limit on the number of results / records returned by the query", "type": "integer", "maximum": 100, "minimum": 0 }, "needle": { "description": "Define an expression to search using full-text search.", "type": "object", "properties": { "isRegex": { "type": "boolean" }, "matchCase": { "type": "boolean" }, "value": { "allOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "maxLength": 1000, "type": "string" } ] } }, "required": [ "value" ] }, "orderBy": { "description": "Configure the order of the results returned by the query.", "type": "object", "properties": { "order": { "description": "Set the order of the results", "type": "string", "enum": [ "asc", "desc" ] }, "value": { "description": "Configure which Calculation to order the results by.", "type": "string" } }, "required": [ "value" ] } }, "type": "object" } }, "required": [ "description", "name", "parameters" ] } } } }, "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/workers-observability_query" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Not found" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Saved Queries" ], "x-api-token-group": [ "Workers Observability Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "observability.queries", "x-fern-sdk-method-name": "edit" } }, "/accounts/{account_id}/workers/observability/shared/query": { "parameters": [ { "name": "account_id", "in": "path", "description": "Your Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "shared.query.post", "summary": "Create a sharable link to a query result", "description": "Shared queries store the results of a previously run query, allowing you to share the results with others.", "requestBody": { "description": "Create a sharable link to a query result.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chart": { "description": "When true, includes time-series data in the response.", "type": "boolean" }, "chartType": { "description": "Controls the SQL shape and response payload for the 'calculations' view. Omitted or 'timeseries_and_aggregate': current behaviour — both the time-series and aggregate queries. 'timeseries': time-series only. 'aggregate': aggregate only. 'distribution': a bucketed 2D histogram (time × value buckets) returned in 'distribution' instead of 'calculations'. 'distribution' is not compatible with 'compare' — combining them returns a 400.", "type": "string", "enum": [ "timeseries_and_aggregate", "timeseries", "aggregate", "distribution" ] }, "compare": { "description": "When true, includes a comparison dataset from the previous time period of equal length.", "type": "boolean" }, "distributionScale": { "description": "Value-axis bucketing for chartType 'distribution'. Omitted or 'log': geometric buckets, best for heavy-tailed latency. 'linear': fixed-width buckets, clearer for narrow or additive ranges. Ignored for other chartTypes. The response echoes the scheme used in distribution.bucketMode.", "type": "string", "enum": [ "log", "linear" ] }, "dry": { "description": "When true, executes the query without persisting the results. Useful for validation or previewing.", "type": "boolean", "default": false }, "granularity": { "description": "Number of time-series buckets. Only used when view is 'calculations'. Omit to let the system auto-detect an appropriate granularity.", "type": "number" }, "ignoreSeries": { "description": "When true, omits time-series data from the response and returns only aggregated values. Reduces response size when series are not needed.", "type": "boolean", "default": false }, "limit": { "description": "Maximum number of events to return when view is 'events'. Also controls the number of group-by rows when view is 'calculations'.", "type": "number", "default": 50, "maximum": 2000 }, "offset": { "description": "Cursor for pagination in event, trace, invocation, and agent views. Pass the $metadata.id of the last event, the trace cursor, or AgentRun.id to fetch the next page.", "type": "string" }, "offsetBy": { "description": "Numeric offset for paginating grouped/pattern results (top-N lists). Use together with limit. Not used by cursor-based pagination.", "type": "number" }, "offsetDirection": { "description": "Pagination direction: 'next' for forward, 'prev' for backward.", "type": "string" }, "parameters": { "description": "Query parameters defining what data to retrieve — filters, calculations, group-bys, and ordering. In practice this should always be provided for ad-hoc queries. Only omit when executing a previously saved query by queryId. Use the keys and values endpoints to discover available fields before building filters.", "properties": { "calculations": { "description": "Aggregation calculations to compute (e.g. count, avg, p99). Each calculation produces aggregate values and optional time-series data.", "type": "array", "items": { "discriminator": { "propertyName": "operator" }, "oneOf": [ { "properties": { "alias": { "description": "Custom label for this calculation in the results. Useful for distinguishing multiple calculations.", "type": "string" }, "key": { "description": "Field name to calculate over. Must exist in the data. Verify with the keys endpoint. Required for every operator except `count`, which aggregates whole rows and may omit it.", "type": "string" }, "keyType": { "description": "Data type of the key. Required when key is provided to ensure correct aggregation.", "type": "string", "enum": [ "string", "number", "boolean" ] }, "operator": { "description": "Aggregation operator to apply. Examples: count, avg, sum, min, max, median, p90, p95, p99, uniq, stddev, variance.", "type": "string", "enum": [ "count", "COUNT" ] } }, "required": [ "operator" ], "type": "object" }, { "properties": { "alias": { "description": "Custom label for this calculation in the results. Useful for distinguishing multiple calculations.", "type": "string" }, "key": { "description": "Field name to calculate over. Must exist in the data. Verify with the keys endpoint. Required for every operator except `count`, which aggregates whole rows and may omit it.", "type": "string", "pattern": "\\S" }, "keyType": { "description": "Data type of the key. Required when key is provided to ensure correct aggregation.", "type": "string", "enum": [ "string", "number", "boolean" ] }, "operator": { "description": "Aggregation operator to apply. Examples: count, avg, sum, min, max, median, p90, p95, p99, uniq, stddev, variance.", "type": "string", "enum": [ "uniq", "max", "min", "sum", "avg", "median", "p001", "p01", "p05", "p10", "p25", "p75", "p90", "p95", "p99", "p999", "stddev", "variance", "COUNT_DISTINCT", "MAX", "MIN", "SUM", "AVG", "MEDIAN", "P001", "P01", "P05", "P10", "P25", "P75", "P90", "P95", "P99", "P999", "STDDEV", "VARIANCE" ] } }, "required": [ "key", "operator" ], "type": "object" } ] } }, "datasets": { "description": "Datasets to query. Leave empty to query all available datasets.", "type": "array", "items": { "type": "string" }, "example": [] }, "filterCombination": { "description": "Logical operator for combining top-level filters: 'and' (all must match) or 'or' (any must match). Defaults to 'and'.", "type": "string", "enum": [ "and", "or", "AND", "OR" ] }, "filters": { "description": "Filters to narrow query results. Use the keys and values endpoints to discover available fields before building filters. Supports nested groups via kind: 'group'. Maximum nesting depth is 4.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/workers-observability_filter_node" }, { "anyOf": [ { "description": "A group node that nests child filters combined with a logical operator.", "properties": { "filterCombination": { "description": "Logical operator for combining child filters: 'and' (all must match) or 'or' (any must match).", "type": "string", "enum": [ "and", "or", "AND", "OR" ] }, "filters": { "description": "Child filter nodes. Each can be a leaf filter or another nested group.", "type": "array", "items": { "$ref": "#/components/schemas/workers-observability_filter_node" }, "minItems": 1 }, "kind": { "description": "Discriminator indicating this is a nested filter group.", "type": "string", "enum": [ "group" ] } }, "required": [ "kind", "filterCombination", "filters" ], "type": "object" }, { "$ref": "#/components/schemas/workers-observability_filter_leaf" } ], "description": "Supports nested groups via kind: 'group'. Maximum nesting depth is 4." } ] } }, "groupBys": { "description": "Fields to group calculation results by. Only applicable when the query view is 'calculations'. Produces per-group aggregate values.", "type": "array", "items": { "properties": { "type": { "description": "Data type of the group-by field.", "type": "string", "enum": [ "string", "number", "boolean" ] }, "value": { "description": "Field name to group results by (e.g. $metadata.service, $metadata.statusCode).", "type": "string" } }, "required": [ "type", "value" ], "type": "object" } }, "havings": { "description": "Post-aggregation filters applied to calculation results. Use to filter groups after aggregation (e.g. only groups where count > 100).", "type": "array", "items": { "properties": { "key": { "description": "Calculation alias or operator to filter on after aggregation.", "type": "string" }, "operation": { "description": "Numeric comparison operator: eq, neq, gt, gte, lt, lte.", "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte" ] }, "value": { "description": "Threshold value to compare the calculation result against.", "type": "number" } }, "required": [ "key", "operation", "value" ], "type": "object" } }, "limit": { "description": "Maximum number of group-by rows to return in calculation results. A value of 10 is a sensible default for most use cases.", "type": "integer", "maximum": 2000, "minimum": 0 }, "needle": { "description": "Full-text search expression applied across all event fields. Matches events containing the specified text.", "type": "object", "properties": { "isRegex": { "description": "When true, treats the value as a regular expression (RE2 syntax).", "type": "boolean" }, "matchCase": { "description": "When true, performs a case-sensitive search. Defaults to case-insensitive.", "type": "boolean" }, "value": { "description": "The text or pattern to search for.", "allOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "maxLength": 1000, "type": "string" } ] } }, "required": [ "value" ] }, "orderBy": { "description": "Ordering for grouped calculation results. Only effective when a group-by is present.", "type": "object", "properties": { "order": { "description": "Sort direction: 'asc' for ascending, 'desc' for descending.", "type": "string", "enum": [ "asc", "desc" ] }, "value": { "description": "Alias of the calculation to order results by. Must match the alias (or operator) of a calculation in the query.", "type": "string" } }, "required": [ "value" ] } }, "type": "object" }, "queryId": { "description": "Identifier for the query. When parameters are omitted, this ID is used to load a previously saved query's parameters. When providing parameters inline, pass any identifier (e.g. an ad-hoc ID).", "type": "string" }, "timeframe": { "description": "Timeframe for the query using Unix timestamps in milliseconds. 'from' must be earlier than 'to'. Narrower timeframes produce faster responses and more specific results.", "type": "object", "properties": { "from": { "description": "Start timestamp for the query timeframe. Unix timestamp in milliseconds", "type": "integer", "maximum": 253402300799999, "minimum": 0 }, "to": { "description": "End timestamp for the query timeframe. Unix timestamp in milliseconds", "type": "integer", "maximum": 253402300799999, "minimum": 0 } }, "required": [ "to", "from" ] }, "view": { "description": "Controls the shape of the response. 'events': individual log lines matching the query. 'calculations': aggregated metrics (count, avg, p99, etc.) with optional group-by breakdowns and time-series. 'invocations': events grouped by request ID. 'traces': distributed trace summaries. 'agents': agent-specific trace summaries.", "type": "string", "default": "calculations", "enum": [ "traces", "events", "calculations", "invocations", "requests", "agents" ] } }, "required": [ "queryId", "timeframe" ] } } } }, "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "id": { "description": "Specify the ID of the shared query.", "type": "string" } }, "required": [ "id" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Bad Request" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Too many requests" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Shared", "Query" ], "x-api-token-group": [ "Workers Observability Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "observability.shared-queries", "x-fern-sdk-method-name": "create" } }, "/accounts/{account_id}/workers/observability/shared/query/{id}": { "get": { "operationId": "shared.query.get", "summary": "View a query that has been shared", "description": "Shared queries store the results of a previously run query, allowing you to share the results with others.", "parameters": [ { "name": "id", "in": "path", "description": "Specify the ID of the shared query.", "required": true, "schema": { "description": "Specify the ID of the shared query.", "type": "string" } }, { "name": "view", "in": "query", "description": "Select the view of the query result to return, defaults to events.", "schema": { "description": "Select the view of the query result to return, defaults to events.", "type": "string", "enum": [ "events", "invocations", "calculations" ] } } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/workers-observability_query_results" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Bad Request" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Forbidden" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Shared", "Query" ], "x-api-token-group": [ "Workers Observability Write", "Workers Observability Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "observability.shared-queries", "x-fern-sdk-method-name": "get" }, "parameters": [ { "name": "account_id", "in": "path", "description": "Your Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ] }, "/accounts/{account_id}/workers/observability/telemetry/keys": { "parameters": [ { "name": "account_id", "in": "path", "description": "Your Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "telemetry.keys.list", "summary": "List keys", "description": "List all the keys in your telemetry events.", "requestBody": { "description": "Find keys in your telemetry events matching a specific filter or needle.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "datasets": { "description": "Leave this empty to use the default datasets", "type": "array", "items": { "type": "string" }, "default": [] }, "filters": { "description": "Apply filters to narrow key discovery. Supports nested groups via kind: 'group'. Maximum nesting depth is 4.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/workers-observability_filter_node" }, { "anyOf": [ { "description": "A group node that nests child filters combined with a logical operator.", "properties": { "filterCombination": { "description": "Logical operator for combining child filters: 'and' (all must match) or 'or' (any must match).", "type": "string", "enum": [ "and", "or", "AND", "OR" ] }, "filters": { "description": "Child filter nodes. Each can be a leaf filter or another nested group.", "type": "array", "items": { "$ref": "#/components/schemas/workers-observability_filter_node" }, "minItems": 1 }, "kind": { "description": "Discriminator indicating this is a nested filter group.", "type": "string", "enum": [ "group" ] } }, "required": [ "kind", "filterCombination", "filters" ], "type": "object" }, { "$ref": "#/components/schemas/workers-observability_filter_leaf" } ], "description": "Supports nested groups via kind: 'group'. Maximum nesting depth is 4." } ] }, "default": [] }, "from": { "type": "number" }, "keyNeedle": { "description": "If the user suggests a key, use this to narrow down the list of keys returned. Make sure matchCase is false to avoid case sensitivity issues.", "type": "object", "properties": { "isRegex": { "description": "When true, treats the value as a regular expression (RE2 syntax).", "type": "boolean" }, "matchCase": { "description": "When true, performs a case-sensitive search. Defaults to case-insensitive.", "type": "boolean" }, "value": { "description": "The text or pattern to search for.", "allOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "maxLength": 1000, "type": "string" } ] } }, "required": [ "value" ] }, "limit": { "description": "Advanced usage: set limit=1000+ to retrieve comprehensive key options without needing additional filtering.", "type": "number" }, "needle": { "description": "Search for a specific substring in any of the events", "type": "object", "properties": { "isRegex": { "description": "When true, treats the value as a regular expression (RE2 syntax).", "type": "boolean" }, "matchCase": { "description": "When true, performs a case-sensitive search. Defaults to case-insensitive.", "type": "boolean" }, "value": { "description": "The text or pattern to search for.", "allOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "maxLength": 1000, "type": "string" } ] } }, "required": [ "value" ] }, "to": { "type": "number" } } } } } }, "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "array", "items": { "properties": { "key": { "type": "string" }, "lastSeenAt": { "type": "number" }, "type": { "type": "string", "enum": [ "string", "boolean", "number" ] } }, "required": [ "key", "type", "lastSeenAt" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Bad Request" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Forbidden" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Too many requests" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "504": { "description": "Gateway timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Gateway timeout" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Keys" ], "x-api-token-group": [ "Workers Observability Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "observability.telemetry", "x-fern-sdk-method-name": "keys" } }, "/accounts/{account_id}/workers/observability/telemetry/live-tail": { "parameters": [ { "name": "account_id", "in": "path", "description": "Your Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "telemetry.live-tail.post", "summary": "Prepare live tail", "description": "Prepare websocket server for live tail.", "requestBody": { "description": "Create websocket server for live tail.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filterCombination": { "description": "Set a flag to describe how to combine the filters on the query.", "type": "string", "default": "and", "enum": [ "and", "or", "AND", "OR" ] }, "filters": { "description": "Apply filters to the query. Supports nested groups via kind: 'group'.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/workers-observability_filter_node" }, { "anyOf": [ { "description": "A group node that nests child filters combined with a logical operator.", "properties": { "filterCombination": { "description": "Logical operator for combining child filters: 'and' (all must match) or 'or' (any must match).", "type": "string", "enum": [ "and", "or", "AND", "OR" ] }, "filters": { "description": "Child filter nodes. Each can be a leaf filter or another nested group.", "type": "array", "items": { "$ref": "#/components/schemas/workers-observability_filter_node" }, "minItems": 1 }, "kind": { "description": "Discriminator indicating this is a nested filter group.", "type": "string", "enum": [ "group" ] } }, "required": [ "kind", "filterCombination", "filters" ], "type": "object" }, { "$ref": "#/components/schemas/workers-observability_filter_leaf" } ], "description": "Supports nested groups via kind: 'group'. Maximum nesting depth is 4." } ] }, "default": [] }, "scriptId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "wsUrl": { "description": "WebSocket URL clients connect to in order to stream live tail events.", "type": "string", "format": "uri" } }, "required": [ "wsUrl" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Forbidden" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Live Tail" ], "x-api-token-group": [ "Workers Observability Write" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "observability.telemetry", "x-fern-sdk-method-name": "live-tail", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/observability/telemetry/live-tail/heartbeat": { "parameters": [ { "name": "account_id", "in": "path", "description": "Your Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "telemetry.live-tail.heartbeat.get", "summary": "Live tail heartbeat", "description": "Notify live tail that user is still eligible to receive live events.", "requestBody": { "description": "Keep your live tail connection alive.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scriptId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Live Tail" ], "x-api-token-group": [ "Workers Observability Write" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "observability.telemetry", "x-fern-sdk-method-name": "heartbeat", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/observability/telemetry/query": { "parameters": [ { "name": "account_id", "in": "path", "description": "Your Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "telemetry.query", "summary": "Run a query", "description": "Run a temporary or saved query.", "requestBody": { "description": "Query your observability events, requests, and traces to build visualizations and identify insights.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chart": { "description": "When true, includes time-series data in the response.", "type": "boolean" }, "chartType": { "description": "Controls the SQL shape and response payload for the 'calculations' view. Omitted or 'timeseries_and_aggregate': current behaviour — both the time-series and aggregate queries. 'timeseries': time-series only. 'aggregate': aggregate only. 'distribution': a bucketed 2D histogram (time × value buckets) returned in 'distribution' instead of 'calculations'. 'distribution' is not compatible with 'compare' — combining them returns a 400.", "type": "string", "enum": [ "timeseries_and_aggregate", "timeseries", "aggregate", "distribution" ] }, "compare": { "description": "When true, includes a comparison dataset from the previous time period of equal length.", "type": "boolean" }, "distributionScale": { "description": "Value-axis bucketing for chartType 'distribution'. Omitted or 'log': geometric buckets, best for heavy-tailed latency. 'linear': fixed-width buckets, clearer for narrow or additive ranges. Ignored for other chartTypes. The response echoes the scheme used in distribution.bucketMode.", "type": "string", "enum": [ "log", "linear" ] }, "dry": { "description": "When true, executes the query without persisting the results. Useful for validation or previewing.", "type": "boolean", "default": false }, "granularity": { "description": "Number of time-series buckets. Only used when view is 'calculations'. Omit to let the system auto-detect an appropriate granularity.", "type": "number" }, "ignoreSeries": { "description": "When true, omits time-series data from the response and returns only aggregated values. Reduces response size when series are not needed.", "type": "boolean", "default": false }, "limit": { "description": "Maximum number of events to return when view is 'events'. Also controls the number of group-by rows when view is 'calculations'.", "type": "number", "default": 50, "maximum": 2000 }, "offset": { "description": "Cursor for pagination in event, trace, invocation, and agent views. Pass the $metadata.id of the last event, the trace cursor, or AgentRun.id to fetch the next page.", "type": "string" }, "offsetBy": { "description": "Numeric offset for paginating grouped/pattern results (top-N lists). Use together with limit. Not used by cursor-based pagination.", "type": "number" }, "offsetDirection": { "description": "Pagination direction: 'next' for forward, 'prev' for backward.", "type": "string" }, "parameters": { "description": "Query parameters defining what data to retrieve — filters, calculations, group-bys, and ordering. In practice this should always be provided for ad-hoc queries. Only omit when executing a previously saved query by queryId. Use the keys and values endpoints to discover available fields before building filters.", "properties": { "calculations": { "description": "Aggregation calculations to compute (e.g. count, avg, p99). Each calculation produces aggregate values and optional time-series data.", "type": "array", "items": { "discriminator": { "propertyName": "operator" }, "oneOf": [ { "properties": { "alias": { "description": "Custom label for this calculation in the results. Useful for distinguishing multiple calculations.", "type": "string" }, "key": { "description": "Field name to calculate over. Must exist in the data. Verify with the keys endpoint. Required for every operator except `count`, which aggregates whole rows and may omit it.", "type": "string" }, "keyType": { "description": "Data type of the key. Required when key is provided to ensure correct aggregation.", "type": "string", "enum": [ "string", "number", "boolean" ] }, "operator": { "description": "Aggregation operator to apply. Examples: count, avg, sum, min, max, median, p90, p95, p99, uniq, stddev, variance.", "type": "string", "enum": [ "count", "COUNT" ] } }, "required": [ "operator" ], "type": "object" }, { "properties": { "alias": { "description": "Custom label for this calculation in the results. Useful for distinguishing multiple calculations.", "type": "string" }, "key": { "description": "Field name to calculate over. Must exist in the data. Verify with the keys endpoint. Required for every operator except `count`, which aggregates whole rows and may omit it.", "type": "string", "pattern": "\\S" }, "keyType": { "description": "Data type of the key. Required when key is provided to ensure correct aggregation.", "type": "string", "enum": [ "string", "number", "boolean" ] }, "operator": { "description": "Aggregation operator to apply. Examples: count, avg, sum, min, max, median, p90, p95, p99, uniq, stddev, variance.", "type": "string", "enum": [ "uniq", "max", "min", "sum", "avg", "median", "p001", "p01", "p05", "p10", "p25", "p75", "p90", "p95", "p99", "p999", "stddev", "variance", "COUNT_DISTINCT", "MAX", "MIN", "SUM", "AVG", "MEDIAN", "P001", "P01", "P05", "P10", "P25", "P75", "P90", "P95", "P99", "P999", "STDDEV", "VARIANCE" ] } }, "required": [ "key", "operator" ], "type": "object" } ] } }, "datasets": { "description": "Datasets to query. Leave empty to query all available datasets.", "type": "array", "items": { "type": "string" }, "example": [] }, "filterCombination": { "description": "Logical operator for combining top-level filters: 'and' (all must match) or 'or' (any must match). Defaults to 'and'.", "type": "string", "enum": [ "and", "or", "AND", "OR" ] }, "filters": { "description": "Filters to narrow query results. Use the keys and values endpoints to discover available fields before building filters. Supports nested groups via kind: 'group'. Maximum nesting depth is 4.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/workers-observability_filter_node" }, { "anyOf": [ { "description": "A group node that nests child filters combined with a logical operator.", "properties": { "filterCombination": { "description": "Logical operator for combining child filters: 'and' (all must match) or 'or' (any must match).", "type": "string", "enum": [ "and", "or", "AND", "OR" ] }, "filters": { "description": "Child filter nodes. Each can be a leaf filter or another nested group.", "type": "array", "items": { "$ref": "#/components/schemas/workers-observability_filter_node" }, "minItems": 1 }, "kind": { "description": "Discriminator indicating this is a nested filter group.", "type": "string", "enum": [ "group" ] } }, "required": [ "kind", "filterCombination", "filters" ], "type": "object" }, { "$ref": "#/components/schemas/workers-observability_filter_leaf" } ], "description": "Supports nested groups via kind: 'group'. Maximum nesting depth is 4." } ] } }, "groupBys": { "description": "Fields to group calculation results by. Only applicable when the query view is 'calculations'. Produces per-group aggregate values.", "type": "array", "items": { "properties": { "type": { "description": "Data type of the group-by field.", "type": "string", "enum": [ "string", "number", "boolean" ] }, "value": { "description": "Field name to group results by (e.g. $metadata.service, $metadata.statusCode).", "type": "string" } }, "required": [ "type", "value" ], "type": "object" } }, "havings": { "description": "Post-aggregation filters applied to calculation results. Use to filter groups after aggregation (e.g. only groups where count > 100).", "type": "array", "items": { "properties": { "key": { "description": "Calculation alias or operator to filter on after aggregation.", "type": "string" }, "operation": { "description": "Numeric comparison operator: eq, neq, gt, gte, lt, lte.", "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte" ] }, "value": { "description": "Threshold value to compare the calculation result against.", "type": "number" } }, "required": [ "key", "operation", "value" ], "type": "object" } }, "limit": { "description": "Maximum number of group-by rows to return in calculation results. A value of 10 is a sensible default for most use cases.", "type": "integer", "maximum": 2000, "minimum": 0 }, "needle": { "description": "Full-text search expression applied across all event fields. Matches events containing the specified text.", "type": "object", "properties": { "isRegex": { "description": "When true, treats the value as a regular expression (RE2 syntax).", "type": "boolean" }, "matchCase": { "description": "When true, performs a case-sensitive search. Defaults to case-insensitive.", "type": "boolean" }, "value": { "description": "The text or pattern to search for.", "allOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "maxLength": 1000, "type": "string" } ] } }, "required": [ "value" ] }, "orderBy": { "description": "Ordering for grouped calculation results. Only effective when a group-by is present.", "type": "object", "properties": { "order": { "description": "Sort direction: 'asc' for ascending, 'desc' for descending.", "type": "string", "enum": [ "asc", "desc" ] }, "value": { "description": "Alias of the calculation to order results by. Must match the alias (or operator) of a calculation in the query.", "type": "string" } }, "required": [ "value" ] } }, "type": "object" }, "queryId": { "description": "Identifier for the query. When parameters are omitted, this ID is used to load a previously saved query's parameters. When providing parameters inline, pass any identifier (e.g. an ad-hoc ID).", "type": "string" }, "timeframe": { "description": "Timeframe for the query using Unix timestamps in milliseconds. 'from' must be earlier than 'to'. Narrower timeframes produce faster responses and more specific results.", "type": "object", "properties": { "from": { "description": "Start timestamp for the query timeframe. Unix timestamp in milliseconds", "type": "integer", "maximum": 253402300799999, "minimum": 0 }, "to": { "description": "End timestamp for the query timeframe. Unix timestamp in milliseconds", "type": "integer", "maximum": 253402300799999, "minimum": 0 } }, "required": [ "to", "from" ] }, "view": { "description": "Controls the shape of the response. 'events': individual log lines matching the query. 'calculations': aggregated metrics (count, avg, p99, etc.) with optional group-by breakdowns and time-series. 'invocations': events grouped by request ID. 'traces': distributed trace summaries. 'agents': agent-specific trace summaries.", "type": "string", "default": "calculations", "enum": [ "traces", "events", "calculations", "invocations", "requests", "agents" ] } }, "required": [ "queryId", "timeframe" ] } } } }, "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/workers-observability_query_results" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Bad Request" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Forbidden" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Too many requests" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "504": { "description": "Gateway timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Gateway timeout" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Query run" ], "x-api-token-group": [ "Workers Observability Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "observability.telemetry", "x-fern-sdk-method-name": "query" } }, "/accounts/{account_id}/workers/observability/telemetry/values": { "parameters": [ { "name": "account_id", "in": "path", "description": "Your Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "telemetry.values.list", "summary": "List values", "description": "List unique values found in your events.", "requestBody": { "description": "Retrieve values from your telemetry events.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "datasets": { "description": "Leave this empty to use the default datasets", "type": "array", "items": { "type": "string" } }, "filters": { "description": "Apply filters before listing values. Supports nested groups via kind: 'group'. Maximum nesting depth is 4.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/workers-observability_filter_node" }, { "anyOf": [ { "description": "A group node that nests child filters combined with a logical operator.", "properties": { "filterCombination": { "description": "Logical operator for combining child filters: 'and' (all must match) or 'or' (any must match).", "type": "string", "enum": [ "and", "or", "AND", "OR" ] }, "filters": { "description": "Child filter nodes. Each can be a leaf filter or another nested group.", "type": "array", "items": { "$ref": "#/components/schemas/workers-observability_filter_node" }, "minItems": 1 }, "kind": { "description": "Discriminator indicating this is a nested filter group.", "type": "string", "enum": [ "group" ] } }, "required": [ "kind", "filterCombination", "filters" ], "type": "object" }, { "$ref": "#/components/schemas/workers-observability_filter_leaf" } ], "description": "Supports nested groups via kind: 'group'. Maximum nesting depth is 4." } ] }, "default": [] }, "key": { "type": "string" }, "limit": { "type": "number", "default": 50 }, "needle": { "description": "Full-text search expression to match events containing the specified text or pattern.", "type": "object", "properties": { "isRegex": { "description": "When true, treats the value as a regular expression (RE2 syntax).", "type": "boolean" }, "matchCase": { "description": "When true, performs a case-sensitive search. Defaults to case-insensitive.", "type": "boolean" }, "value": { "description": "The text or pattern to search for.", "allOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "maxLength": 1000, "type": "string" } ] } }, "required": [ "value" ] }, "timeframe": { "type": "object", "properties": { "from": { "type": "number" }, "to": { "type": "number" } }, "required": [ "to", "from" ] }, "type": { "type": "string", "enum": [ "string", "boolean", "number" ] } }, "required": [ "timeframe", "key", "type", "datasets" ] } } } }, "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "array", "items": { "properties": { "dataset": { "type": "string" }, "key": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "boolean", "number" ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "key", "type", "value", "dataset" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Bad Request" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Forbidden" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Too many requests" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "504": { "description": "Gateway timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Gateway timeout" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Values" ], "x-api-token-group": [ "Workers Observability Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "observability.telemetry", "x-fern-sdk-method-name": "values" } }, "/accounts/{account_id}/workers/observability/usage": { "get": { "operationId": "usage.get", "summary": "Get event count", "description": "Event counts broken down by dataset and service, bucketed by day, for up to 90 days. The top-level events field is the sum of all breakdown counts.", "parameters": [ { "name": "from", "in": "query", "description": "Unix timestamp in milliseconds for the start of the range.", "required": true, "schema": { "description": "Unix timestamp in milliseconds for the start of the range.", "type": "string", "minLength": 1 } }, { "name": "to", "in": "query", "description": "Unix timestamp in milliseconds for the end of the range.", "required": true, "schema": { "description": "Unix timestamp in milliseconds for the end of the range.", "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "breakdown": { "description": "Event counts grouped by dataset and service, bucketed by day.", "type": "array", "items": { "properties": { "bin": { "description": "ISO-8601 timestamp for the start of the bucket.", "type": "string" }, "count": { "description": "ABR-adjusted event count for this bucket.", "type": "number" }, "dataset": { "description": "Dataset name (e.g. 'workers', 'queues').", "type": "string" }, "service": { "description": "Worker or service name that produced the events.", "type": "string" } }, "required": [ "bin", "dataset", "service", "count" ], "type": "object" } }, "events": { "description": "Total ABR-adjusted event count for the period — sum of all breakdown bins.", "type": "number" } }, "required": [ "events", "breakdown" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Bad Request" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Forbidden" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Too many requests" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "504": { "description": "Gateway timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Gateway timeout" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Usage" ], "x-api-token-group": [ "Workers Observability Write", "Workers Observability Read" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "observability", "x-fern-sdk-method-name": "usage", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "description": "Your Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ] }, "/accounts/{account_id}/workers/observability/zones/{zone_id}/observability/tracing/rules": { "get": { "operationId": "zone.observability.tracing.rules.get", "summary": "View zone trace rules", "description": "Retrieve the ordered sampling overrides for a zone's managed Cloudflare Traces ruleset.", "parameters": [ { "name": "zone_id", "in": "path", "description": "Specify the zone ID.", "required": true, "schema": { "description": "Specify the zone ID.", "type": "string" } } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "rules": { "description": "Trace rules in evaluation order.", "type": "array", "items": { "additionalProperties": false, "properties": { "action": { "type": "string", "enum": [ "set_trace_settings" ] }, "action_parameters": { "type": "object", "additionalProperties": false, "properties": { "sampling_ratio": { "description": "The ratio of requests sampled for tracing, from 0 to 1.", "type": "number", "maximum": 1, "minimum": 0 } }, "required": [ "sampling_ratio" ] }, "description": { "type": "string", "maxLength": 1000 }, "enabled": { "type": "boolean" }, "expression": { "description": "A Rules language expression that selects requests.", "type": "string", "maxLength": 4096, "minLength": 1 } }, "required": [ "action", "action_parameters", "expression", "description", "enabled" ], "type": "object" }, "maxItems": 1000 } }, "required": [ "rules" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Bad Request" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Forbidden" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Observability" ], "x-api-token-group": [ "Workers Observability Write", "Workers Observability Read" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "observability.tracing.rules", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "description": "Your Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "put": { "operationId": "zone.observability.tracing.rules.update", "summary": "Replace zone trace rules", "description": "Replace all sampling overrides in a zone's managed Cloudflare Traces ruleset. Rules are evaluated in the supplied order.", "parameters": [ { "name": "zone_id", "in": "path", "description": "Specify the zone ID.", "required": true, "schema": { "description": "Specify the zone ID.", "type": "string" } } ], "requestBody": { "description": "Replace the ordered trace rules", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "description": "Trace rules in evaluation order.", "type": "array", "items": { "additionalProperties": false, "properties": { "action": { "type": "string", "enum": [ "set_trace_settings" ] }, "action_parameters": { "type": "object", "additionalProperties": false, "properties": { "sampling_ratio": { "description": "The ratio of requests sampled for tracing, from 0 to 1.", "type": "number", "maximum": 1, "minimum": 0 } }, "required": [ "sampling_ratio" ] }, "description": { "type": "string", "maxLength": 1000 }, "enabled": { "type": "boolean" }, "expression": { "description": "A Rules language expression that selects requests.", "type": "string", "maxLength": 4096, "minLength": 1 } }, "required": [ "action", "action_parameters", "expression", "description", "enabled" ], "type": "object" }, "maxItems": 1000 } }, "required": [ "rules" ] } } } }, "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "rules": { "description": "Trace rules in evaluation order.", "type": "array", "items": { "additionalProperties": false, "properties": { "action": { "type": "string", "enum": [ "set_trace_settings" ] }, "action_parameters": { "type": "object", "additionalProperties": false, "properties": { "sampling_ratio": { "description": "The ratio of requests sampled for tracing, from 0 to 1.", "type": "number", "maximum": 1, "minimum": 0 } }, "required": [ "sampling_ratio" ] }, "description": { "type": "string", "maxLength": 1000 }, "enabled": { "type": "boolean" }, "expression": { "description": "A Rules language expression that selects requests.", "type": "string", "maxLength": 4096, "minLength": 1 } }, "required": [ "action", "action_parameters", "expression", "description", "enabled" ], "type": "object" }, "maxItems": 1000 } }, "required": [ "rules" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Bad Request" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Forbidden" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Observability" ], "x-api-token-group": [ "Workers Observability Write" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "observability.tracing.rules", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/observability/zones/{zone_id}/observability/tracing/settings": { "get": { "operationId": "zone.observability.tracing.settings.get", "summary": "View zone tracing settings", "description": "Retrieve the zone-level Cloudflare Traces settings.", "parameters": [ { "name": "zone_id", "in": "path", "description": "Specify the zone ID.", "required": true, "schema": { "description": "Specify the zone ID.", "type": "string" } } ], "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "additionalProperties": false, "properties": { "destinations": { "description": "OpenTelemetry destination identifiers that receive traces.", "type": "array", "items": { "maxLength": 256, "minLength": 1, "type": "string" }, "maxItems": 100 }, "enabled": { "description": "Whether Cloudflare Traces is enabled for the zone.", "type": "boolean" }, "forward_context": { "description": "Whether trace context is sent externally or across a zone boundary.", "type": "boolean" }, "persist": { "description": "Whether traces are persisted in Cloudflare.", "type": "boolean" }, "propagation_policy": { "description": "When inbound trace context may be continued.", "type": "string", "enum": [ "authenticated", "unauthenticated" ] }, "sampling_ratio": { "description": "The ratio of requests sampled for tracing, from 0 to 1.", "type": "number", "maximum": 1, "minimum": 0 } }, "required": [ "enabled", "persist", "sampling_ratio", "destinations", "propagation_policy", "forward_context" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Bad Request" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Forbidden" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Observability" ], "x-api-token-group": [ "Workers Observability Write", "Workers Observability Read" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "observability.tracing.settings", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "name": "account_id", "in": "path", "description": "Your Cloudflare account ID.", "required": true, "schema": { "type": "string" } } ], "patch": { "operationId": "zone.observability.tracing.settings.update", "summary": "Update zone tracing settings", "description": "Update the zone-level Cloudflare Traces settings.", "parameters": [ { "name": "zone_id", "in": "path", "description": "Specify the zone ID.", "required": true, "schema": { "description": "Specify the zone ID.", "type": "string" } } ], "requestBody": { "description": "Update zone tracing settings", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destinations": { "description": "OpenTelemetry destination identifiers that receive traces.", "type": "array", "items": { "maxLength": 256, "minLength": 1, "type": "string" }, "maxItems": 100 }, "enabled": { "description": "Whether Cloudflare Traces is enabled for the zone.", "type": "boolean" }, "forward_context": { "description": "Whether trace context is sent externally or across a zone boundary.", "type": "boolean" }, "persist": { "description": "Whether traces are persisted in Cloudflare.", "type": "boolean" }, "propagation_policy": { "description": "When inbound trace context may be continued.", "type": "string", "enum": [ "authenticated", "unauthenticated" ] }, "sampling_ratio": { "description": "The ratio of requests sampled for tracing, from 0 to 1.", "type": "number", "maximum": 1, "minimum": 0 } }, "additionalProperties": false, "minProperties": 1 } } } }, "responses": { "200": { "description": "Successful request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string", "enum": [ "Successful request" ] } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object", "additionalProperties": false, "properties": { "destinations": { "description": "OpenTelemetry destination identifiers that receive traces.", "type": "array", "items": { "maxLength": 256, "minLength": 1, "type": "string" }, "maxItems": 100 }, "enabled": { "description": "Whether Cloudflare Traces is enabled for the zone.", "type": "boolean" }, "forward_context": { "description": "Whether trace context is sent externally or across a zone boundary.", "type": "boolean" }, "persist": { "description": "Whether traces are persisted in Cloudflare.", "type": "boolean" }, "propagation_policy": { "description": "When inbound trace context may be continued.", "type": "string", "enum": [ "authenticated", "unauthenticated" ] }, "sampling_ratio": { "description": "The ratio of requests sampled for tracing, from 0 to 1.", "type": "number", "maximum": 1, "minimum": 0 } }, "required": [ "enabled", "persist", "sampling_ratio", "destinations", "propagation_policy", "forward_context" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "messages", "success", "errors", "result" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Bad Request" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Unauthorized" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Forbidden" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "detail": { "type": "string" }, "message": { "type": "string", "enum": [ "Internal error" ] } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "errors", "success", "messages" ] } } } } }, "tags": [ "Observability" ], "x-api-token-group": [ "Workers Observability Write" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "observability.tracing.settings", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/placement/regions": { "get": { "operationId": "worker-placement-list-regions", "summary": "List Placement Regions", "description": "Returns a list of available placement regions organized by cloud provider. These regions can be used to configure Smart Placement for Workers.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } } ], "responses": { "200": { "description": "List Placement Regions response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_placement-regions-response" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "List Placement Regions response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Placement" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.placement.regions", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts": { "get": { "operationId": "worker-script-list-workers", "summary": "List Workers", "description": "Fetch a list of uploaded workers.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "tags", "in": "query", "description": "Filter scripts by tags. Format: comma-separated list of tag:allowed pairs where allowed is 'yes' or 'no'.", "schema": { "type": "string", "example": "production:yes,staging:no" } } ], "responses": { "200": { "description": "List Workers response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_script-response-collection" } } } }, "4XX": { "description": "List Workers response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts-search": { "get": { "operationId": "worker-script-search-workers", "summary": "Search Workers", "description": "Search for Workers in an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "name", "in": "query", "schema": { "description": "Worker name to search for. Both exact and partial matches are returned.", "type": "string", "example": "my-worker" } }, { "name": "id", "in": "query", "schema": { "description": "Worker ID (also called tag) to search for. Only exact matches are returned.", "type": "string", "example": "bdf3567828824b74aadd550004cf4913" } }, { "name": "order_by", "in": "query", "schema": { "description": "Property to sort results by. Results are sorted in ascending order.", "type": "string", "example": "created_on", "default": "name", "enum": [ "created_on", "modified_on", "name" ] } }, { "name": "page", "in": "query", "description": "Current page.", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per page.", "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Search Workers success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "properties": { "created_on": { "$ref": "#/components/schemas/workers_created_on" }, "environment_is_default": { "description": "Whether the environment is the default environment.", "type": "boolean", "example": true }, "environment_name": { "description": "Name of the environment.", "type": "string", "example": "production" }, "id": { "$ref": "#/components/schemas/workers_identifier" }, "modified_on": { "$ref": "#/components/schemas/workers_modified_on" }, "script_name": { "$ref": "#/components/schemas/workers_script_name" }, "service_name": { "description": "Name of the service.", "type": "string", "example": "my-service" } }, "required": [ "id", "script_name", "created_on", "modified_on" ], "type": "object" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Search Workers failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts", "x-fern-sdk-method-name": "search", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}": { "delete": { "operationId": "worker-script-delete-worker", "summary": "Delete Worker", "description": "Delete your worker. This call has no response body on a successful delete.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } }, { "name": "force", "in": "query", "description": "If set to true, delete will not be stopped by associated service binding, durable object, or other binding. Any of these associated bindings/durable objects will be deleted along with the script.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Delete Worker response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-null-result" } } } }, "4XX": { "description": "Delete Worker response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "worker-script-download-worker", "summary": "Download Worker", "description": "Fetch raw script content for your worker. Note this is the original script content, not JSON encoded.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "Worker successfully downloaded. Returns script content as a multipart form, with no metadata part and no JSON encoding applied.", "content": { "application/javascript": { "schema": { "type": "string", "example": "export default {\n async fetch(request, env, ctx) {\n return new Response(\"Hello, world!\");\n }\n};\n" } }, "multipart/form-data": { "schema": { "type": "object", "additionalProperties": { "description": "Modules used by the Worker, including JavaScript files and source maps.", "format": "binary", "type": "string" } } } } }, "4XX": { "description": "Download Worker response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "worker-script-upload-worker-module", "summary": "Upload Worker Module", "description": "Upload a worker module. You can find more about the multipart metadata on our docs: https://developers.cloudflare.com/workers/configuration/multipart-upload-metadata/.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } }, { "name": "bindings_inherit", "in": "query", "description": "When set to \"strict\", the upload will fail if any `inherit` type bindings cannot be resolved against the previous version of the Worker. Without this, unresolvable inherit bindings are silently dropped.", "schema": { "type": "string", "enum": [ "strict" ] } } ], "requestBody": { "$ref": "#/components/requestBodies/workers_script_upload" }, "responses": { "200": { "description": "Upload Worker Module response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_script-response-upload-single" }, { "example": { "errors": [], "messages": [], "result": { "created_on": "2022-05-05T05:15:11.602148Z", "etag": "777f24a43bef5f69174aa69ceaf1dea67968d510a31d1vw3e49d34a0187c06d1", "handlers": [ "fetch" ], "id": "this-is_my_script-01", "logpush": false, "modified_on": "2022-05-20T19:02:56.446492Z", "placement": { "mode": "smart" }, "startup_time_ms": 10, "tail_consumers": [ { "environment": "production", "service": "my-log-consumer" } ], "usage_model": "standard" }, "success": true }, "type": "object" } ] } } } }, "4XX": { "description": "Upload Worker Module response failure. When the upload uses the\ndeclarative `exports` field and one or more entries fail\nreconciliation, the response is the exports reconciliation\nerror envelope (error code 100402) with per-class detail in\n`errors[].meta.details`.\n", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "$ref": "#/components/schemas/workers_exports_reconciliation_error_response" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}/assets-upload-session": { "post": { "operationId": "worker-script-update-create-assets-upload-session", "summary": "Create Assets Upload Session", "description": "Start uploading a collection of assets for use in a Worker version. To learn more about the direct uploads of assets, see https://developers.cloudflare.com/workers/static-assets/direct-upload/.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_create-assets-upload-session-object" } } } }, "responses": { "200": { "description": "Create Assets Upload Session response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_create-assets-upload-session-response" } } } }, "4XX": { "description": "Create Assets Upload Session response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_create-assets-upload-session-response" }, { "$ref": "#/components/schemas/workers_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.assets.upload", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}/content": { "put": { "operationId": "worker-script-put-content", "summary": "Put script content", "description": "Put script content without touching config or metadata.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } }, { "name": "CF-WORKER-BODY-PART", "in": "header", "description": "The multipart name of a script upload part containing script content in service worker format. Alternative to including in a metadata part.", "schema": { "type": "string" } }, { "name": "CF-WORKER-MAIN-MODULE-PART", "in": "header", "description": "The multipart name of a script upload part containing script content in es module format. Alternative to including in a metadata part.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "encoding": { "files": { "contentType": "application/javascript+module, text/javascript+module, application/javascript, text/javascript, text/x-python, text/x-python-requirement, application/wasm, text/plain, application/octet-stream, application/source-map" }, "metadata": { "contentType": "application/json" } }, "schema": { "type": "object", "properties": { "files": { "description": "An array of modules (often JavaScript files) comprising a Worker script. At least one module must be present and referenced in the metadata as `main_module` or `body_part` by filename.
Possible Content-Type(s) are: `application/javascript+module`, `text/javascript+module`, `application/javascript`, `text/javascript`, `text/x-python`, `text/x-python-requirement`, `application/wasm`, `text/plain`, `application/octet-stream`, `application/source-map`.", "type": "array", "items": { "format": "binary", "type": "string" }, "x-stainless-collection-type": "set" }, "metadata": { "description": "JSON-encoded metadata about the uploaded parts and Worker configuration.", "type": "object", "properties": { "body_part": { "description": "Name of the uploaded file that contains the Worker script (e.g. the file adding a listener to the `fetch` event). Indicates a `service worker syntax` Worker.", "type": "string", "example": "worker.js" }, "main_module": { "description": "Name of the uploaded file that contains the main module (e.g. the file exporting a `fetch` handler). Indicates a `module syntax` Worker.", "type": "string", "example": "worker.js" } } } }, "required": [ "metadata" ] } } } }, "responses": { "200": { "description": "Put script content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_script-response-single" } } } }, "4XX": { "description": "Put script content failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.content", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}/content/v2": { "get": { "operationId": "worker-script-get-content", "summary": "Get script content", "description": "Fetch script content only.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "Fetch script content.", "content": { "string": { "schema": { "type": "string", "example": "export default {\n async fetch(request, env, ctx) {\n return new Response(\"Hello, world!\");\n }\n};\n" } } } }, "4XX": { "description": "Fetch script content failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.content", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}/deployments": { "get": { "operationId": "worker-deployments-list-deployments", "summary": "List Deployments", "description": "List of Worker Deployments. The first deployment in the list is the latest deployment actively serving traffic.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "List Deployments response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "deployments": { "type": "array", "items": { "$ref": "#/components/schemas/workers_deployment" } } }, "required": [ "deployments" ] } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "List Deployments response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Deployments" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.deployments", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "worker-deployments-create-deployment", "summary": "Create Deployment", "description": "Deployments configure how [Worker Versions](https://developers.cloudflare.com/api/operations/worker-versions-list-versions) are deployed to traffic. A deployment can consist of one or two versions of a Worker.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } }, { "name": "force", "in": "query", "description": "If set to true, the deployment will be created even if normally blocked by something such rolling back to an older version when a secret has changed.", "schema": { "type": "boolean" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_deployment" } } } }, "responses": { "200": { "description": "Create Deployment response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_deployment" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Create Deployment response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Deployments" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.deployments", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}/deployments/{deployment_id}": { "delete": { "operationId": "worker-deployments-delete-deployment", "summary": "Delete Deployment", "description": "Delete a Worker Deployment. The latest deployment, which is actively serving traffic, cannot be deleted. All other deployments can be deleted.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } }, { "name": "deployment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Delete Deployment response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common" } } } }, "4XX": { "description": "Delete Deployment response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Deployments" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.deployments", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "worker-deployments-get-deployment", "summary": "Get Deployment", "description": "Get information about a Worker Deployment.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } }, { "name": "deployment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get Deployment response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_deployment" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Get Deployment response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Deployments" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.deployments", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}/schedules": { "get": { "operationId": "worker-cron-trigger-get-cron-triggers", "summary": "Get Cron Triggers", "description": "Fetches Cron Triggers for a Worker.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "Get Cron Triggers response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "schedules": { "type": "array", "items": { "$ref": "#/components/schemas/workers_schedule" } } }, "required": [ "schedules" ] } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Get Cron Triggers response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Cron Trigger" ], "x-api-token-group": [ "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.schedules", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "worker-cron-trigger-update-cron-triggers", "summary": "Update Cron Triggers", "description": "Updates Cron Triggers for a Worker.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/workers_schedule" } } } } }, "responses": { "200": { "description": "Update Cron Triggers response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "schedules": { "type": "array", "items": { "$ref": "#/components/schemas/workers_schedule" } } }, "required": [ "schedules" ] } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Update Cron Triggers response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Cron Trigger" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.schedules", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}/script-settings": { "get": { "operationId": "worker-script-settings-get-settings", "summary": "Get Script Settings", "description": "Get script-level settings when using [Worker Versions](https://developers.cloudflare.com/api/operations/worker-versions-list-versions). Includes Logpush and Tail Consumers.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "Fetch script settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_script-settings-response" } } } }, "4XX": { "description": "Fetch script settings failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.settings", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "worker-script-settings-patch-settings", "summary": "Patch Script Settings", "description": "Patch script-level settings when using [Worker Versions](https://developers.cloudflare.com/api/operations/worker-versions-list-versions). Including but not limited to Logpush and Tail Consumers.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_script-settings-item" } } } }, "responses": { "200": { "description": "Patch script settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_script-settings-response" } } } }, "4XX": { "description": "Patch script settings failure. When the patch uses the\ndeclarative `exports` field and one or more entries fail\nreconciliation, the response is the exports reconciliation\nerror envelope (error code 100402) with per-class detail in\n`errors[].meta.details`.\n", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "$ref": "#/components/schemas/workers_exports_reconciliation_error_response" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.settings", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}/secrets": { "get": { "operationId": "worker-list-script-secrets", "summary": "List script secrets", "description": "List secrets bound to a script.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "List script secrets.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/workers_secret" } } }, "type": "object" } ] } } } }, "4XX": { "description": "List script secrets failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.secrets", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "put": { "operationId": "worker-put-script-secret", "summary": "Add script secret", "description": "Add a secret to a script by creating a new version with that secret.\n\nWhen changing more than one secret at a time, prefer the \"Patch multiple\nscript secrets\" API instead of changing many secrets individually.\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_secret" } } } }, "responses": { "200": { "description": "Put script secret binding success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_secret" } }, "type": "object" } ] } } } }, "429": { "description": "Too many requests are currently modifying the script.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } }, "4XX": { "description": "Put script secret binding failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.secrets", "x-fern-sdk-method-name": "update", "x-forge-hidden": true, "x-forge-params": { "name": { "positional": true, "required": true } } } }, "/accounts/{account_id}/workers/scripts/{script_name}/secrets-bulk": { "patch": { "operationId": "worker-patch-script-secrets-bulk", "summary": "Patch multiple script secrets", "description": "Create, update, or delete multiple secrets on a script in a single operation using JSON Merge Patch (RFC 7396).\nThis operation creates a single version with all changes included.\nPrefer this API instead of changing many secrets individually.\n\nUsage:\n\n- To create or update a secret, set its value to a secret object.\n- To delete a secret, set its value to `null`.\n- Secrets not included in the request are left unchanged.\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_secret-patch-request" } }, "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/workers_secret-patch-request" } } } }, "responses": { "200": { "description": "Patch script secrets bulk success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_secret-patch-response" } }, "type": "object" } ] } } } }, "429": { "description": "Too many requests are currently modifying the script.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } }, "4XX": { "description": "Patch script secrets bulk failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.secrets", "x-fern-sdk-method-name": "bulk-edit", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}/secrets/{secret_name}": { "delete": { "operationId": "worker-delete-script-secret", "summary": "Delete script secret", "description": "Remove a secret from a script by creating a new version without that\nsecret.\n\nWhen changing more than one secret at a time, prefer the \"Patch multiple\nscript secrets\" API instead of changing many secrets individually.\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } }, { "name": "secret_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_secret_name" } }, { "name": "url_encoded", "in": "query", "schema": { "$ref": "#/components/schemas/workers_secret_name_url_encoded" } } ], "responses": { "200": { "description": "Delete script secret binding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-null-result" } } } }, "4XX": { "description": "Delete script secret failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.secrets", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "worker-get-script-secret", "summary": "Get secret binding", "description": "Get a given secret binding (value omitted) on a script.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } }, { "name": "secret_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_secret_name" } }, { "name": "url_encoded", "in": "query", "schema": { "$ref": "#/components/schemas/workers_secret_name_url_encoded" } } ], "responses": { "200": { "description": "Get script secret binding.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_secret" } }, "type": "object" } ] } } } }, "4XX": { "description": "Get script secret failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.secrets", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}/settings": { "get": { "operationId": "worker-script-get-settings", "summary": "Get Settings", "description": "Get metadata and config, such as bindings or usage model.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "Fetch settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_script-and-version-settings-response" } } } }, "4XX": { "description": "Fetch settings failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.script-and-version-settings", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "worker-script-patch-settings", "summary": "Patch Settings", "description": "Patch metadata or config, such as bindings or usage model.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "encoding": { "settings": { "contentType": "application/json" } }, "schema": { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/workers_script-and-version-settings-item" } } } } } }, "responses": { "200": { "description": "Patch settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_script-and-version-settings-response" } } } }, "4XX": { "description": "Patch settings failure. When the patch uses the declarative\n`exports` field and one or more entries fail reconciliation,\nthe response is the exports reconciliation error envelope\n(error code 100402) with per-class detail in\n`errors[].meta.details`.\n", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "$ref": "#/components/schemas/workers_exports_reconciliation_error_response" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.script-and-version-settings", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}/subdomain": { "delete": { "operationId": "worker-script-delete-subdomain", "summary": "Delete Worker subdomain", "description": "Disable all workers.dev subdomains for a Worker.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "Delete subdomain response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_subdomain" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Delete subdomain response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.subdomain", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "worker-script-get-subdomain", "summary": "Get Worker subdomain", "description": "Get if the Worker is available on the workers.dev subdomain.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "Get subdomain response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_subdomain" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Get subdomain response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.subdomain", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "worker-script-post-subdomain", "summary": "Post Worker subdomain", "description": "Enable or disable the Worker on the workers.dev subdomain.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "description": "Whether the Worker should be available on the workers.dev subdomain.", "type": "boolean", "example": true, "x-auditable": true }, "previews_enabled": { "description": "Whether the Worker's Preview URLs should be available on the workers.dev subdomain.", "type": "boolean", "example": false, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "enabled" ] } } } }, "responses": { "200": { "description": "Post subdomain response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_subdomain" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Post subdomain response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.subdomain", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}/tails": { "get": { "operationId": "worker-tail-logs-list-tails", "summary": "List Tails", "description": "Get list of tails currently deployed on a Worker.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "List Tails response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_tail" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "List Tails response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Tail Logs" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.tail", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "worker-tail-logs-start-tail", "summary": "Start Tail", "description": "Starts a tail that receives logs and exception from a Worker.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "Start Tail response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_tail" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Start Tail response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Tail Logs" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.tail", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}/tails/{id}": { "delete": { "operationId": "worker-tail-logs-delete-tail", "summary": "Delete Tail", "description": "Deletes a tail from a Worker.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } }, { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } } ], "responses": { "200": { "description": "Delete Tail response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common" } } } }, "4XX": { "description": "Delete Tail response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Tail Logs" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.tail", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}/usage-model": { "get": { "operationId": "worker-script-fetch-usage-model", "summary": "Fetch Usage Model", "description": "Fetches the Usage Model for a given Worker.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "responses": { "200": { "description": "Fetch Usage Model response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_usage-model-response" } } } }, "4XX": { "description": "Fetch Usage Model response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.usage-model", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "worker-script-update-usage-model", "summary": "Update Usage Model", "description": "Updates the Usage Model for a given Worker. Requires a Workers Paid subscription.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "usage_model": { "$ref": "#/components/schemas/workers_usage_model" }, "user_limits": { "$ref": "#/components/schemas/workers_user_limits" } } } } } }, "responses": { "200": { "description": "Update Usage Model response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_usage-model-response" } } } }, "4XX": { "description": "Update Usage Model response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Script" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.scripts.usage-model", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}/versions": { "get": { "operationId": "worker-versions-list-versions", "summary": "List Versions", "description": "List of Worker Versions. The first version in the list is the latest version.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name-2" } }, { "name": "deployable", "in": "query", "description": "Only return versions that can be used in a deployment. Ignores pagination.", "schema": { "type": "boolean", "default": false } }, { "name": "page", "in": "query", "description": "Current page.", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "description": "Items per-page.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List Versions response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_versions-list-response" } } } }, "4XX": { "description": "List Versions response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_versions-list-response" }, { "$ref": "#/components/schemas/workers_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Versions" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.versions", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "worker-versions-upload-version", "summary": "Upload Version", "description": "Upload a Worker Version without deploying to Cloudflare's network. You can find more about the multipart metadata on our docs: https://developers.cloudflare.com/workers/configuration/multipart-upload-metadata/.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name-2" } }, { "name": "bindings_inherit", "in": "query", "description": "When set to \"strict\", the upload will fail if any `inherit` type bindings cannot be resolved against the previous version of the Worker. Without this, unresolvable inherit bindings are silently dropped.", "schema": { "type": "string", "enum": [ "strict" ] } } ], "requestBody": { "$ref": "#/components/requestBodies/workers_version-post" }, "responses": { "200": { "description": "Upload Version response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_versions-upload-response" } } } }, "4XX": { "description": "Upload Version response failure. When the upload uses the\ndeclarative `exports` field and one or more entries fail\nreconciliation, the response is the exports reconciliation\nerror envelope (error code 100402) with per-class detail in\n`errors[].meta.details`.\n", "content": { "application/json": { "schema": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/workers_versions-upload-response" }, { "$ref": "#/components/schemas/workers_api-response-common-failure" } ] }, { "$ref": "#/components/schemas/workers_exports_reconciliation_error_response" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Versions" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.versions", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/scripts/{script_name}/versions/{version_id}": { "get": { "operationId": "worker-versions-get-version-detail", "summary": "Get Version Detail", "description": "Retrieves detailed information about a specific version of a Workers script.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "script_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_script_name-2" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_version_identifier" } } ], "responses": { "200": { "description": "Get Version Detail response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_versions-single-response" } } } }, "4XX": { "description": "Get Version Detail response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_versions-single-response" }, { "$ref": "#/components/schemas/workers_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Versions" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.versions", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/services/{service_name}/environments/{environment_name}/content": { "get": { "operationId": "worker-environment-get-script-content", "summary": "Get script content", "description": "Get script content from a worker with an environment.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "service_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_service" } }, { "name": "environment_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_environment" } } ], "responses": { "200": { "description": "Get script content.", "content": { "string": { "schema": { "type": "string", "example": "export default {\n async fetch(request, env, ctx) {\n return new Response(\"Hello, world!\");\n }\n};\n" } } } }, "4XX": { "description": "Get script content failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Environment" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.services.environments.content", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "worker-environment-put-script-content", "summary": "Put script content", "description": "Put script content from a worker with an environment.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "service_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_service" } }, { "name": "environment_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_environment" } }, { "name": "CF-WORKER-BODY-PART", "in": "header", "description": "The multipart name of a script upload part containing script content in service worker format. Alternative to including in a metadata part.", "schema": { "type": "string" } }, { "name": "CF-WORKER-MAIN-MODULE-PART", "in": "header", "description": "The multipart name of a script upload part containing script content in es module format. Alternative to including in a metadata part.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "encoding": { "files": { "contentType": "application/javascript+module, text/javascript+module, application/javascript, text/javascript, text/x-python, text/x-python-requirement, application/wasm, text/plain, application/octet-stream, application/source-map" }, "metadata": { "contentType": "application/json" } }, "schema": { "type": "object", "properties": { "files": { "description": "An array of modules (often JavaScript files) comprising a Worker script. At least one module must be present and referenced in the metadata as `main_module` or `body_part` by filename.
Possible Content-Type(s) are: `application/javascript+module`, `text/javascript+module`, `application/javascript`, `text/javascript`, `text/x-python`, `text/x-python-requirement`, `application/wasm`, `text/plain`, `application/octet-stream`, `application/source-map`.", "type": "array", "items": { "format": "binary", "type": "string" }, "x-stainless-collection-type": "set" }, "metadata": { "description": "JSON-encoded metadata about the uploaded parts and Worker configuration.", "type": "object", "properties": { "body_part": { "description": "Name of the part in the multipart request that contains the script (e.g. the file adding a listener to the `fetch` event). Indicates a `service worker syntax` Worker.", "type": "string", "example": "worker.js" }, "main_module": { "description": "Name of the part in the multipart request that contains the main module (e.g. the file exporting a `fetch` handler). Indicates a `module syntax` Worker.", "type": "string", "example": "worker.js" } } } }, "required": [ "metadata" ] } } } }, "responses": { "200": { "description": "Put script content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_script-response-single" } } } }, "4XX": { "description": "Put script content failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Environment" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.services.environments.content", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/services/{service_name}/environments/{environment_name}/settings": { "get": { "operationId": "worker-script-environment-get-settings", "summary": "Get Script Settings", "description": "Get script settings from a worker with an environment.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "service_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_service" } }, { "name": "environment_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_environment" } } ], "responses": { "200": { "description": "Fetch script settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_script-settings-response" } } } }, "4XX": { "description": "Fetch script settings failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Environment" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.services.environments.settings", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "worker-script-environment-patch-settings", "summary": "Patch Script Settings", "description": "Patch script metadata, such as bindings.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "service_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_service" } }, { "name": "environment_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_environment" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_script-settings-response" } } } }, "responses": { "200": { "description": "Patch script settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_script-settings-response" } } } }, "4XX": { "description": "Patch script settings failure. When the patch uses the\ndeclarative `exports` field and one or more entries fail\nreconciliation, the response is the exports reconciliation\nerror envelope (error code 100402) with per-class detail in\n`errors[].meta.details`.\n", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "$ref": "#/components/schemas/workers_exports_reconciliation_error_response" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Environment" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.services.environments.settings", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/subdomain": { "delete": { "operationId": "worker-subdomain-delete-subdomain", "summary": "Delete Subdomain", "description": "Deletes a Workers subdomain for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } } ], "responses": { "204": { "description": "Subdomain deleted successfully." }, "4XX": { "description": "Delete Subdomain response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Subdomain" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.subdomains", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "worker-subdomain-get-subdomain", "summary": "Get Subdomain", "description": "Returns a Workers subdomain for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } } ], "responses": { "200": { "description": "Get Subdomain response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_subdomain-2" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Get Subdomain response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Subdomain" ], "x-api-token-group": [ "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.subdomains", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "worker-subdomain-create-subdomain", "summary": "Create Subdomain", "description": "Creates a Workers subdomain for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_subdomain-2" } } } }, "responses": { "200": { "description": "Create Subdomain response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_subdomain-2" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Create Subdomain response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Subdomain" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.subdomains", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/workers": { "get": { "operationId": "listWorkers", "summary": "List Workers", "description": "List all Workers for an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "page", "in": "query", "description": "Current page.", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per-page.", "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1 } }, { "name": "order_by", "in": "query", "description": "Property to sort results by.", "schema": { "type": "string", "default": "deployed_on", "enum": [ "deployed_on", "updated_on", "created_on", "name" ] } }, { "name": "order", "in": "query", "description": "Sort direction.", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "List Workers success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/workers_Worker" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "401": { "$ref": "#/components/responses/workers_ErrorAuth" }, "500": { "$ref": "#/components/responses/workers_ErrorInternalServer" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.beta.workers", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "createWorker", "summary": "Create Worker", "description": "Create a new Worker.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } } ], "requestBody": { "description": "Worker creation parameters.", "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_Worker" }, { "required": [ "name" ], "type": "object" } ] } } } }, "responses": { "200": { "description": "Create Worker success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_Worker" } }, "required": [ "result" ], "type": "object" } ] } } } }, "400": { "description": "Bad Request - Invalid input data.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "properties": { "errors": { "type": "array", "items": { "discriminator": { "mapping": { "10016": "#/components/schemas/workers_ErrorWorkerNameInvalid", "10021": "#/components/schemas/workers_ErrorWorkerInvalid", "100102": "#/components/schemas/workers_ErrorWorkerTagLengthLimit", "100132": "#/components/schemas/workers_ErrorWorkerNameSubdomainLengthLimit", "100134": "#/components/schemas/workers_ErrorWorkerTagInvalid", "100308": "#/components/schemas/workers_ErrorWorkerObservabilitySamplingRateInvalid", "100315": "#/components/schemas/workers_ErrorWorkerNamePreviewLengthLimit" }, "propertyName": "code" }, "oneOf": [ { "$ref": "#/components/schemas/workers_ErrorWorkerNameInvalid" }, { "$ref": "#/components/schemas/workers_ErrorWorkerInvalid" }, { "$ref": "#/components/schemas/workers_ErrorWorkerTagLengthLimit" }, { "$ref": "#/components/schemas/workers_ErrorWorkerNameSubdomainLengthLimit" }, { "$ref": "#/components/schemas/workers_ErrorWorkerTagInvalid" }, { "$ref": "#/components/schemas/workers_ErrorWorkerObservabilitySamplingRateInvalid" }, { "$ref": "#/components/schemas/workers_ErrorWorkerNamePreviewLengthLimit" } ], "type": "object" } } }, "required": [ "errors" ], "type": "object" } ] } } } }, "401": { "$ref": "#/components/responses/workers_ErrorAuth" }, "403": { "description": "Forbidden - Access denied or limit exceeded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "properties": { "errors": { "type": "array", "items": { "discriminator": { "mapping": { "10037": "#/components/schemas/workers_ErrorWorkerLimit", "100103": "#/components/schemas/workers_ErrorWorkerTagLimit" }, "propertyName": "code" }, "oneOf": [ { "$ref": "#/components/schemas/workers_ErrorWorkerLimit" }, { "$ref": "#/components/schemas/workers_ErrorWorkerTagLimit" } ], "type": "object" } } }, "required": [ "errors" ], "type": "object" } ] } } } }, "409": { "description": "Conflict - Resource already exists.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "properties": { "errors": { "type": "array", "items": { "discriminator": { "mapping": { "10040": "#/components/schemas/workers_ErrorWorkerNameConflict" }, "propertyName": "code" }, "oneOf": [ { "$ref": "#/components/schemas/workers_ErrorWorkerNameConflict" } ], "type": "object" } } }, "required": [ "errors" ], "type": "object" } ] } } } }, "500": { "$ref": "#/components/responses/workers_ErrorInternalServer" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.beta.workers", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/workers/{worker_id}": { "delete": { "operationId": "deleteWorker", "summary": "Delete Worker", "description": "Delete a Worker and all its associated resources (versions, deployments, etc.).", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "worker_id", "in": "path", "required": true, "schema": { "description": "Identifier for the Worker, which can be ID or name.", "type": "string" } } ], "responses": { "200": { "description": "Delete Worker success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common" } } } }, "400": { "description": "Bad Request - Missing or invalid parameters.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "properties": { "errors": { "type": "array", "items": { "discriminator": { "mapping": { "10003": "#/components/schemas/workers_ErrorMissingParam" }, "propertyName": "code" }, "oneOf": [ { "$ref": "#/components/schemas/workers_ErrorMissingParam" } ], "type": "object" } } }, "required": [ "errors" ], "type": "object" } ] } } } }, "401": { "$ref": "#/components/responses/workers_ErrorAuth" }, "404": { "$ref": "#/components/responses/workers_ErrorWorkerNotFound" }, "500": { "$ref": "#/components/responses/workers_ErrorInternalServer" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.beta.workers", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "getWorker", "summary": "Get Worker", "description": "Get details about a specific Worker.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "worker_id", "in": "path", "required": true, "schema": { "description": "Identifier for the Worker, which can be ID or name.", "type": "string" } } ], "responses": { "200": { "description": "Get Worker success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_Worker" } }, "required": [ "result" ], "type": "object" } ] } } } }, "400": { "description": "Bad Request - Missing or invalid parameters.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "properties": { "errors": { "type": "array", "items": { "discriminator": { "mapping": { "10003": "#/components/schemas/workers_ErrorMissingParam" }, "propertyName": "code" }, "oneOf": [ { "$ref": "#/components/schemas/workers_ErrorMissingParam" } ], "type": "object" } } }, "required": [ "errors" ], "type": "object" } ] } } } }, "404": { "$ref": "#/components/responses/workers_ErrorWorkerNotFound" }, "500": { "$ref": "#/components/responses/workers_ErrorInternalServer" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.beta.workers", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "editWorker", "summary": "Edit Worker", "description": "Perform a partial update on a Worker, where omitted properties are left unchanged from their current values.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "worker_id", "in": "path", "required": true, "schema": { "description": "Identifier for the Worker, which can be ID or name.", "type": "string" } } ], "requestBody": { "description": "Worker partial update parameters.", "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_Worker" }, { "type": "object" } ] } }, "application/merge-patch+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_Worker" }, { "type": "object" } ] } } } }, "responses": { "200": { "description": "Partially Update Worker success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_Worker" } }, "required": [ "result" ], "type": "object" } ] } } } }, "400": { "description": "Bad Request - Invalid input data.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "properties": { "errors": { "type": "array", "items": { "discriminator": { "mapping": { "10003": "#/components/schemas/workers_ErrorMissingParam", "10016": "#/components/schemas/workers_ErrorWorkerNameInvalid", "10021": "#/components/schemas/workers_ErrorWorkerInvalid", "100102": "#/components/schemas/workers_ErrorWorkerTagLengthLimit", "100132": "#/components/schemas/workers_ErrorWorkerNameSubdomainLengthLimit", "100134": "#/components/schemas/workers_ErrorWorkerTagInvalid", "100308": "#/components/schemas/workers_ErrorWorkerObservabilitySamplingRateInvalid", "100315": "#/components/schemas/workers_ErrorWorkerNamePreviewLengthLimit" }, "propertyName": "code" }, "oneOf": [ { "$ref": "#/components/schemas/workers_ErrorMissingParam" }, { "$ref": "#/components/schemas/workers_ErrorWorkerNameInvalid" }, { "$ref": "#/components/schemas/workers_ErrorWorkerInvalid" }, { "$ref": "#/components/schemas/workers_ErrorWorkerTagLengthLimit" }, { "$ref": "#/components/schemas/workers_ErrorWorkerTagInvalid" }, { "$ref": "#/components/schemas/workers_ErrorWorkerNameSubdomainLengthLimit" }, { "$ref": "#/components/schemas/workers_ErrorWorkerNamePreviewLengthLimit" }, { "$ref": "#/components/schemas/workers_ErrorWorkerObservabilitySamplingRateInvalid" } ], "type": "object" } } }, "required": [ "errors" ], "type": "object" } ] } } } }, "401": { "$ref": "#/components/responses/workers_ErrorAuth" }, "403": { "description": "Forbidden - Insufficient permissions or quota exceeded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "properties": { "errors": { "type": "array", "items": { "discriminator": { "mapping": { "10037": "#/components/schemas/workers_ErrorWorkerLimit", "100103": "#/components/schemas/workers_ErrorWorkerTagLimit" }, "propertyName": "code" }, "oneOf": [ { "$ref": "#/components/schemas/workers_ErrorWorkerLimit" }, { "$ref": "#/components/schemas/workers_ErrorWorkerTagLimit" } ], "type": "object" } } }, "required": [ "errors" ], "type": "object" } ] } } } }, "404": { "$ref": "#/components/responses/workers_ErrorWorkerNotFound" }, "409": { "description": "Conflict - Worker name already exists.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "properties": { "errors": { "type": "array", "items": { "discriminator": { "mapping": { "10040": "#/components/schemas/workers_ErrorWorkerNameConflict" }, "propertyName": "code" }, "oneOf": [ { "$ref": "#/components/schemas/workers_ErrorWorkerNameConflict" } ], "type": "object" } } }, "required": [ "errors" ], "type": "object" } ] } } } }, "500": { "$ref": "#/components/responses/workers_ErrorInternalServer" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.beta.workers", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "updateWorker", "summary": "Update Worker", "description": "Perform a complete replacement of a Worker, where omitted properties are set to their default values. This is the exact same as the Create Worker endpoint, but operates on an existing Worker. To perform a partial update instead, use the Edit Worker endpoint.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "worker_id", "in": "path", "required": true, "schema": { "description": "Identifier for the Worker, which can be ID or name.", "type": "string" } } ], "requestBody": { "description": "Worker update parameters.", "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_Worker" }, { "required": [ "name" ], "type": "object" } ] } } } }, "responses": { "200": { "description": "Update Worker success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_Worker" } }, "required": [ "result" ], "type": "object" } ] } } } }, "400": { "description": "Bad Request - Invalid input data.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "properties": { "errors": { "type": "array", "items": { "discriminator": { "mapping": { "10003": "#/components/schemas/workers_ErrorMissingParam", "10016": "#/components/schemas/workers_ErrorWorkerNameInvalid", "10021": "#/components/schemas/workers_ErrorWorkerInvalid", "100102": "#/components/schemas/workers_ErrorWorkerTagLengthLimit", "100132": "#/components/schemas/workers_ErrorWorkerNameSubdomainLengthLimit", "100134": "#/components/schemas/workers_ErrorWorkerTagInvalid", "100308": "#/components/schemas/workers_ErrorWorkerObservabilitySamplingRateInvalid", "100315": "#/components/schemas/workers_ErrorWorkerNamePreviewLengthLimit" }, "propertyName": "code" }, "oneOf": [ { "$ref": "#/components/schemas/workers_ErrorMissingParam" }, { "$ref": "#/components/schemas/workers_ErrorWorkerNameInvalid" }, { "$ref": "#/components/schemas/workers_ErrorWorkerInvalid" }, { "$ref": "#/components/schemas/workers_ErrorWorkerTagLengthLimit" }, { "$ref": "#/components/schemas/workers_ErrorWorkerTagInvalid" }, { "$ref": "#/components/schemas/workers_ErrorWorkerNameSubdomainLengthLimit" }, { "$ref": "#/components/schemas/workers_ErrorWorkerNamePreviewLengthLimit" }, { "$ref": "#/components/schemas/workers_ErrorWorkerObservabilitySamplingRateInvalid" } ], "type": "object" } } }, "required": [ "errors" ], "type": "object" } ] } } } }, "401": { "$ref": "#/components/responses/workers_ErrorAuth" }, "403": { "description": "Forbidden - Insufficient permissions or quota exceeded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "properties": { "errors": { "type": "array", "items": { "discriminator": { "mapping": { "10037": "#/components/schemas/workers_ErrorWorkerLimit", "100103": "#/components/schemas/workers_ErrorWorkerTagLimit" }, "propertyName": "code" }, "oneOf": [ { "$ref": "#/components/schemas/workers_ErrorWorkerLimit" }, { "$ref": "#/components/schemas/workers_ErrorWorkerTagLimit" } ], "type": "object" } } }, "required": [ "errors" ], "type": "object" } ] } } } }, "404": { "$ref": "#/components/responses/workers_ErrorWorkerNotFound" }, "409": { "description": "Conflict - Worker name already exists.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "properties": { "errors": { "type": "array", "items": { "discriminator": { "mapping": { "10040": "#/components/schemas/workers_ErrorWorkerNameConflict" }, "propertyName": "code" }, "oneOf": [ { "$ref": "#/components/schemas/workers_ErrorWorkerNameConflict" } ], "type": "object" } } }, "required": [ "errors" ], "type": "object" } ] } } } }, "500": { "$ref": "#/components/responses/workers_ErrorInternalServer" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Workers" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.beta.workers", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/workers/{worker_id}/versions": { "get": { "operationId": "listWorkerVersions", "summary": "List Versions", "description": "List all versions for a Worker.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "worker_id", "in": "path", "required": true, "schema": { "description": "Identifier for the Worker, which can be ID or name.", "type": "string" } }, { "name": "page", "in": "query", "description": "Current page.", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Items per-page.", "schema": { "type": "integer", "default": 10, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "List versions success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/workers_Version" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "List versions failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Versions" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.beta.workers.versions", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "createWorkerVersion", "summary": "Create Version", "description": "Create a new version.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "worker_id", "in": "path", "required": true, "schema": { "description": "Identifier for the Worker, which can be ID or name.", "type": "string" } }, { "name": "deploy", "in": "query", "schema": { "description": "If true, a deployment will be created that sends 100% of traffic to the new version.", "type": "boolean" } } ], "requestBody": { "description": "Version creation parameters.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_Version" } } } }, "responses": { "200": { "description": "Create version success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_Version" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Create version failure. When the upload uses the declarative\n`exports` field and one or more entries fail reconciliation,\nthe response is the exports reconciliation error envelope\n(error code 100402) with per-class detail in\n`errors[].meta.details`.\n", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "$ref": "#/components/schemas/workers_exports_reconciliation_error_response" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Versions" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.beta.workers.versions", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/workers/{worker_id}/versions/latest": { "patch": { "operationId": "patchLatestWorkerVersion", "summary": "Patch Latest Version", "description": "Only `/versions/latest` is supported. Creates a new version by applying a JSON Merge Patch (RFC 7396) to the latest version. Patching a specific version ID is not supported. Omitted fields are inherited from the latest version.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "worker_id", "in": "path", "required": true, "schema": { "description": "Identifier for the Worker, which can be ID or name.", "type": "string" } }, { "name": "deploy", "in": "query", "schema": { "description": "If true, a deployment will be created that sends 100% of traffic to the new version.", "type": "boolean" } } ], "requestBody": { "description": "JSON Merge Patch to apply to the latest version. An empty object creates a new version with no changes.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_Version" }, { "type": "object" } ] } }, "application/merge-patch+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_Version" }, { "type": "object" } ] } } } }, "responses": { "200": { "description": "Patch version success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_Version" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Patch version failure. When the patch uses the declarative\n`exports` field and one or more entries fail reconciliation,\nthe response is the exports reconciliation error envelope\n(error code 100402) with per-class detail in\n`errors[].meta.details`.\n", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "$ref": "#/components/schemas/workers_exports_reconciliation_error_response" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Versions" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.beta.workers.versions", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/workers/workers/{worker_id}/versions/{version_id}": { "delete": { "operationId": "deleteWorkerVersion", "summary": "Delete Version", "description": "Delete a version.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "worker_id", "in": "path", "required": true, "schema": { "description": "Identifier for the Worker, which can be ID or name.", "type": "string" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "description": "Identifier for the version, which can be a UUID, a UUID prefix (minimum length 8), or the literal \"latest\" to operate on the most recently created version.", "type": "string" } } ], "responses": { "200": { "description": "Delete version success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common" } } } }, "4XX": { "description": "Delete version failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Versions" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.beta.workers.versions", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "getWorkerVersion", "summary": "Get Version", "description": "Get details about a specific version.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "worker_id", "in": "path", "required": true, "schema": { "description": "Identifier for the Worker, which can be ID or name.", "type": "string" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "description": "Identifier for the version, which can be a UUID, a UUID prefix (minimum length 8), or the literal \"latest\" to operate on the most recently created version.", "type": "string" } }, { "name": "include", "in": "query", "schema": { "description": "Whether to include the `modules` property of the version in the response, which contains code and sourcemap content and may add several megabytes to the response size.", "type": "string", "enum": [ "modules" ] } } ], "responses": { "200": { "description": "Get version success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_Version" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Get version failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Versions" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.beta.workers.versions", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/workflows": { "get": { "operationId": "wor-list-workflows", "summary": "List all Workflows", "description": "Lists all workflows configured for the account.", "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "number", "default": 10, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "number", "default": 1, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Allows filtering workflows` name.", "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of all Workflows belonging to a account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "array", "items": { "properties": { "class_name": { "type": "string" }, "created_on": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "instances": { "type": "object", "additionalProperties": { "type": "number" } }, "modified_on": { "type": "string", "format": "date-time" }, "name": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" }, "schedules": { "type": "array", "items": { "properties": { "cron": { "type": "string" }, "next_instance": { "type": "string" } }, "required": [ "cron", "next_instance" ], "type": "object" } }, "script_name": { "type": "string" }, "triggered_on": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "name", "id", "created_on", "modified_on", "script_name", "class_name", "triggered_on", "instances" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Input Validation Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows", "x-fern-sdk-method-name": "list" } }, "/accounts/{account_id}/workflows/settings": { "get": { "operationId": "wor-get-workflow-settings", "summary": "Get account settings", "description": "Retrieves account-level Workflows settings, such as the default instance retention.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Account settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "default_retention": { "type": "object", "properties": { "error_retention": { "description": "Default error retention in milliseconds.", "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "success_retention": { "description": "Default success retention in milliseconds.", "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } } } } }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.settings", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "wor-update-workflow-settings", "summary": "Update account settings", "description": "Updates only the account-level Workflows settings fields present in the request body.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "default_retention": { "description": "Default retention applied to instances of this version when they do not set their own retention.", "type": "object", "properties": { "error_retention": { "description": "Specifies the duration in milliseconds or as a string like '5 minutes'.", "anyOf": [ { "description": "Specifies the duration in milliseconds.", "type": "integer" }, { "example": "5 minutes", "pattern": "^(\\d+)\\s+(second|minute|hour|day|week|month|year)s?$", "type": "string" } ] }, "success_retention": { "description": "Specifies the duration in milliseconds or as a string like '5 minutes'.", "anyOf": [ { "description": "Specifies the duration in milliseconds.", "type": "integer" }, { "example": "5 minutes", "pattern": "^(\\d+)\\s+(second|minute|hour|day|week|month|year)s?$", "type": "string" } ] } } } } } } } }, "responses": { "200": { "description": "Updated account settings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "default_retention": { "type": "object", "properties": { "error_retention": { "description": "Default error retention in milliseconds.", "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "success_retention": { "description": "Default success retention in milliseconds.", "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } } } } }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.settings", "x-fern-sdk-method-name": "edit" } }, "/accounts/{account_id}/workflows/{workflow_name}": { "delete": { "operationId": "wor-delete-workflow", "summary": "Deletes a Workflow", "description": "Deletes a Workflow. This only deletes the Workflow and does not delete or modify any Worker associated to this Workflow or bounded to it.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deletes a Workflow.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "success": { "type": "boolean", "nullable": true } }, "required": [ "success", "status" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Workflow not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows", "x-fern-sdk-method-name": "delete", "x-forge-require-confirmation": "This operation permanently deletes the Workflow." }, "get": { "operationId": "wor-get-workflow-details", "summary": "Get Workflow details", "description": "Retrieves configuration and metadata for a specific workflow.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get Workflow details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "class_name": { "type": "string" }, "created_on": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "instances": { "type": "object", "additionalProperties": { "type": "number" } }, "modified_on": { "type": "string", "format": "date-time" }, "name": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" }, "schedules": { "type": "array", "items": { "properties": { "cron": { "type": "string" }, "next_instance": { "type": "string" } }, "required": [ "cron", "next_instance" ], "type": "object" } }, "script_name": { "type": "string" }, "triggered_on": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "name", "id", "created_on", "modified_on", "script_name", "class_name", "triggered_on", "instances" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Workflow has no deployed versions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Workflow not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows", "x-fern-sdk-method-name": "get" }, "put": { "operationId": "wor-create-or-modify-workflow", "summary": "Create/modify Workflow", "description": "Creates a new workflow or updates an existing workflow definition.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "class_name": { "type": "string", "maxLength": 255, "minLength": 1 }, "concurrency": { "type": "object", "properties": { "limit": { "description": "Maximum number of instances of this workflow that can run concurrently. Additional instances are queued and started as running instances complete. Must not exceed the account concurrency limit.", "type": "integer", "maximum": 9007199254740991, "minimum": 1 } } }, "default_retention": { "description": "Default retention applied to instances of this version when they do not set their own retention.", "type": "object", "properties": { "error_retention": { "description": "Specifies the duration in milliseconds or as a string like '5 minutes'.", "anyOf": [ { "description": "Specifies the duration in milliseconds.", "type": "integer" }, { "example": "5 minutes", "pattern": "^(\\d+)\\s+(second|minute|hour|day|week|month|year)s?$", "type": "string" } ] }, "success_retention": { "description": "Specifies the duration in milliseconds or as a string like '5 minutes'.", "anyOf": [ { "description": "Specifies the duration in milliseconds.", "type": "integer" }, { "example": "5 minutes", "pattern": "^(\\d+)\\s+(second|minute|hour|day|week|month|year)s?$", "type": "string" } ] } } }, "limits": { "type": "object", "properties": { "steps": { "type": "integer", "maximum": 9007199254740991, "minimum": 1 } } }, "schedules": { "type": "array", "items": { "properties": { "cron": { "type": "string", "maxLength": 256, "minLength": 1 } }, "required": [ "cron" ], "type": "object" }, "maxItems": 200 }, "script_name": { "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "script_name", "class_name" ] } } } }, "responses": { "200": { "description": "Create/modify a Workflow based on a deployed script with an existing `WorkflowEntrypoint` class. Must be done after deploying the corresponding script.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "class_name": { "type": "string" }, "created_on": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "is_deleted": { "type": "number" }, "modified_on": { "type": "string", "format": "date-time" }, "name": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" }, "script_name": { "type": "string" }, "terminator_running": { "type": "number" }, "triggered_on": { "type": "string", "format": "date-time", "nullable": true }, "version_id": { "type": "string", "format": "uuid" } }, "required": [ "version_id", "name", "id", "created_on", "modified_on", "script_name", "class_name", "triggered_on", "is_deleted", "terminator_running" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "workflows", "x-fern-sdk-method-name": "update" } }, "/accounts/{account_id}/workflows/{workflow_name}/instances": { "get": { "operationId": "wor-list-workflow-instances", "summary": "List of workflow instances", "description": "Lists all instances of a workflow with their execution status.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "page", "in": "query", "description": "Deprecated: use `cursor` for pagination instead.", "schema": { "type": "number", "deprecated": true, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "number", "default": 50, "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Opaque token for cursor-based pagination. Mutually exclusive with `page`.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "description": "Defines the direction for cursor-based pagination.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "running", "paused", "errored", "terminated", "complete", "waitingForPause", "waiting", "rollingBack" ] } }, { "name": "date_start", "in": "query", "description": "Accepts ISO 8601 with no timezone offsets and in UTC.", "schema": { "type": "string", "format": "date-time" } }, { "name": "date_end", "in": "query", "description": "Accepts ISO 8601 with no timezone offsets and in UTC.", "schema": { "type": "string", "format": "date-time" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of workflow instances.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "array", "items": { "properties": { "created_on": { "type": "string", "format": "date-time" }, "ended_on": { "type": "string", "format": "date-time", "nullable": true }, "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" }, "modified_on": { "type": "string", "format": "date-time" }, "started_on": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "enum": [ "queued", "running", "paused", "errored", "terminated", "complete", "waitingForPause", "waiting", "rollingBack" ] }, "trigger_source": { "type": "string", "enum": [ "unknown", "api", "binding", "event", "cron" ] }, "version_id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" } }, "required": [ "id", "created_on", "modified_on", "started_on", "ended_on", "workflow_id", "version_id", "status" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "description": "Deprecated: use cursor-based pagination instead.", "type": "number", "deprecated": true }, "per_page": { "type": "number" }, "total_count": { "description": "Deprecated: cursor-based pagination can produce an inaccurate total count.", "type": "number", "deprecated": true }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Input Validation Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Workflow Name not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.instances", "x-fern-sdk-method-name": "list", "x-forge-params": { "date_end": { "flagName": "end" }, "date_start": { "flagName": "start" } } }, "post": { "operationId": "wor-create-new-workflow-instance", "summary": "Create a new workflow instance", "description": "Creates a new instance of a workflow, starting its execution.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_id": { "description": "The system reserves IDs that consist of the `cf_` prefix and exactly 64 lowercase hexadecimal characters.", "type": "string", "maximum": 100, "minimum": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" }, "instance_retention": { "type": "object", "properties": { "error_retention": { "description": "Specifies the duration in milliseconds or as a string like '5 minutes'.", "anyOf": [ { "description": "Specifies the duration in milliseconds.", "type": "integer" }, { "example": "5 minutes", "pattern": "^(\\d+)\\s+(second|minute|hour|day|week|month|year)s?$", "type": "string" } ] }, "success_retention": { "description": "Specifies the duration in milliseconds or as a string like '5 minutes'.", "anyOf": [ { "description": "Specifies the duration in milliseconds.", "type": "integer" }, { "example": "5 minutes", "pattern": "^(\\d+)\\s+(second|minute|hour|day|week|month|year)s?$", "type": "string" } ] } } }, "location_hint": { "type": "string", "enum": [ "wnam", "weur", "enam", "eeur", "apac", "apac-ne", "apac-se", "oc", "sam", "afr", "me" ] }, "params": { "description": "JSON-encoded event payload passed into the new instance.", "type": "string" } } } } } }, "responses": { "200": { "description": "Create workflow instance. Body is a JSON parsable string that it's passed into the new instance as the event payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" }, "status": { "type": "string", "enum": [ "queued", "running", "paused", "errored", "terminated", "complete", "waitingForPause", "waiting", "rollingBack" ] }, "trigger_source": { "type": "string", "enum": [ "unknown", "api", "binding", "event", "cron" ] }, "version_id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" } }, "required": [ "id", "workflow_id", "version_id", "status" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Provided Workflow ID is not valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Workflow Name not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.instances", "x-fern-sdk-method-name": "create", "x-forge-params": { "instance_retention.error_retention": { "flagName": "error-retention" }, "instance_retention.success_retention": { "flagName": "success-retention" }, "params": { "fromFile": { "format": "json" } } } } }, "/accounts/{account_id}/workflows/{workflow_name}/instances/batch": { "post": { "operationId": "wor-batch-create-workflow-instance", "summary": "Batch create new Workflow instances", "description": "Creates multiple workflow instances in a single batch operation.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "instance_id": { "description": "The system reserves IDs that consist of the `cf_` prefix and exactly 64 lowercase hexadecimal characters.", "type": "string", "maximum": 100, "minimum": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" }, "instance_retention": { "type": "object", "properties": { "error_retention": { "description": "Specifies the duration in milliseconds or as a string like '5 minutes'.", "anyOf": [ { "description": "Specifies the duration in milliseconds.", "type": "integer" }, { "example": "5 minutes", "pattern": "^(\\d+)\\s+(second|minute|hour|day|week|month|year)s?$", "type": "string" } ] }, "success_retention": { "description": "Specifies the duration in milliseconds or as a string like '5 minutes'.", "anyOf": [ { "description": "Specifies the duration in milliseconds.", "type": "integer" }, { "example": "5 minutes", "pattern": "^(\\d+)\\s+(second|minute|hour|day|week|month|year)s?$", "type": "string" } ] } } }, "location_hint": { "type": "string", "enum": [ "wnam", "weur", "enam", "eeur", "apac", "apac-ne", "apac-se", "oc", "sam", "afr", "me" ] }, "params": { "description": "JSON-encoded event payload passed into the new instance.", "type": "string" } }, "type": "object" }, "maxItems": 100, "minItems": 1 } } } }, "responses": { "200": { "description": "Batch create workflow instances. Body is a JSON list that contain all payloads and ids that are passed into the new instance as the event payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "array", "items": { "properties": { "id": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" }, "status": { "type": "string", "enum": [ "queued", "running", "paused", "errored", "terminated", "complete", "waitingForPause", "waiting", "rollingBack" ] }, "trigger_source": { "type": "string", "enum": [ "unknown", "api", "binding", "event", "cron" ] }, "version_id": { "type": "string", "format": "uuid" }, "workflow_id": { "type": "string", "format": "uuid" } }, "required": [ "id", "workflow_id", "version_id", "status" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Provided Workflow ID is not valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Workflow Name not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.instances.batch", "x-fern-sdk-method-name": "create" } }, "/accounts/{account_id}/workflows/{workflow_name}/instances/batch/delete": { "post": { "operationId": "wor-batch-delete-workflow-instances", "summary": "Batch delete instances of a workflow", "description": "Deletes multiple workflow instances in a single batch operation.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instances": { "type": "array", "items": { "description": "Instance identifier. Accepts user-created IDs (`^[a-zA-Z0-9_][a-zA-Z0-9-_]*$`, maximum 100 characters) and system-generated IDs that consist of a `cf_` or `-` prefix and exactly 64 lowercase hexadecimal characters.", "maxLength": 100, "minLength": 1, "pattern": "^(-[0-9a-f]{64}|[a-zA-Z0-9_][a-zA-Z0-9-_]*)$", "type": "string" }, "maxItems": 100, "minItems": 1 } }, "required": [ "instances" ] } } } }, "responses": { "200": { "description": "Returns deleted instances and any per-instance errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "deleted": { "type": "array", "items": { "properties": { "id": { "type": "string" } }, "required": [ "id" ], "type": "object" } }, "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "id": { "type": "string" }, "message": { "type": "string" } }, "required": [ "id", "code", "message" ], "type": "object" } } }, "required": [ "deleted", "errors" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Input Validation Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Workflow Name not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "workflows.instances.batch", "x-fern-sdk-method-name": "delete" } }, "/accounts/{account_id}/workflows/{workflow_name}/instances/batch/terminate": { "post": { "operationId": "wor-batch-terminate-workflow-instances", "summary": "Batch terminate instances of a workflow", "description": "Performs a batch termination of multiple workflow instances.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "maxLength": 100, "minLength": 1, "pattern": "^(-[0-9a-f]{64}|[a-zA-Z0-9_][a-zA-Z0-9-_]*)$", "type": "string" }, "maxItems": 100, "minItems": 1 } } } }, "responses": { "200": { "description": "Batch terminate instances of a workflow, via a async job. Body is a JSON list that contain the ids of the instances to terminate.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "instancesTerminated": { "type": "number" }, "status": { "type": "string", "enum": [ "ok", "already_running" ] } }, "required": [ "status", "instancesTerminated" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Provided Workflow ID is not valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Workflow Name not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "workflows.instances.batch", "x-fern-sdk-method-name": "terminate" } }, "/accounts/{account_id}/workflows/{workflow_name}/instances/terminate": { "get": { "operationId": "wor-status-terminate-workflow-instances", "summary": "Get status of the job responsible for terminate all instances of a workflow", "description": "Gets the status of a bulk workflow instance termination job.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get status of the job responsible for terminate all instances of a workflow.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "running", "not_running" ] } }, "required": [ "status" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Input Validation Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Workflow Name not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "workflows.instances.batch", "x-fern-sdk-method-name": "termination-status" } }, "/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}": { "delete": { "operationId": "wor-delete-workflow-instance", "summary": "Delete a workflow instance", "description": "Deletes a workflow instance and its stored state.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "instance_id", "in": "path", "description": "Instance identifier. User-created instances match `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$` (max 100 characters); cron-triggered instances can use a longer, system-generated id derived from the cron expression.", "required": true, "schema": { "type": "string", "maxLength": 271, "minLength": 1 } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Instance deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "instanceId": { "type": "string" }, "timestamp": { "description": "Accepts ISO 8601 with no timezone offsets and in UTC.", "type": "string", "format": "date-time" } }, "required": [ "instanceId", "timestamp" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "404": { "description": "Workflow not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.instances", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "wor-describe-workflow-instance", "summary": "Get logs and status from instance", "description": "Retrieves logs and execution status for a specific workflow instance.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "instance_id", "in": "path", "description": "Instance identifier. User-created instances match `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$` (max 100 characters); cron-triggered instances can use a longer, system-generated id derived from the cron expression.", "required": true, "schema": { "type": "string", "maxLength": 271, "minLength": 1 } }, { "name": "simple", "in": "query", "description": "When true, omits step details and returns only metadata with step_count.", "schema": { "type": "string", "default": "false", "enum": [ "true", "false" ] } }, { "name": "order", "in": "query", "description": "Step ordering: \"asc\" (default, oldest first) or \"desc\" (newest first).", "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get all logs and status from the instance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "end": { "type": "string", "format": "date-time", "nullable": true }, "error": { "type": "object", "nullable": true, "properties": { "message": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "message" ] }, "output": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "params": { "type": "object" }, "queued": { "type": "string", "format": "date-time" }, "rollback": { "type": "object", "nullable": true, "properties": { "error": { "type": "object", "nullable": true, "properties": { "message": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "message" ] }, "outcome": { "type": "string", "enum": [ "complete", "failed" ] } }, "required": [ "outcome", "error" ] }, "schedule": { "type": "object", "properties": { "cron": { "type": "string" }, "scheduledTime": { "type": "number" } }, "required": [ "cron", "scheduledTime" ] }, "start": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "enum": [ "queued", "running", "paused", "errored", "terminated", "complete", "waitingForPause", "waiting", "rollingBack" ] }, "step_count": { "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "steps": { "type": "array", "items": { "anyOf": [ { "properties": { "attempts": { "type": "array", "items": { "properties": { "end": { "type": "string", "format": "date-time", "nullable": true }, "error": { "type": "object", "nullable": true, "properties": { "message": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "message" ] }, "start": { "type": "string", "format": "date-time" }, "success": { "type": "boolean", "nullable": true } }, "required": [ "start", "end", "success", "error" ], "type": "object" } }, "config": { "type": "object", "properties": { "retries": { "type": "object", "properties": { "backoff": { "type": "string", "enum": [ "constant", "linear", "exponential" ] }, "delay": { "description": "Specifies the delay duration. The value '[dynamic]' means that a user-supplied function computes the delay.", "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "limit": { "type": "number" } }, "required": [ "limit", "delay" ] }, "sensitive": { "description": "When set to 'output', step output is redacted from log and step output responses.", "type": "string", "enum": [ "output" ] }, "timeout": { "description": "Specifies the timeout duration.", "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "retries", "timeout" ] }, "end": { "type": "string", "format": "date-time", "nullable": true }, "name": { "type": "string" }, "output": { "type": "string", "nullable": true }, "start": { "type": "string", "format": "date-time" }, "success": { "type": "boolean", "nullable": true }, "type": { "type": "string", "enum": [ "step", "rollback" ] } }, "required": [ "name", "start", "end", "attempts", "config", "output", "success", "type" ], "type": "object" }, { "properties": { "end": { "type": "string", "format": "date-time" }, "error": { "type": "object", "nullable": true, "properties": { "message": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "message" ] }, "finished": { "type": "boolean" }, "name": { "type": "string" }, "start": { "type": "string", "format": "date-time" }, "type": { "type": "string", "enum": [ "sleep" ] } }, "required": [ "name", "start", "end", "finished", "type", "error" ], "type": "object" }, { "properties": { "trigger": { "type": "object", "properties": { "source": { "type": "string" } }, "required": [ "source" ] }, "type": { "type": "string", "enum": [ "termination" ] } }, "required": [ "type", "trigger" ], "type": "object" }, { "properties": { "end": { "type": "string", "format": "date-time" }, "error": { "type": "object", "nullable": true, "properties": { "message": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "message" ] }, "event_type": { "type": "string" }, "finished": { "type": "boolean" }, "name": { "type": "string" }, "output": { "type": "string" }, "start": { "type": "string", "format": "date-time" }, "type": { "type": "string", "enum": [ "waitForEvent" ] } }, "required": [ "name", "start", "end", "finished", "type", "error" ], "type": "object" } ] } }, "success": { "type": "boolean", "nullable": true }, "trigger": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "unknown", "api", "binding", "event", "cron" ] } }, "required": [ "source" ] }, "versionId": { "type": "string", "format": "uuid" } }, "required": [ "params", "trigger", "versionId", "queued", "start", "end", "step_count", "steps", "success", "error", "status", "output", "rollback" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Instance not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.instances", "x-fern-sdk-method-name": "get" } }, "/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/events/{event_type}": { "post": { "operationId": "wor-send-event-workflow-instance", "summary": "Send event to instance", "description": "Sends an event to a running workflow instance to trigger state transitions.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "instance_id", "in": "path", "description": "Instance identifier. User-created instances match `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$` (max 100 characters); cron-triggered instances can use a longer, system-generated id derived from the cron expression.", "required": true, "schema": { "type": "string", "maxLength": 271, "minLength": 1 } }, { "name": "event_type", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Send an event to an instance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "instanceId": { "type": "string" }, "timestamp": { "description": "Accepts ISO 8601 with no timezone offsets and in UTC.", "type": "string", "format": "date-time" } }, "required": [ "instanceId", "timestamp" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Workflow not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.instances.events", "x-fern-sdk-method-name": "send" } }, "/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/status": { "patch": { "operationId": "wor-change-status-workflow-instance", "summary": "Change status of instance", "description": "Changes the execution status of a workflow instance (e.g., pause, resume, terminate).", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "instance_id", "in": "path", "description": "Instance identifier. User-created instances match `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$` (max 100 characters); cron-triggered instances can use a longer, system-generated id derived from the cron expression.", "required": true, "schema": { "type": "string", "maxLength": 271, "minLength": 1 } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "properties": { "status": { "type": "string", "enum": [ "pause" ] } }, "required": [ "status" ], "type": "object" }, { "properties": { "status": { "type": "string", "enum": [ "resume" ] } }, "required": [ "status" ], "type": "object" }, { "properties": { "rollback": { "description": "Run rollback before terminating.", "type": "boolean" }, "status": { "type": "string", "enum": [ "terminate" ] } }, "required": [ "status" ], "type": "object" }, { "properties": { "from": { "description": "Step to restart from.", "type": "object", "properties": { "count": { "type": "integer", "exclusiveMinimum": true, "maximum": 9007199254740991, "minimum": 0 }, "name": { "type": "string", "maxLength": 256, "minLength": 1 }, "type": { "type": "string", "enum": [ "do", "sleep", "waitForEvent" ] } }, "required": [ "name" ] }, "status": { "type": "string", "enum": [ "restart" ] } }, "required": [ "status" ], "type": "object" } ] } } } }, "responses": { "200": { "description": "Change status of instance - it can be paused, resumed or terminated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued", "running", "paused", "errored", "terminated", "complete", "waitingForPause", "waiting", "rollingBack" ] }, "timestamp": { "description": "Accepts ISO 8601 with no timezone offsets and in UTC.", "type": "string", "format": "date-time" } }, "required": [ "status", "timestamp" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Instance not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "409": { "description": "Instance not in a restartable state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Scripts Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "workflows.instances.status", "x-fern-sdk-method-name": "edit", "x-forge-aliases": [ { "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.instances", "x-fern-sdk-method-name": "pause", "x-forge-params": { "from": { "hidden": true }, "rollback": { "hidden": true }, "status": { "default": "pause", "hidden": true } } }, { "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.instances", "x-fern-sdk-method-name": "resume", "x-forge-params": { "from": { "hidden": true }, "rollback": { "hidden": true }, "status": { "default": "resume", "hidden": true } } }, { "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.instances", "x-fern-sdk-method-name": "terminate", "x-forge-params": { "from": { "hidden": true }, "status": { "default": "terminate", "hidden": true } }, "x-forge-require-confirmation": "This operation terminates the running Workflow instance." }, { "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.instances", "x-fern-sdk-method-name": "restart", "x-forge-params": { "rollback": { "hidden": true }, "status": { "default": "restart", "hidden": true } } } ] } }, "/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/step": { "get": { "operationId": "wor-get-workflow-instance-step", "summary": "Get full step output from instance", "description": "Retrieves the full, untruncated output for a specific step on a workflow instance. Returns a flat status-shaped JSON body with step `status` ('running' | 'waiting' | 'complete' | 'errored'), `error` (nullable), and `output` (the step value, or null while running/waiting/errored). When the step returned a ReadableStream from step.do, the response is served as 'application/octet-stream' with the raw bytes as the body instead of JSON. A `status='running'` response with non-null `error` indicates the step is currently retrying after a prior attempt failed.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "instance_id", "in": "path", "description": "Instance identifier. User-created instances match `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$` (max 100 characters); cron-triggered instances can use a longer, system-generated id derived from the cron expression.", "required": true, "schema": { "type": "string", "maxLength": 271, "minLength": 1 } }, { "name": "name", "in": "query", "description": "Exact step name from the instance logs response, including the generated counter suffix.", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "type", "in": "query", "description": "Step type to disambiguate step.do and waitForEvent entries that share the same name.", "required": true, "schema": { "type": "string", "enum": [ "step", "waitForEvent" ] } }, { "name": "attempt", "in": "query", "description": "Specific attempt number to retrieve output or error for.", "schema": { "type": "integer", "exclusiveMinimum": true, "maximum": 9007199254740991, "minimum": 0 } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get the full output from a specific instance step.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "error": { "description": "Error details when status='errored'; null otherwise.", "type": "object", "nullable": true, "properties": { "message": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "message" ] }, "event_type": { "description": "The event type the step is waiting on, as supplied to step.waitForEvent. Only present when type='waitForEvent'.", "type": "string" }, "output": { "description": "Contains the full step output or waitForEvent payload without truncation. Uses '[REDACTED]' for sensitive outputs. Contains a value when status='complete'. May contain a ReadableStream when step.do returns one; the response serves stream outputs as application/octet-stream rather than JSON.", "type": "object" }, "status": { "type": "string", "enum": [ "queued", "running", "paused", "errored", "terminated", "complete", "waitingForPause", "waiting", "rollingBack" ] } }, "required": [ "status", "error" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } }, "application/octet-stream": { "schema": { "description": "Raw bytes of the ReadableStream returned from step.do.", "type": "string", "format": "binary" } } } }, "400": { "description": "Bad Request (e.g. 'attempt' parameter supplied with type='waitForEvent').", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Step not found on this instance, or requested attempt is out of range.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "429": { "description": "Step output requests are rate limited.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "500": { "description": "Step completed but its stored output is corrupt or missing (server-side data-integrity failure).", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.instances.step", "x-fern-sdk-method-name": "get" } }, "/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/subscribe": { "get": { "operationId": "wor-subscribe-workflow-instance-events", "summary": "Subscribe to workflow instance events", "description": "Opens a WebSocket that streams workflow instance events.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "instance_id", "in": "path", "description": "Instance identifier. User-created instances match `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$` (max 100 characters); cron-triggered instances can use a longer, system-generated id derived from the cron expression.", "required": true, "schema": { "type": "string", "maxLength": 271, "minLength": 1 } }, { "name": "cursor", "in": "query", "description": "Last event ID already received.", "schema": { "type": "integer" } }, { "name": "filter", "in": "query", "description": "Workflow event types to include. Send multiple event types by repeating the filter query parameter.", "schema": { "type": "array", "items": { "enum": [ "workflow_queued", "workflow_started", "workflow_running", "workflow_paused", "workflow_waiting_for_pause", "workflow_waiting", "workflow_completed", "workflow_errored", "workflow_terminated", "step_started", "step_completed", "step_errored", "attempt_started", "attempt_completed", "attempt_errored", "sleep_started", "sleep_completed", "wait_started", "wait_completed", "wait_timed_out", "rollback_started", "rollback_step_started", "rollback_step_completed", "rollback_step_errored", "rollback_attempt_started", "rollback_attempt_completed", "rollback_attempt_errored", "rollback_completed", "rollback_errored" ], "type": "string" } } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "101": { "description": "WebSocket subscription established." }, "400": { "description": "Invalid subscription options.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Instance not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.instances", "x-fern-sdk-method-name": "subscribe" } }, "/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/subscribe/token": { "get": { "operationId": "wor-create-workflow-instance-subscription-token", "summary": "Create a workflow instance event subscription token", "description": "Creates a short-lived token for connecting to the workflow instance event WebSocket.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "instance_id", "in": "path", "description": "Instance identifier. User-created instances match `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$` (max 100 characters); cron-triggered instances can use a longer, system-generated id derived from the cron expression.", "required": true, "schema": { "type": "string", "maxLength": 271, "minLength": 1 } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A five-minute subscription token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "token": { "type": "string" }, "websocketUrl": { "type": "string" } }, "required": [ "token", "websocketUrl" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Workflow event subscriptions require control plane v2.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Instance not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "workflows.instances", "x-fern-sdk-method-name": "subscribe-token" } }, "/accounts/{account_id}/workflows/{workflow_name}/versions": { "get": { "operationId": "wor-list-workflow-versions", "summary": "List deployed Workflow versions", "description": "Lists all deployed versions of a workflow.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "per_page", "in": "query", "schema": { "type": "number", "default": 50, "maximum": 100, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "number", "default": 1, "minimum": 1 } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List deployed workflow versions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "array", "items": { "properties": { "class_name": { "type": "string" }, "concurrency": { "type": "object", "properties": { "limit": { "description": "Maximum number of instances of this workflow that can run concurrently. Additional instances are queued and started as running instances complete. Must not exceed the account concurrency limit.", "type": "integer", "maximum": 9007199254740991, "minimum": 1 } } }, "created_on": { "type": "string", "format": "date-time" }, "default_retention": { "type": "object", "properties": { "error_retention": { "description": "Default error retention in milliseconds.", "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "success_retention": { "description": "Default success retention in milliseconds.", "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } } }, "has_dag": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "language": { "description": "The programming language of the workflow implementation.", "type": "string", "enum": [ "javascript", "python" ] }, "limits": { "type": "object", "properties": { "steps": { "type": "integer", "maximum": 9007199254740991, "minimum": 1 } } }, "modified_on": { "type": "string", "format": "date-time" }, "workflow_id": { "type": "string", "format": "uuid" } }, "required": [ "created_on", "modified_on", "id", "workflow_id", "class_name", "has_dag", "language" ], "type": "object" } }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.versions", "x-fern-sdk-method-name": "list" } }, "/accounts/{account_id}/workflows/{workflow_name}/versions/{version_id}": { "get": { "operationId": "wor-describe-workflow-versions", "summary": "Get Workflow version details", "description": "Retrieves details for a specific deployed workflow version.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get specific version details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "class_name": { "type": "string" }, "concurrency": { "type": "object", "properties": { "limit": { "description": "Maximum number of instances of this workflow that can run concurrently. Additional instances are queued and started as running instances complete. Must not exceed the account concurrency limit.", "type": "integer", "maximum": 9007199254740991, "minimum": 1 } } }, "created_on": { "type": "string", "format": "date-time" }, "default_retention": { "type": "object", "properties": { "error_retention": { "description": "Default error retention in milliseconds.", "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 }, "success_retention": { "description": "Default success retention in milliseconds.", "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } } }, "has_dag": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "language": { "description": "The programming language of the workflow implementation.", "type": "string", "enum": [ "javascript", "python" ] }, "limits": { "type": "object", "properties": { "steps": { "type": "integer", "maximum": 9007199254740991, "minimum": 1 } } }, "modified_on": { "type": "string", "format": "date-time" }, "workflow_id": { "type": "string", "format": "uuid" } }, "required": [ "created_on", "modified_on", "id", "workflow_id", "class_name", "has_dag", "language" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } }, "404": { "description": "Version not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.versions", "x-fern-sdk-method-name": "get" } }, "/accounts/{account_id}/workflows/{workflow_name}/versions/{version_id}/dag": { "get": { "operationId": "wor-describe-workflow-versions-dag", "summary": "Get Workflow version dag", "description": "Retrieves the directed acyclic graph (DAG) representation of a workflow version.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get the parsed DAG for a specific workflow version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "class_name": { "type": "string" }, "created_on": { "type": "string", "format": "date-time" }, "dag": { "type": "object", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "modified_on": { "type": "string", "format": "date-time" }, "workflow_id": { "type": "string", "format": "uuid" } }, "required": [ "created_on", "modified_on", "id", "workflow_id", "class_name", "dag" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "404": { "description": "Version not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "workflows.versions", "x-fern-sdk-method-name": "dag" } }, "/accounts/{account_id}/workflows/{workflow_name}/versions/{version_id}/graph": { "get": { "operationId": "wor-describe-workflow-versions-graph", "summary": "Get Workflow version graph", "description": "Retrieves the graph visualization of a workflow version.", "parameters": [ { "name": "workflow_name", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_][a-zA-Z0-9-_]*$" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get the parsed graph for a specific workflow version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "properties": { "class_name": { "type": "string" }, "created_on": { "type": "string", "format": "date-time" }, "graph": { "description": "Versioned workflow graph payload.", "type": "object", "nullable": true, "properties": { "version": { "type": "number" }, "workflow": { "description": "A parsed workflow entrypoint with its step graph.", "type": "object", "properties": { "class_name": { "type": "string" }, "functions": { "type": "object", "additionalProperties": { "properties": { "name": { "type": "string" }, "nodes": { "description": "Child nodes (recursive).", "type": "array", "items": { "type": "object" } }, "type": { "type": "string", "enum": [ "function_def" ] } }, "required": [ "type", "name", "nodes" ], "type": "object" } }, "nodes": { "type": "array", "items": { "oneOf": [ { "properties": { "duration": { "description": "Duration as milliseconds (number) or human-readable string.", "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "name": { "type": "string" }, "resolves": { "type": "number" }, "starts": { "type": "number" }, "type": { "type": "string", "enum": [ "step_sleep" ] } }, "required": [ "type", "name", "duration" ], "type": "object" }, { "properties": { "config": { "description": "Configuration for a step (retries and timeout).", "type": "object", "properties": { "retries": { "description": "Retry policy for a step.", "type": "object", "properties": { "backoff": { "description": "Backoff strategy for step retries.", "type": "string", "enum": [ "constant", "linear", "exponential" ] }, "delay": { "description": "Duration as milliseconds (number) or human-readable string.", "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "limit": { "type": "number" } }, "required": [ "limit", "delay", "backoff" ] }, "timeout": { "description": "Duration as milliseconds (number) or human-readable string.", "anyOf": [ { "type": "number" }, { "type": "string" } ] } }, "required": [ "retries", "timeout" ] }, "name": { "type": "string" }, "nodes": { "description": "Child nodes (recursive).", "type": "array", "items": { "type": "object" } }, "resolves": { "type": "number" }, "starts": { "type": "number" }, "type": { "type": "string", "enum": [ "step_do" ] } }, "required": [ "type", "name", "config", "nodes" ], "type": "object" }, { "properties": { "name": { "type": "string" }, "options": { "description": "Options for a waitForEvent step.", "type": "object", "nullable": true, "properties": { "event_type": { "type": "string" }, "timeout": { "description": "Duration as milliseconds (number) or human-readable string.", "anyOf": [ { "type": "number" }, { "type": "string" } ] } }, "required": [ "event_type", "timeout" ] }, "payload": { "description": "Shape descriptor for JSON payloads.", "anyOf": [ { "properties": { "type": { "type": "string", "enum": [ "unknown" ] } }, "required": [ "type" ], "type": "object" }, { "properties": { "fields": { "description": "Nested JsonShape fields (recursive structure).", "type": "object", "additionalProperties": { "type": "object" } }, "type": { "type": "string", "enum": [ "object" ] } }, "required": [ "type", "fields" ], "type": "object" } ] }, "resolves": { "type": "number" }, "starts": { "type": "number" }, "type": { "type": "string", "enum": [ "step_wait_for_event" ] } }, "required": [ "type", "name", "options" ], "type": "object" }, { "properties": { "name": { "type": "string" }, "resolves": { "type": "number" }, "starts": { "type": "number" }, "timestamp": { "type": "string" }, "type": { "type": "string", "enum": [ "step_sleep_until" ] } }, "required": [ "type", "name", "timestamp" ], "type": "object" }, { "properties": { "nodes": { "description": "Child nodes (recursive).", "type": "array", "items": { "type": "object" } }, "type": { "type": "string", "enum": [ "loop" ] } }, "required": [ "type", "nodes" ], "type": "object" }, { "properties": { "kind": { "description": "Parallel execution strategy.", "type": "string", "enum": [ "all", "any", "all_settled", "race" ] }, "nodes": { "description": "Child nodes (recursive).", "type": "array", "items": { "type": "object" } }, "type": { "type": "string", "enum": [ "parallel" ] } }, "required": [ "type", "kind", "nodes" ], "type": "object" }, { "properties": { "catch_block": { "type": "object", "nullable": true, "properties": { "nodes": { "description": "Child nodes (recursive).", "type": "array", "items": { "type": "object" } }, "type": { "type": "string", "enum": [ "block" ] } }, "required": [ "type", "nodes" ] }, "finally_block": { "type": "object", "nullable": true, "properties": { "nodes": { "description": "Child nodes (recursive).", "type": "array", "items": { "type": "object" } }, "type": { "type": "string", "enum": [ "block" ] } }, "required": [ "type", "nodes" ] }, "try_block": { "type": "object", "nullable": true, "properties": { "nodes": { "description": "Child nodes (recursive).", "type": "array", "items": { "type": "object" } }, "type": { "type": "string", "enum": [ "block" ] } }, "required": [ "type", "nodes" ] }, "type": { "type": "string", "enum": [ "try" ] } }, "required": [ "type", "try_block", "catch_block", "finally_block" ], "type": "object" }, { "properties": { "nodes": { "description": "Child nodes (recursive).", "type": "array", "items": { "type": "object" } }, "type": { "type": "string", "enum": [ "block" ] } }, "required": [ "type", "nodes" ], "type": "object" }, { "properties": { "branches": { "type": "array", "items": { "properties": { "condition": { "type": "string", "nullable": true }, "nodes": { "description": "Child nodes (recursive).", "type": "array", "items": { "type": "object" } } }, "required": [ "condition", "nodes" ], "type": "object" } }, "type": { "type": "string", "enum": [ "if" ] } }, "required": [ "type", "branches" ], "type": "object" }, { "properties": { "branches": { "type": "array", "items": { "properties": { "condition": { "type": "string", "nullable": true }, "nodes": { "description": "Child nodes (recursive).", "type": "array", "items": { "type": "object" } } }, "required": [ "condition", "nodes" ], "type": "object" } }, "discriminant": { "type": "string" }, "type": { "type": "string", "enum": [ "switch" ] } }, "required": [ "type", "discriminant", "branches" ], "type": "object" }, { "properties": { "class_name": { "type": "string" }, "functions": { "type": "object", "additionalProperties": { "properties": { "name": { "type": "string" }, "nodes": { "description": "Child nodes (recursive).", "type": "array", "items": { "type": "object" } }, "type": { "type": "string", "enum": [ "function_def" ] } }, "required": [ "type", "name", "nodes" ], "type": "object" } }, "nodes": { "description": "Child nodes (recursive).", "type": "array", "items": { "type": "object" } }, "payload": { "description": "Shape descriptor for JSON payloads.", "anyOf": [ { "properties": { "type": { "type": "string", "enum": [ "unknown" ] } }, "required": [ "type" ], "type": "object" }, { "properties": { "fields": { "description": "Nested JsonShape fields (recursive structure).", "type": "object", "additionalProperties": { "type": "object" } }, "type": { "type": "string", "enum": [ "object" ] } }, "required": [ "type", "fields" ], "type": "object" } ] }, "type": { "type": "string", "enum": [ "start" ] } }, "required": [ "type", "class_name", "functions", "nodes" ], "type": "object" }, { "properties": { "name": { "type": "string" }, "resolves": { "type": "number" }, "starts": { "type": "number" }, "type": { "type": "string", "enum": [ "function_call" ] } }, "required": [ "type", "name" ], "type": "object" }, { "properties": { "name": { "type": "string" }, "nodes": { "description": "Child nodes (recursive).", "type": "array", "items": { "type": "object" } }, "type": { "type": "string", "enum": [ "function_def" ] } }, "required": [ "type", "name", "nodes" ], "type": "object" }, { "properties": { "kind": { "description": "Break or return from a loop.", "type": "string", "enum": [ "break", "return" ] }, "type": { "type": "string", "enum": [ "break" ] } }, "required": [ "type", "kind" ], "type": "object" } ] } }, "payload": { "description": "Shape descriptor for JSON payloads.", "anyOf": [ { "properties": { "type": { "type": "string", "enum": [ "unknown" ] } }, "required": [ "type" ], "type": "object" }, { "properties": { "fields": { "description": "Nested JsonShape fields (recursive structure).", "type": "object", "additionalProperties": { "type": "object" } }, "type": { "type": "string", "enum": [ "object" ] } }, "required": [ "type", "fields" ], "type": "object" } ] } }, "required": [ "class_name", "functions", "nodes" ] } }, "required": [ "version", "workflow" ] }, "id": { "type": "string", "format": "uuid" }, "modified_on": { "type": "string", "format": "date-time" }, "workflow_id": { "type": "string", "format": "uuid" } }, "required": [ "created_on", "modified_on", "id", "workflow_id", "class_name", "graph" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "per_page", "count", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "result", "messages" ] } } } }, "404": { "description": "Version not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "messages", "errors", "result" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Workflows" ], "x-api-token-group": [ "Workers Tail Read", "Workers Scripts Write", "Workers Scripts Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.workers.write", "com.cloudflare.api.workers.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workflows.versions", "x-fern-sdk-method-name": "graph" } }, "/accounts/{account_id}/zerotrust/connectivity_settings": { "get": { "operationId": "zero-trust-accounts-get-connectivity-settings", "summary": "Get Zero Trust Connectivity Settings", "description": "Gets the Zero Trust Connectivity Settings for the given account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } } ], "responses": { "200": { "description": "Get Zero Trust Connectivity Settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_zero_trust_connectivity_settings_response" } } } }, "4XX": { "description": "Get Zero Trust Connectivity Settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Zero Trust Connectivity Settings" ], "x-api-token-group": [ "Zero Trust Report", "Zero Trust Read", "Zero Trust Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.connectivity-settings", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "zero-trust-accounts-patch-connectivity-settings", "summary": "Updates the Zero Trust Connectivity Settings", "description": "Updates the Zero Trust Connectivity Settings for the given account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "icmp_proxy_enabled": { "$ref": "#/components/schemas/tunnel_icmp_proxy_enabled" }, "offramp_warp_enabled": { "$ref": "#/components/schemas/tunnel_offramp_warp_enabled" } } } } } }, "responses": { "200": { "description": "Update Zero Trust Connectivity Settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_zero_trust_connectivity_settings_response" } } } }, "4XX": { "description": "Update Zero Trust Connectivity Settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Zero Trust Connectivity Settings" ], "x-api-token-group": [ "Zero Trust Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.connectivity-settings", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/zerotrust/routes/hostname": { "get": { "operationId": "zero-trust-networks-route-hostname-list", "summary": "List hostname routes", "description": "Lists and filters hostname routes in an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "id", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_hostname_route_id" } }, { "name": "hostname", "in": "query", "description": "If set, only list hostname routes that contain a substring of the given value, the filter is case-insensitive.", "schema": { "$ref": "#/components/schemas/tunnel_hostname" } }, { "name": "tunnel_id", "in": "query", "description": "If set, only list hostname routes that point to a specific tunnel.", "schema": { "$ref": "#/components/schemas/tunnel_tunnel_id-3" } }, { "name": "comment", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_hostname_query_comment" } }, { "name": "existed_at", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_existed_at" } }, { "name": "is_deleted", "in": "query", "schema": { "description": "If `true`, only return deleted hostname routes. If `false`, exclude deleted hostname routes.", "type": "boolean", "example": true, "default": false } }, { "name": "per_page", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_per_page" } }, { "name": "page", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_page_number" } } ], "responses": { "200": { "description": "List hostname routes response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_hostname_route_response_collection" } } } }, "4XX": { "description": "List hostname routes failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_hostname_route_response_collection" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Zero Trust Hostname Route" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare One Networks Read", "Cloudflare Tunnel Write", "Cloudflare Tunnel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.routes.hostname", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "zero-trust-networks-route-hostname-create", "summary": "Create hostname route", "description": "Create a hostname route.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/tunnel_hostname_comment" }, "hostname": { "$ref": "#/components/schemas/tunnel_hostname" }, "tunnel_id": { "$ref": "#/components/schemas/tunnel_tunnel_id-3" } } } } } }, "responses": { "200": { "description": "Create hostname route response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_hostname_route_response_single" } } } }, "4XX": { "description": "Create hostname route response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_hostname_route_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Zero Trust Hostname Route" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare Tunnel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.routes.hostname", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/zerotrust/routes/hostname/{hostname_route_id}": { "delete": { "operationId": "zero-trust-networks-route-hostname-delete", "summary": "Delete hostname route", "description": "Delete a hostname route.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "hostname_route_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_hostname_route_id" } } ], "responses": { "200": { "description": "Delete hostname route response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_hostname_route_response_single" } } } }, "4XX": { "description": "Delete hostname route response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_hostname_route_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Zero Trust Hostname Route" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare Tunnel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.routes.hostname", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation permanently deletes a hostname route." }, "get": { "operationId": "zero-trust-networks-route-hostname-get", "summary": "Get hostname route", "description": "Get a hostname route.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "hostname_route_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_hostname_route_id" } } ], "responses": { "200": { "description": "Get hostname route response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_hostname_route_response_single" } } } }, "4XX": { "description": "Get hostname route response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_hostname_route_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Zero Trust Hostname Route" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare One Networks Read", "Cloudflare Tunnel Write", "Cloudflare Tunnel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.routes.hostname", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "zero-trust-networks-route-hostname-update", "summary": "Update hostname route", "description": "Updates a hostname route.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "hostname_route_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_hostname_route_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/tunnel_hostname_comment" }, "hostname": { "$ref": "#/components/schemas/tunnel_hostname" }, "tunnel_id": { "$ref": "#/components/schemas/tunnel_tunnel_id-3" } } } } } }, "responses": { "200": { "description": "Update hostname route response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_hostname_route_response_single" } } } }, "4XX": { "description": "Update hostname route response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_hostname_route_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Zero Trust Hostname Route" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare Tunnel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.routes.hostname", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/zerotrust/subnets": { "get": { "operationId": "zero-trust-networks-subnets-list", "summary": "List Subnets", "description": "Lists and filters subnets in an account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "name", "in": "query", "description": "If set, only list subnets with the given name", "schema": { "$ref": "#/components/schemas/tunnel_subnet_query_name" } }, { "name": "comment", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_subnet_query_comment" } }, { "name": "network", "in": "query", "schema": { "description": "If set, only list the subnet whose network exactly matches the given CIDR.", "allOf": [ { "$ref": "#/components/schemas/tunnel_ip_network_encoded" } ] } }, { "name": "existed_at", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_existed_at" } }, { "name": "address_family", "in": "query", "description": "If set, only include subnets in the given address family - `v4` or `v6`", "schema": { "$ref": "#/components/schemas/tunnel_address_family" } }, { "name": "is_default_network", "in": "query", "schema": { "description": "If `true`, only include default subnets. If `false`, exclude default subnets subnets. If not set, all subnets will be included.", "type": "boolean" } }, { "name": "is_deleted", "in": "query", "schema": { "description": "If `true`, only include deleted subnets. If `false`, exclude deleted subnets. If not set, all subnets will be included.", "type": "boolean" } }, { "name": "sort_order", "in": "query", "schema": { "description": "Sort order of the results. `asc` means oldest to newest, `desc` means newest to oldest. If not set, they will not be in any particular order.", "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "subnet_types", "in": "query", "schema": { "description": "If set, the types of subnets to include, separated by comma.", "type": "string", "example": "cloudflare_source,warp", "enum": [ "cloudflare_source", "initial_resolved_ip", "warp" ] } }, { "name": "per_page", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_per_page" } }, { "name": "page", "in": "query", "schema": { "$ref": "#/components/schemas/tunnel_page_number" } } ], "responses": { "200": { "description": "List subnets response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_subnet_response_collection" } } } }, "4XX": { "description": "List subnets response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_subnet_response_collection" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Zero Trust Subnets" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare One Networks Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.subnets", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/accounts/{account_id}/zerotrust/subnets/cloudflare_source/{address_family}": { "patch": { "operationId": "zero-trust-networks-subnet-update-cloudflare-source", "summary": "Update Cloudflare Source Subnet", "description": "Updates the Cloudflare Source subnet of the given address family", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "address_family", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_address_family" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/tunnel_subnet_comment" }, "name": { "$ref": "#/components/schemas/tunnel_subnet_name" }, "network": { "$ref": "#/components/schemas/tunnel_subnet_ip_network" } } } } } }, "responses": { "200": { "description": "Update subnet response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_subnet_response_single" } } } }, "4XX": { "description": "Update subnet response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_subnet_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Zero Trust Subnets" ], "x-api-token-group": [ "Cloudflare One Networks Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.subnets.cloudflare-source", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/zerotrust/subnets/initial_resolved_ip/{address_family}": { "get": { "operationId": "zero-trust-networks-subnet-get-initial-resolved-ip", "summary": "Get Initial Resolved IP Subnet", "description": "Returns the account's default Initial Resolved IP Subnet for the given address family.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "address_family", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_address_family" } } ], "responses": { "200": { "description": "Get Initial Resolved IP Subnet response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_subnet_response_single" } } } }, "4XX": { "description": "Get Initial Resolved IP Subnet response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_subnet_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Zero Trust Subnets" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare One Networks Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.subnets.initial-resolved-ip", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "zero-trust-networks-subnet-update-initial-resolved-ip", "summary": "Update Initial Resolved IP Subnet", "description": "Updates the CIDR for the account's default Initial Resolved IP Subnet of the given address\nfamily. The new CIDR must not conflict with existing private routes in the account.\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "address_family", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_address_family" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/tunnel_subnet_comment" }, "name": { "$ref": "#/components/schemas/tunnel_subnet_name" }, "network": { "$ref": "#/components/schemas/tunnel_subnet_ip_network" } } } } } }, "responses": { "200": { "description": "Update Initial Resolved IP Subnet response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_subnet_response_single" } } } }, "4XX": { "description": "Update Initial Resolved IP Subnet response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_subnet_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Zero Trust Subnets" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.subnets.initial-resolved-ip", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/zerotrust/subnets/warp": { "post": { "operationId": "zero-trust-networks-subnet-create-warp", "summary": "Create WARP IP subnet", "description": "Create a WARP IP assignment subnet. Currently, only IPv4 subnets can be created.\n\n**Network constraints:**\n- The network must be within one of the following private IP ranges:\n - `10.0.0.0/8` (RFC 1918)\n - `172.16.0.0/12` (RFC 1918)\n - `192.168.0.0/16` (RFC 1918)\n - `100.64.0.0/10` (RFC 6598 - CGNAT)\n- The subnet must have a prefix length of `/24` or larger (e.g., `/16`, `/20`, `/24` are valid; `/25`, `/28` are not)\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/tunnel_subnet_comment" }, "is_default_network": { "$ref": "#/components/schemas/tunnel_subnet_is_default_network" }, "name": { "$ref": "#/components/schemas/tunnel_subnet_name" }, "network": { "$ref": "#/components/schemas/tunnel_subnet_ip_network" } }, "required": [ "name", "network" ] } } } }, "responses": { "200": { "description": "Create subnet response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_subnet_response_single" } } } }, "4XX": { "description": "Create subnet response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_subnet_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Zero Trust Subnets" ], "x-api-token-group": [ "Cloudflare One Networks Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.subnets.warp", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/zerotrust/subnets/warp/{subnet_id}": { "delete": { "operationId": "zero-trust-networks-subnet-delete-warp", "summary": "Delete WARP IP subnet", "description": "Delete a WARP IP assignment subnet. This operation is idempotent - deleting an already-deleted or non-existent subnet will return success with a null result.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "subnet_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_subnet_id" } } ], "responses": { "200": { "description": "Delete subnet response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_subnet_response_single_nullable" } } } }, "4XX": { "description": "Delete subnet response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_subnet_response_single_nullable" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Zero Trust Subnets" ], "x-api-token-group": [ "Cloudflare One Networks Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.subnets.warp", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation permanently deletes a WARP IP subnet." }, "get": { "operationId": "zero-trust-networks-subnet-get-warp", "summary": "Get WARP IP subnet", "description": "Get a WARP IP assignment subnet.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "subnet_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_subnet_id" } } ], "responses": { "200": { "description": "Get subnet response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_subnet_response_single" } } } }, "4XX": { "description": "Get subnet response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_subnet_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Zero Trust Subnets" ], "x-api-token-group": [ "Cloudflare One Networks Write", "Cloudflare One Networks Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.subnets.warp", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "zero-trust-networks-subnet-update-warp", "summary": "Update WARP IP subnet", "description": "Updates a WARP IP assignment subnet.\n\n**Update constraints:**\n- The `network` field cannot be modified for WARP subnets. Only `name`, `comment`, and `is_default_network` can be updated.\n- IPv6 subnets cannot be updated\n", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_account_id" } }, { "name": "subnet_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tunnel_subnet_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/tunnel_subnet_comment" }, "is_default_network": { "$ref": "#/components/schemas/tunnel_subnet_is_default_network" }, "name": { "$ref": "#/components/schemas/tunnel_subnet_name" }, "network": { "$ref": "#/components/schemas/tunnel_subnet_ip_network" } } } } } }, "responses": { "200": { "description": "Update subnet response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tunnel_subnet_response_single" } } } }, "4XX": { "description": "Update subnet response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tunnel_subnet_response_single" }, { "$ref": "#/components/schemas/tunnel_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Zero Trust Subnets" ], "x-api-token-group": [ "Cloudflare One Networks Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "network.subnets.warp", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/accounts/{account_id}/zt_risk_scoring/behaviors": { "get": { "operationId": "dlp-risk-score-behaviors-get", "summary": "Get all behaviors and associated configuration", "description": "Retrieves configured risk score behaviors that define how user actions affect their overall risk score.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Risk scoring behaviors.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dlp_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dlp_Behaviors" } }, "type": "object" } ] } } } }, "4XX": { "description": "Failed to get risk scoring behaviors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dlp_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zero Trust Risk Scoring" ], "x-api-token-group": [ "Zero Trust Read", "Zero Trust Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.risk-scoring.behaviours", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "dlp-risk-score-behaviors-put", "summary": "Update configuration for risk behaviors", "description": "Updates risk score behavior configurations, defining weights and thresholds for risk calculation.", "parameters": [ { "name": "account_id", "in": "path", "description": "Account ID.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Behaviors.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dlp_UpdateBehaviors" } } } }, "responses": { "200": { "description": "Dataset created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dlp_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dlp_UpdateBehaviors" } }, "type": "object" } ] } } } }, "4XX": { "description": "Dataset creation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dlp_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zero Trust Risk Scoring" ], "x-api-token-group": [ "Zero Trust Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.risk-scoring.behaviours", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/zt_risk_scoring/integrations": { "get": { "operationId": "dlp-zt-risk-score-integration-list", "summary": "List all risk score integrations for the account.", "description": "Lists all configured Zero Trust risk score integrations for the account.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dlp_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dlp_RiskScoreIntegrationArray" } }, "type": "object" } ] } } } }, "4XX": { "description": "List failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dlp_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zero Trust Risk Scoring Integrations" ], "x-api-token-group": [ "Zero Trust Read", "Zero Trust Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.risk-scoring.integrations", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "dlp-zt-risk-score-integration-create", "summary": "Create new risk score integration.", "description": "Creates a new Zero Trust risk score integration, connecting external risk signals to Cloudflare's risk scoring system.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dlp_CreateIntegrationBody" } } } }, "responses": { "200": { "description": "Create response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dlp_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dlp_RiskScoreIntegration" } }, "type": "object" } ] } } } }, "4XX": { "description": "Create failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dlp_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zero Trust Risk Scoring Integrations" ], "x-api-token-group": [ "Zero Trust Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.risk-scoring.integrations", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/accounts/{account_id}/zt_risk_scoring/integrations/reference_id/{reference_id}": { "get": { "operationId": "dlp-zt-risk-score-integration-get-by-reference-id", "summary": "Get risk score integration by reference id.", "description": "Retrieves a Zero Trust risk score integration using its external reference ID.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "reference_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dlp_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dlp_RiskScoreIntegration" } }, "type": "object" } ] } } } }, "4XX": { "description": "Get failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dlp_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zero Trust Risk Scoring Integrations" ], "x-api-token-group": [ "Zero Trust Read", "Zero Trust Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.risk-scoring.integrations.references", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/zt_risk_scoring/integrations/{integration_id}": { "delete": { "operationId": "dlp-zt-risk-score-integration-delete", "summary": "Delete a risk score integration.", "description": "Removes a Zero Trust risk score integration, disconnecting the external risk signal source.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "integration_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Delete response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dlp_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dlp_Empty" } }, "type": "object" } ] } } } }, "4XX": { "description": "Delete failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dlp_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zero Trust Risk Scoring Integrations" ], "x-api-token-group": [ "Zero Trust Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.risk-scoring.integrations", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "dlp-zt-risk-score-integration-get", "summary": "Get risk score integration by id.", "description": "Gets a Zero Trust risk score integration by ID.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "integration_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dlp_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dlp_RiskScoreIntegration" } }, "type": "object" } ] } } } }, "4XX": { "description": "Get failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dlp_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zero Trust Risk Scoring Integrations" ], "x-api-token-group": [ "Zero Trust Read", "Zero Trust Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.risk-scoring.integrations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "dlp-zt-risk-score-integration-update", "summary": "Update a risk score integration.", "description": "Overwrite the reference_id, tenant_url, and active values with the ones provided.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "integration_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dlp_UpdateIntegrationBody" } } } }, "responses": { "200": { "description": "Update response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dlp_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dlp_RiskScoreIntegration" } }, "type": "object" } ] } } } }, "4XX": { "description": "Update failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dlp_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zero Trust Risk Scoring Integrations" ], "x-api-token-group": [ "Zero Trust Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.risk-scoring.integrations", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/accounts/{account_id}/zt_risk_scoring/summary": { "get": { "operationId": "dlp-risk-score-summary-get", "summary": "Get risk score info for all users in the account", "description": "Gets an aggregate summary of risk scores across the account, including distribution and trends.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Risk score for all users in the account.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dlp_api-response-collection" }, { "properties": { "result": { "$ref": "#/components/schemas/dlp_RiskSummary" } }, "type": "object" } ] } } } }, "4XX": { "description": "Failed to get risk scores.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dlp_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zero Trust Risk Scoring" ], "x-api-token-group": [ "Zero Trust: PII Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.risk-scoring.summary", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/zt_risk_scoring/{user_id}": { "get": { "operationId": "dlp-risk-score-summary-get-for-user", "summary": "Get risk event/score information for a specific user", "description": "Retrieves the detailed risk score breakdown for a specific user, including contributing factors.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Risk events.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dlp_api-response-collection" }, { "properties": { "result": { "$ref": "#/components/schemas/dlp_RiskEvents" } }, "type": "object" } ] } } } }, "4XX": { "description": "Failed to get risk events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dlp_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zero Trust Risk Scoring" ], "x-api-token-group": [ "Zero Trust: PII Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.risk-scoring", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/accounts/{account_id}/zt_risk_scoring/{user_id}/reset": { "post": { "operationId": "dlp-risk-score-reset-post", "summary": "Clear the risk score for a particular user", "description": "Resets risk scores for specified users, clearing their accumulated risk history.", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Dataset created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dlp_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dlp_Empty" } }, "type": "object" } ] } } } }, "4XX": { "description": "Dataset creation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dlp_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zero Trust Risk Scoring" ], "x-api-token-group": [ "Zero Trust Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.risk-scoring", "x-fern-sdk-method-name": "reset", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation wipes risk-scoring history." } }, "/api/v4/health": { "get": { "operationId": "monolithHealthCheck", "summary": "API health check", "description": "Returns the operational health status of the Cloudflare API monolith.\nThis is an internal infrastructure health check endpoint and is not\nintended for customer use. It is permanently exempt from SDK and public\ndocs generation (see x-fern-ignore). Ref: APIOPS-12957.\n", "responses": { "200": { "description": "The API is healthy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/monolith_health_response" } } } } }, "security": [], "tags": [ "Health" ], "x-fern-availability": "generally-available", "x-fern-ignore": true, "x-fern-sdk-group-name": "health", "x-fern-sdk-method-name": "check" } }, "/billing/address-validation": { "post": { "operationId": "billing-validate-address", "summary": "Validate Billing Address", "description": "Validates a billing address and returns validated address suggestions. Authentication is not enforced to support pre-signup address validation flows, so credentials are accepted but not required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_address_validation_request" } } } }, "responses": { "200": { "description": "Validate Billing Address response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_address_validation_response_single" } } } }, "4XX": { "description": "Validate Billing Address response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] }, {} ], "tags": [ "Account Billing" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "billing.addresses", "x-fern-sdk-method-name": "validate" } }, "/billing/rate_plans/{public_key}": { "get": { "operationId": "billing-get-rate-plan", "summary": "Get Rate Plan by Public Key", "description": "Gets a rate plan's details by its public key (e.g., 'teams_free', 'cf_pro_20_20'). This is a public catalog endpoint, so authentication is not enforced and credentials are accepted but not required.", "parameters": [ { "name": "public_key", "in": "path", "description": "The public key identifier for the rate plan.", "required": true, "schema": { "type": "string", "example": "teams_free" } } ], "responses": { "200": { "description": "Get Rate Plan response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_rate_plan_simple_response" } } } }, "4XX": { "description": "Get Rate Plan response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] }, {} ], "tags": [ "Rate Plans" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-sdk-group-name": "billing.rate-plans", "x-fern-sdk-method-name": "get" } }, "/certificates": { "get": { "operationId": "origin-ca-list-certificates", "summary": "List Certificates", "description": "List all existing Origin CA certificates for a given zone. You can use an Origin CA Key as your User Service Key or an API token when calling this endpoint ([see above](#requests)).", "parameters": [ { "name": "zone_id", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of records per page.", "type": "number", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "limit", "in": "query", "schema": { "description": "Limit to the number of records returned.", "type": "integer", "example": 10 } }, { "name": "offset", "in": "query", "schema": { "description": "Offset the results.", "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "List Certificates response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_collection-2" } } } }, "4XX": { "description": "List Certificates response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_collection-2" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Origin CA" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-ca-certificates", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "origin-ca-create-certificate", "summary": "Create Certificate", "description": "Create an Origin CA certificate. You can use an Origin CA Key as your User Service Key or an API token when calling this endpoint ([see above](#requests)).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csr": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_csr" }, "hostnames": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostnames" }, "request_type": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_request_type" }, "requested_validity": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_requested_validity" } }, "required": [ "hostnames", "request_type", "csr" ] } } } }, "responses": { "200": { "description": "Create Certificate response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single-2" } } } }, "4XX": { "description": "Create Certificate response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single-2" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Origin CA" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-ca-certificates", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/certificates/{certificate_id}": { "delete": { "operationId": "origin-ca-revoke-certificate", "summary": "Revoke Certificate", "description": "Revoke an existing Origin CA certificate by its serial number. You can use an Origin CA Key as your User Service Key or an API token when calling this endpoint ([see above](#requests)).", "parameters": [ { "name": "certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Revoke Certificate response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_revoke_response" } } } }, "4XX": { "description": "Revoke Certificate response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_revoke_response" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Origin CA" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-ca-certificates", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "origin-ca-get-certificate", "summary": "Get Certificate", "description": "Get an existing Origin CA certificate by its serial number. You can use an Origin CA Key as your User Service Key or an API token when calling this endpoint ([see above](#requests)).", "parameters": [ { "name": "certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Get Certificate response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single-2" } } } }, "4XX": { "description": "Get Certificate response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single-2" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "user_service_key": [] } ], "tags": [ "Origin CA" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-ca-certificates", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/internal/submit": { "post": { "operationId": "postInternalSubmit", "summary": "Internal route for testing URL submissions", "description": "Internal route for testing URL submissions.", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "internal.submit", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/ips": { "get": { "operationId": "cloudflare-ips-cloudflare-ip-details", "summary": "Cloudflare/JD Cloud IP Details", "description": "Get IPs used on the Cloudflare/JD Cloud network, see https://www.cloudflare.com/ips for Cloudflare IPs or https://developers.cloudflare.com/china-network/reference/infrastructure/ for JD Cloud IPs.", "parameters": [ { "name": "networks", "in": "query", "description": "Specified as `jdcloud` to list IPs used by JD Cloud data centers.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cloudflare IP Details response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/public-ip_api-response-single" }, { "properties": { "result": { "oneOf": [ { "$ref": "#/components/schemas/public-ip_ips" }, { "$ref": "#/components/schemas/public-ip_ips_jdcloud" } ] } } } ] } } } }, "4XX": { "description": "Cloudflare IP Details response failure", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/public-ip_api-response-single" }, { "properties": { "result": { "oneOf": [ { "$ref": "#/components/schemas/public-ip_ips" }, { "$ref": "#/components/schemas/public-ip_ips_jdcloud" } ] } } } ] }, { "$ref": "#/components/schemas/public-ip_api-response-common-failure" } ] } } } } }, "security": [ {} ], "tags": [ "Cloudflare IPs" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ips", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/live": { "get": { "operationId": "getLive", "summary": "Run liveness checks", "description": "Return a success message after running liveness checks", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "live", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/memberships": { "get": { "operationId": "user'-s-account-memberships-list-memberships", "summary": "List Memberships", "description": "List memberships of accounts the user can access.", "parameters": [ { "name": "account.name", "in": "query", "schema": { "$ref": "#/components/schemas/iam_properties-name" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of memberships per page.", "type": "number", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "order", "in": "query", "schema": { "description": "Field to order memberships by.", "type": "string", "example": "status", "enum": [ "id", "account.name", "status" ] } }, { "name": "direction", "in": "query", "schema": { "description": "Direction to order memberships.", "type": "string", "example": "desc", "enum": [ "asc", "desc" ] } }, { "name": "name", "in": "query", "schema": { "$ref": "#/components/schemas/iam_properties-name" } }, { "name": "status", "in": "query", "schema": { "description": "Status of this membership.", "type": "string", "example": "accepted", "enum": [ "accepted", "pending", "rejected" ] } } ], "responses": { "200": { "description": "List Memberships response", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/iam_collection_membership_response" }, { "$ref": "#/components/schemas/iam_collection_membership_response_with_policies" } ] } } } }, "4XX": { "description": "List Memberships response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "User's Account Memberships" ], "x-api-token-group": [ "Memberships Write", "Memberships Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.memberships", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/memberships/{membership_id}": { "delete": { "operationId": "user'-s-account-memberships-delete-membership", "summary": "Delete Membership", "description": "Remove the associated member from an account.", "parameters": [ { "name": "membership_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_membership_components-schemas-identifier" } } ], "responses": { "200": { "description": "Delete Membership response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "properties": { "id": { "$ref": "#/components/schemas/iam_membership_components-schemas-identifier" } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Delete Membership response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "User's Account Memberships" ], "x-api-token-group": [ "Memberships Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.memberships", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "Are you sure? This action cannot be undone." }, "get": { "operationId": "user'-s-account-memberships-membership-details", "summary": "Membership Details", "description": "Get a specific membership.", "parameters": [ { "name": "membership_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_membership_components-schemas-identifier" } } ], "responses": { "200": { "description": "Membership Details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_single_membership_response_with_policies" } } } }, "4XX": { "description": "Membership Details response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "User's Account Memberships" ], "x-api-token-group": [ "Memberships Write", "Memberships Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.memberships", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "user'-s-account-memberships-update-membership", "summary": "Update Membership", "description": "Accept or reject this account invitation.", "parameters": [ { "name": "membership_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_membership_components-schemas-identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "status": { "description": "Whether to accept or reject this account invitation.", "example": "accepted", "enum": [ "accepted", "rejected" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Update Membership response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_single_membership_response_with_policies" } } } }, "4XX": { "description": "Update Membership response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "User's Account Memberships" ], "x-api-token-group": [ "Memberships Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.memberships", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/oauth/scopes": { "get": { "operationId": "oauth-scopes-list", "summary": "List OAuth Scopes", "description": "List all available OAuth scopes. This endpoint requires authentication but has no authorization role requirements.", "responses": { "200": { "description": "List OAuth Scopes response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_collection_oauth_scopes_response" } } } }, "4XX": { "description": "List OAuth Scopes response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "OAuth Clients" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "iam.oauth-scopes", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/organizations": { "get": { "operationId": "Organization_listOrganizations", "summary": "List organizations the user has access to", "description": "Retrieve a list of organizations a particular user has access to. (Currently in Public Beta - see https://developers.cloudflare.com/fundamentals/organizations/)", "parameters": [ { "$ref": "#/components/parameters/organizations-api_OrganizationListFiltersId" }, { "$ref": "#/components/parameters/organizations-api_OrganizationListFiltersName" }, { "$ref": "#/components/parameters/organizations-api_OrganizationListFiltersNameStartsWith" }, { "$ref": "#/components/parameters/organizations-api_OrganizationListFiltersNameEndsWith" }, { "$ref": "#/components/parameters/organizations-api_OrganizationListFiltersNameContains" }, { "$ref": "#/components/parameters/organizations-api_OrganizationListFiltersContainingAccount" }, { "$ref": "#/components/parameters/organizations-api_OrganizationListFiltersContainingUser" }, { "$ref": "#/components/parameters/organizations-api_OrganizationListFiltersContainingOrganization" }, { "$ref": "#/components/parameters/organizations-api_OrganizationListFiltersParentId" }, { "$ref": "#/components/parameters/organizations-api_PageTokenParamsPageToken" }, { "$ref": "#/components/parameters/organizations-api_PageTokenParamsPageSize" } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_Organization" } }, "result_info": { "$ref": "#/components/schemas/organizations-api_PageTokenResultInfo" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result", "result_info" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Organizations" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "organization", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "Organizations_createUserOrganization", "summary": "Create organization", "description": "Create a new organization for a user. (Currently in Public Beta - see https://developers.cloudflare.com/fundamentals/organizations/)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_Organization" } } } }, "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "$ref": "#/components/schemas/organizations-api_Organization" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Organizations" ], "x-api-token-group": [ "User Details Write" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "organization", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/organizations/{organization_id}": { "delete": { "operationId": "Organizations_delete", "summary": "Delete organization.", "description": "Delete an organization. The organization MUST be empty before deleting.\nIt must not contain any sub-organizations, accounts, members or users. (Currently in Public Beta - see https://developers.cloudflare.com/fundamentals/organizations/)\n\n**Access Control:** Restricted to enterprise organizations.", "parameters": [ { "name": "organization_id", "in": "path", "description": "The ID of the organization to delete.", "required": true, "schema": { "$ref": "#/components/schemas/organizations-api_OrganizationID" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "$ref": "#/components/schemas/organizations-api_DeleteOrganizationResponse" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Organizations" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "organization", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "Are you sure? This action cannot be undone." }, "get": { "operationId": "Organizations_retrieve", "summary": "Get organization", "description": "Retrieve the details of a certain organization. (Currently in Public Beta - see https://developers.cloudflare.com/fundamentals/organizations/)", "parameters": [ { "name": "organization_id", "in": "path", "description": "The ID of the organization to retrieve.", "required": true, "schema": { "$ref": "#/components/schemas/organizations-api_OrganizationID" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "$ref": "#/components/schemas/organizations-api_Organization" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Organizations" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "organization", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "Organizations_modify", "summary": "Modify organization.", "description": "Modify organization. (Currently in Public Beta - see https://developers.cloudflare.com/fundamentals/organizations/)", "parameters": [ { "name": "organization_id", "in": "path", "description": "The ID of the organization to modify.", "required": true, "schema": { "$ref": "#/components/schemas/organizations-api_OrganizationID" } } ], "requestBody": { "description": "The new details of the organization. Only accepts updates\nto \"name\" currently.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_Organization" } } } }, "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "$ref": "#/components/schemas/organizations-api_Organization" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Organizations" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "organization", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/organizations/{organization_id}/accounts": { "get": { "operationId": "Organizations_getAccounts", "summary": "Get organization accounts", "description": "Retrieve a list of accounts that belong to a specific organization. (Currently in Public Beta - see https://developers.cloudflare.com/fundamentals/organizations/)", "parameters": [ { "name": "organization_id", "in": "path", "description": "The ID of the organization to retrieve a list of accounts for.", "required": true, "schema": { "$ref": "#/components/schemas/organizations-api_OrganizationID" } }, { "name": "account_pubname", "in": "query", "description": "(case-insensitive) Filter the list of accounts to where the account_pubname is equal to\na particular string.", "schema": { "type": "string" }, "deprecated": true, "explode": false }, { "name": "account_pubname.startsWith", "in": "query", "description": "(case-insensitive) Filter the list of accounts to where the account_pubname starts with\na particular string.", "schema": { "type": "string" }, "deprecated": true, "explode": false }, { "name": "account_pubname.endsWith", "in": "query", "description": "(case-insensitive) Filter the list of accounts to where the account_pubname ends with\na particular string.", "schema": { "type": "string" }, "deprecated": true, "explode": false }, { "name": "account_pubname.contains", "in": "query", "description": "(case-insensitive) Filter the list of accounts to where the account_pubname contains\na particular string.", "schema": { "type": "string" }, "deprecated": true, "explode": false }, { "name": "name", "in": "query", "description": "(case-insensitive) Filter the list of accounts to where the name is equal to a\nparticular string.", "schema": { "type": "string" }, "explode": false }, { "name": "name.startsWith", "in": "query", "description": "(case-insensitive) Filter the list of accounts to where the name starts with a\nparticular string.", "schema": { "type": "string" }, "explode": false }, { "name": "name.endsWith", "in": "query", "description": "(case-insensitive) Filter the list of accounts to where the name ends with a particular\nstring.", "schema": { "type": "string" }, "explode": false }, { "name": "name.contains", "in": "query", "description": "(case-insensitive) Filter the list of accounts to where the name contains a particular\nstring.", "schema": { "type": "string" }, "explode": false }, { "name": "order_by", "in": "query", "description": "Field to order results by. Currently supported values: `account_name`.\nWhen not specified, results are ordered by internal account ID.", "schema": { "type": "string", "enum": [ "account_name" ] }, "explode": false }, { "name": "direction", "in": "query", "description": "Sort direction for the order_by field. Valid values: `asc`, `desc`.\nDefaults to `asc` when order_by is specified.", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "explode": false }, { "name": "include_tags", "in": "query", "description": "Include Account tags from the resource tag mirror. Omit this parameter to preserve the existing Account response shape.", "schema": { "type": "boolean" }, "explode": false }, { "name": "include_total", "in": "query", "description": "Whether to calculate and return the exact result_info.total_size for cursor\npagination. Defaults to true. When false, total_size is omitted. page_size and\ninclude_total may change between pages; next_page_token remains the authoritative\ncontinuation signal.\nLegacy page/per_page requests always calculate total_count.", "schema": { "type": "boolean", "default": true }, "explode": false }, { "$ref": "#/components/parameters/organizations-api_PageTokenParamsPageToken" }, { "$ref": "#/components/parameters/organizations-api_PageTokenParamsPageSize" } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_Account" } }, "result_info": { "$ref": "#/components/schemas/organizations-api_PageTokenResultInfo" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result", "result_info" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Organizations" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "organization.account", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/organizations/{organization_id}/billable/usage": { "get": { "operationId": "billable-usage-v2-get-organization-usage", "summary": "Get Organization Usage (Version 2, Alpha, Restricted)", "description": "Returns cost and usage data for all accounts within an organization,\naligned with the [FinOps FOCUS v1.3](https://focus.finops.org/focus-specification/v1-3/)\nCost and Usage dataset specification.\n\nEach record represents one billable metric for one account on one day.\nThis includes all metered usage, including usage that falls within\nfree-tier allowances and may result in zero cost. The response\nincludes usage for every account belonging to the specified\norganization.\n\n**Note:** Cost and pricing fields are not yet populated and\nwill be absent from responses until billing integration is complete.\n\nWhen `from` and `to` are omitted, defaults to the start of the current\nmonth through today. The maximum date range is 31 days.\n", "parameters": [ { "$ref": "#/components/parameters/billable-usage-api_organization_id" }, { "$ref": "#/components/parameters/billable-usage-api_v2_from" }, { "$ref": "#/components/parameters/billable-usage-api_v2_to" } ], "responses": { "200": { "description": "Organization usage data was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billable-usage-api_v2_usage_response" } } } }, "4XX": { "description": "Indicates the request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billable-usage-api_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Billable Usage V2" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "organizations.billing.usage", "x-fern-sdk-method-name": "get" } }, "/organizations/{organization_id}/logs/audit": { "get": { "operationId": "audit-logs-v2-get-organization-audit-logs", "summary": "Get organization audit logs (Version 2)", "description": "Gets a list of audit logs for an organization.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "description": "The unique id that identifies the organization.", "type": "string", "example": "a67e14daa5f8dceeb91fe5449ba496ef" } }, { "name": "action_result", "in": "query", "schema": { "description": "Filters by whether the action was successful or not.", "type": "array", "items": { "enum": [ "success", "failure" ], "type": "string" }, "example": "success" } }, { "name": "action_type", "in": "query", "schema": { "description": "Filters by the action type.", "type": "array", "items": { "enum": [ "create", "delete", "view", "update" ], "example": "create", "type": "string" } } }, { "name": "actor_context", "in": "query", "schema": { "description": "Filters by the actor context.\n- `api`: The action was performed through the API. The specific credential type was not recorded.\n- `api_key`: The action was authenticated with a Cloudflare Global API Key.\n- `api_token`: The action was authenticated with an API token.\n- `dash`: The action was performed through the Cloudflare dashboard.\n- `oauth`: The action was authenticated with an OAuth token.\n- `origin_ca_key`: The action was authenticated with an Origin CA key.\n", "type": "array", "items": { "enum": [ "api", "api_key", "api_token", "dash", "oauth", "origin_ca_key" ], "example": "api_key", "type": "string" } } }, { "name": "actor_email", "in": "query", "schema": { "description": "Filters by the actor's email address.", "type": "array", "items": { "example": "alice@example.com", "format": "email", "type": "string" } } }, { "name": "actor_id", "in": "query", "schema": { "description": "Filters by the actor's user ID.", "type": "array", "items": { "example": "1d20c3afe174f18b642710cec6298a9d", "type": "string" } } }, { "name": "actor_ip_address", "in": "query", "schema": { "description": "The IP address where the action was initiated.", "type": "array", "items": { "example": "17.168.228.63", "type": "string" } } }, { "name": "actor_token_id", "in": "query", "schema": { "description": "Filters by the API token ID when the actor context is an api_token or oauth.", "type": "array", "items": { "example": "144cdb2e39c55e203cf225d8d8208647", "type": "string" } } }, { "name": "actor_token_name", "in": "query", "schema": { "description": "Filters by the API token name when the actor context is an api_token or oauth.", "type": "array", "items": { "example": "Test Token", "type": "string" } } }, { "name": "actor_type", "in": "query", "schema": { "description": "Filters by the actor type.", "type": "array", "items": { "enum": [ "cloudflare_admin", "system", "user" ], "example": "user", "type": "string" } } }, { "name": "id", "in": "query", "schema": { "description": "Finds a specific log by its ID.", "type": "array", "items": { "example": "f174be97-19b1-40d6-954d-70cd5fbd52db", "type": "string" } } }, { "name": "raw_cf_ray_id", "in": "query", "schema": { "description": "Filters by the response CF Ray ID.", "type": "array", "items": { "example": "8e8dd2156ef28414", "type": "string" } } }, { "name": "raw_method", "in": "query", "schema": { "description": "The HTTP method for the API call.", "type": "array", "items": { "example": "GET", "type": "string" } } }, { "name": "raw_status_code", "in": "query", "schema": { "description": "The response status code that was returned.", "type": "array", "items": { "example": 200, "type": "integer" } } }, { "name": "raw_uri", "in": "query", "schema": { "description": "Filters by the request URI.", "type": "array", "items": { "type": "string" } } }, { "name": "resource_id", "in": "query", "schema": { "description": "Filters by the resource ID.", "type": "array", "items": { "type": "string" } } }, { "name": "resource_product", "in": "query", "schema": { "description": "Filters audit logs by the Cloudflare product associated with the changed resource.", "type": "array", "items": { "example": "Stream", "type": "string" } } }, { "name": "resource_type", "in": "query", "schema": { "description": "Filters audit logs based on the unique type of resource changed by the action.", "type": "array", "items": { "example": "Video", "type": "string" } } }, { "name": "resource_scope", "in": "query", "schema": { "description": "Filters by the resource scope, specifying whether the resource is associated with an organization.", "type": "array", "items": { "enum": [ "organizations" ], "example": "organizations", "type": "string" } } }, { "name": "action_result.not", "in": "query", "schema": { "description": "Filters out audit logs by whether the action was successful or not.", "type": "array", "items": { "enum": [ "success", "failure" ], "type": "string" }, "example": "success" } }, { "name": "action_type.not", "in": "query", "schema": { "description": "Filters out audit logs by the action type.", "type": "array", "items": { "enum": [ "create", "delete", "view", "update" ], "example": "create", "type": "string" } } }, { "name": "actor_context.not", "in": "query", "schema": { "description": "Filters out audit logs by the actor context.\n- `api`: The action was performed through the API. The specific credential type was not recorded.\n- `api_key`: The action was authenticated with a Cloudflare Global API Key.\n- `api_token`: The action was authenticated with an API token.\n- `dash`: The action was performed through the Cloudflare dashboard.\n- `oauth`: The action was authenticated with an OAuth token.\n- `origin_ca_key`: The action was authenticated with an Origin CA key.\n", "type": "array", "items": { "enum": [ "api", "api_key", "api_token", "dash", "oauth", "origin_ca_key" ], "example": "api_key", "type": "string" } } }, { "name": "actor_email.not", "in": "query", "schema": { "description": "Filters out audit logs by the actor's email address.", "type": "array", "items": { "example": "alice@example.com", "format": "email", "type": "string" } } }, { "name": "actor_id.not", "in": "query", "schema": { "description": "Filters out audit logs by the actor's user ID.", "type": "array", "items": { "example": "1d20c3afe174f18b642710cec6298a9d", "type": "string" } } }, { "name": "actor_ip_address.not", "in": "query", "schema": { "description": "Filters out audit logs IP address where the action was initiated.", "type": "array", "items": { "example": "17.168.228.63", "type": "string" } } }, { "name": "actor_token_id.not", "in": "query", "schema": { "description": "Filters out audit logs by the API token ID when the actor context is an api_token or oauth.", "type": "array", "items": { "example": "144cdb2e39c55e203cf225d8d8208647", "type": "string" } } }, { "name": "actor_token_name.not", "in": "query", "schema": { "description": "Filters out audit logs by the API token name when the actor context is an api_token or oauth.", "type": "array", "items": { "example": "Test Token", "type": "string" } } }, { "name": "actor_type.not", "in": "query", "schema": { "description": "Filters out audit logs by the actor type.", "type": "array", "items": { "enum": [ "cloudflare_admin", "system", "user" ], "example": "user", "type": "string" } } }, { "name": "id.not", "in": "query", "schema": { "description": "Filters out audit logs by their IDs.", "type": "array", "items": { "example": "f174be97-19b1-40d6-954d-70cd5fbd52db", "type": "string" } } }, { "name": "raw_cf_ray_id.not", "in": "query", "schema": { "description": "Filters out audit logs by the response CF Ray ID.", "type": "array", "items": { "example": "8e8dd2156ef28414", "type": "string" } } }, { "name": "raw_method.not", "in": "query", "schema": { "description": "Filters out audit logs by the HTTP method for the API call.", "type": "array", "items": { "example": "GET", "type": "string" } } }, { "name": "raw_status_code.not", "in": "query", "schema": { "description": "Filters out audit logs by the response status code that was returned.", "type": "array", "items": { "example": 200, "type": "integer" } } }, { "name": "raw_uri.not", "in": "query", "schema": { "description": "Filters out audit logs by the request URI.", "type": "array", "items": { "type": "string" } } }, { "name": "resource_id.not", "in": "query", "schema": { "description": "Filters out audit logs by the resource ID.", "type": "array", "items": { "type": "string" } } }, { "name": "resource_product.not", "in": "query", "schema": { "description": "Filters out audit logs by the Cloudflare product associated with the changed resource.", "type": "array", "items": { "example": "Stream", "type": "string" } } }, { "name": "resource_type.not", "in": "query", "schema": { "description": "Filters out audit logs based on the unique type of resource changed by the action.", "type": "array", "items": { "example": "Video", "type": "string" } } }, { "name": "resource_scope.not", "in": "query", "schema": { "description": "Filters out audit logs by the resource scope, specifying whether the resource is associated with an organization.", "type": "array", "items": { "enum": [ "organizations" ], "example": "organizations", "type": "string" } } }, { "name": "since", "in": "query", "description": "Limits the returned results to logs newer than the specified date. This can be a date string 2019-04-30 (interpreted in UTC) or an absolute timestamp that conforms to RFC3339.", "required": true, "schema": { "type": "string", "format": "date", "example": "2024-10-30" } }, { "name": "before", "in": "query", "description": "Limits the returned results to logs older than the specified date. This can be a date string 2019-04-30 (interpreted in UTC) or an absolute timestamp that conforms to RFC3339.", "required": true, "schema": { "type": "string", "format": "date", "example": "2024-10-31" } }, { "name": "direction", "in": "query", "schema": { "description": "Sets sorting order.", "type": "string", "example": "desc", "default": "desc", "enum": [ "desc", "asc" ] } }, { "name": "limit", "in": "query", "schema": { "description": "The number limits the objects to return. The cursor attribute may be used to iterate over the next batch of objects if there are more than the limit.", "type": "number", "example": 25, "default": 100, "maximum": 1000, "minimum": 1 } }, { "name": "cursor", "in": "query", "schema": { "description": "The cursor is an opaque token used to paginate through large sets of records. It indicates the position from which to continue when requesting the next set of records. A valid cursor value can be obtained from the cursor object in the result_info structure of a previous response.", "type": "string", "example": "Q1buH-__DQqqig7SVYXT-SsMOTGY2Z3Y80W-fGgva7yaDdmPKveucH5ddOcHsJRhNb-xUK8agZQqkJSMAENGO8NU6g==" } } ], "responses": { "200": { "description": "Get organization audit logs successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_audit-logs-v2-org-response-collection" } } } }, "4XX": { "description": "Get organization audit logs failed response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_api-response-common-failure-2" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Audit Logs" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "organizations.logs.audit", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/organizations/{organization_id}/logs/audit/{id}/history": { "get": { "operationId": "audit-logs-v2-get-organization-audit-log-history", "summary": "Get resource change history from an organization audit log entry (Version 2)", "description": "Returns the chronological change history for the resource identified by the given organization-scoped audit log entry.\n\nThe endpoint first locates the source audit log entry by `id` (using `action_time` to narrow the lookup window), derives identifying filters from that entry, and then returns matching audit logs within the `since`/`before` window.\n\nThe `result_info.history_status` field indicates the quality of the resource identification used:\n- `exact`: Resource was identified by the resource URI.\n- `approximate`: Resource was identified without the resource URI.\n- `unavailable`: The source audit log entry did not contain enough information to identify the resource; an empty result is returned.\n", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "description": "The unique ID that identifies the organization.", "type": "string", "example": "a67e14daa5f8dceeb91fe5449ba496ef" } }, { "name": "id", "in": "path", "required": true, "schema": { "description": "The ID of the audit log to fetch resource history for.", "type": "string", "format": "uuid", "example": "f174be97-19b1-40d6-954d-70cd5fbd52db" } }, { "name": "action_time", "in": "query", "description": "RFC3339 timestamp of the source audit log entry's action time. Used to narrow the source-entry lookup window. Provide the `action.time` value from the audit log identified by `id`.", "required": true, "schema": { "type": "string", "format": "date-time", "example": "2024-10-30T15:00:00Z" } }, { "name": "since", "in": "query", "description": "Limits the returned results to logs newer than the specified date. This can be a date string 2019-04-30 (interpreted in UTC) or an absolute timestamp that conforms to RFC3339.", "required": true, "schema": { "type": "string", "format": "date", "example": "2024-10-30" } }, { "name": "before", "in": "query", "description": "Limits the returned results to logs older than the specified date. This can be a date string 2019-04-30 (interpreted in UTC) or an absolute timestamp that conforms to RFC3339.", "required": true, "schema": { "type": "string", "format": "date", "example": "2024-10-31" } }, { "name": "direction", "in": "query", "schema": { "description": "Sets sorting order.", "type": "string", "example": "desc", "default": "desc", "enum": [ "desc", "asc" ] } }, { "name": "limit", "in": "query", "schema": { "description": "The number limits the objects to return. The cursor attribute may be used to iterate over the next batch of objects if there are more than the limit.", "type": "number", "example": 25, "default": 100, "maximum": 1000, "minimum": 1 } }, { "name": "cursor", "in": "query", "schema": { "description": "The cursor is an opaque token used to paginate through large sets of records. It indicates the position from which to continue when requesting the next set of records. A valid cursor value can be obtained from the cursor object in the result_info structure of a previous response.", "type": "string", "example": "Q1buH-__DQqqig7SVYXT-SsMOTGY2Z3Y80W-fGgva7yaDdmPKveucH5ddOcHsJRhNb-xUK8agZQqkJSMAENGO8NU6g==" } } ], "responses": { "200": { "description": "Get organization resource history successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_audit-logs-v2-org-history-response-collection" } } } }, "404": { "description": "Audit log entry not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_audit-logs-v2-history-not-found" } } } }, "4XX": { "description": "Get organization resource history failed response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_api-response-common-failure-2" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Audit Logs" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "organizations.logs.audit", "x-fern-sdk-method-name": "history", "x-forge-hidden": true } }, "/organizations/{organization_id}/members": { "get": { "operationId": "Members_list", "summary": "List organization members", "description": "List memberships for an Organization. (Currently in Public Beta - see https://developers.cloudflare.com/fundamentals/organizations/)", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/organizations-api_OrganizationID" } }, { "name": "status", "in": "query", "description": "Filter the list of memberships by membership status.", "schema": { "type": "array", "items": { "enum": [ "active", "pending", "rejected", "canceled" ], "type": "string" } } }, { "name": "user.email", "in": "query", "description": "Filter the list of memberships for a specific email.", "schema": { "type": "string" }, "explode": false }, { "name": "user.email.contains", "in": "query", "description": "Filter the list of memberships for a specific email that contains a substring.", "schema": { "type": "string" }, "explode": false }, { "name": "user.email.startsWith", "in": "query", "description": "Filter the list of memberships for a specific email that starts with a substring.", "schema": { "type": "string" }, "explode": false }, { "name": "user.email.endsWith", "in": "query", "description": "Filter the list of memberships for a specific email that ends with a substring.", "schema": { "type": "string" }, "explode": false }, { "$ref": "#/components/parameters/organizations-api_PageTokenParamsPageToken" }, { "$ref": "#/components/parameters/organizations-api_PageTokenParamsPageSize" } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_Member" } }, "result_info": { "$ref": "#/components/schemas/organizations-api_PageTokenResultInfo" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result", "result_info" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "OrganizationMembers" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "organization.member", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "Members_create", "summary": "Create organization member", "description": "Create a membership that grants access to a specific Organization. (Currently in Public Beta - see https://developers.cloudflare.com/fundamentals/organizations/)", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/organizations-api_OrganizationID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_CreateMemberRequest" } } } }, "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "$ref": "#/components/schemas/organizations-api_Member" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "OrganizationMembers" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "organization.member", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/organizations/{organization_id}/members/{member_id}": { "delete": { "operationId": "Members_delete", "summary": "Delete organization member", "description": "Delete a membership to a particular Organization. (Currently in Public Beta - see https://developers.cloudflare.com/fundamentals/organizations/)", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/organizations-api_OrganizationID" } }, { "name": "member_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/organizations-api_MemberID" } } ], "responses": { "204": { "description": "There is no content to send for this request, but the headers may be useful." }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "OrganizationMembers" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "organization.member", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "Are you sure? This action cannot be undone." }, "get": { "operationId": "Members_retrieve", "summary": "Get organization member", "description": "Retrieve a single membership from an Organization. (Currently in Public Beta - see https://developers.cloudflare.com/fundamentals/organizations/)", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/organizations-api_OrganizationID" } }, { "name": "member_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/organizations-api_MemberID" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "$ref": "#/components/schemas/organizations-api_Member" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "OrganizationMembers" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "organization.member", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/organizations/{organization_id}/members:batchCreate": { "post": { "operationId": "Members_batchCreate", "summary": "Batch create organization members", "description": "Batch create multiple memberships that grant access to a specific Organization.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/organizations-api_OrganizationID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_BatchCreateMembersRequest" } } } }, "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_Member" } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "OrganizationMembers" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "organization.member.batch", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/organizations/{organization_id}/profile": { "get": { "operationId": "Organizations_getProfile", "summary": "Get organization profile", "description": "Get an organizations profile if it exists. (Currently in Public Beta - see https://developers.cloudflare.com/fundamentals/organizations/)", "parameters": [ { "name": "organization_id", "in": "path", "description": "The ID of the organization to retrieve a profile for.", "required": true, "schema": { "$ref": "#/components/schemas/organizations-api_OrganizationID" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_ProfileResponse" } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Organizations" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "organization.profile", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "Organizations_modifyProfile", "summary": "Modify organization profile.", "description": "Modify organization profile. (Currently in Public Beta - see https://developers.cloudflare.com/fundamentals/organizations/)", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/organizations-api_OrganizationID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_Profile" } } } }, "responses": { "204": { "description": "There is no content to send for this request, but the headers may be useful." }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Organizations" ], "x-fern-availability": "beta", "x-fern-sdk-group-name": "organization.profile", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/organizations/{organization_id}/shares": { "get": { "operationId": "organization-shares-list", "summary": "List organization shares", "description": "Lists all organization shares.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/resource-sharing_organization_id" } }, { "$ref": "#/components/parameters/resource-sharing_status" }, { "$ref": "#/components/parameters/resource-sharing_kind" }, { "$ref": "#/components/parameters/resource-sharing_target_type" }, { "$ref": "#/components/parameters/resource-sharing_resource_types" }, { "$ref": "#/components/parameters/resource-sharing_order" }, { "$ref": "#/components/parameters/resource-sharing_direction" }, { "$ref": "#/components/parameters/resource-sharing_page" }, { "$ref": "#/components/parameters/resource-sharing_per_page" } ], "responses": { "200": { "description": "List organization shares response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-sharing_share_response_collection" } } } }, "4XX": { "description": "List organization shares response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/resource-sharing_api-response-common-failure" } ] } } } }, "5XX": { "description": "List organization shares response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/resource-sharing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Resource Sharing" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "organization.share", "x-fern-sdk-method-name": "list" } }, "/pages/assets/check-missing": { "post": { "operationId": "pages-assets-check-missing", "summary": "Check missing assets", "description": "Check which of the provided file hashes are missing from the Pages\nasset store. Returns a list of missing hashes that need to be uploaded.\nUsed as part of the Pages Direct Upload workflow.\n\nAuthenticate with the JWT obtained from the upload-token endpoint:\nGET /accounts/{account_id}/pages/projects/{project_name}/upload-token\n", "requestBody": { "required": true, "content": { "application/json": { "example": { "hashes": [ "a948904f2f0f479b8f936b8a0c5d9882", "b026324c6904b2a9cb4b88d6d61c81d1" ] }, "schema": { "$ref": "#/components/schemas/pages_pages_assets_check_missing_request" } } } }, "responses": { "200": { "description": "Check missing response.", "content": { "application/json": { "example": { "result": [ "b026324c6904b2a9cb4b88d6d61c81d1" ], "success": true }, "schema": { "$ref": "#/components/schemas/pages_pages_assets_check_missing_response" } } } }, "4XX": { "description": "Check missing failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pages_api-response-common-failure" } } } } }, "security": [ { "pages_upload_token": [] } ], "tags": [ "Pages Assets" ], "x-forge-hidden": true } }, "/pages/assets/upload": { "post": { "operationId": "pages-assets-upload", "summary": "Upload asset", "description": "Upload one or more files to the Pages asset store. Each file is\nidentified by its content hash and is uploaded using the same JSON shape\nas the Cloudflare KV bulk write API. Used as part of the Pages Direct\nUpload workflow.\n\nAuthenticate with the JWT obtained from the upload-token endpoint:\nGET /accounts/{account_id}/pages/projects/{project_name}/upload-token\n", "requestBody": { "required": true, "content": { "application/json": { "example": [ { "base64": true, "key": "b026324c6904b2a9cb4b88d6d61c81d1", "metadata": { "contentType": "text/plain" }, "value": "SGVsbG8sIFdvcmxkIQ==" } ], "schema": { "$ref": "#/components/schemas/pages_pages_assets_upload_request" } } } }, "responses": { "200": { "description": "Upload asset response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pages_api-response-common" } } } }, "4XX": { "description": "Upload asset failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pages_api-response-common-failure" } } } } }, "security": [ { "pages_upload_token": [] } ], "tags": [ "Pages Assets" ], "x-forge-hidden": true } }, "/pages/assets/upsert-hashes": { "post": { "operationId": "pages-assets-upsert-hashes", "summary": "Upsert asset hashes", "description": "Register the provided file hashes as recently uploaded to the Pages\nasset store. Used as part of the Pages Direct Upload workflow so future\ndeployments can avoid re-uploading files that are already present.\n\nAuthenticate with the JWT obtained from the upload-token endpoint:\nGET /accounts/{account_id}/pages/projects/{project_name}/upload-token\n", "requestBody": { "required": true, "content": { "application/json": { "example": { "hashes": [ "a948904f2f0f479b8f936b8a0c5d9882", "b026324c6904b2a9cb4b88d6d61c81d1" ] }, "schema": { "$ref": "#/components/schemas/pages_pages_assets_upsert_hashes_request" } } } }, "responses": { "200": { "description": "Upsert hashes response.", "content": { "application/json": { "example": { "success": true }, "schema": { "$ref": "#/components/schemas/pages_api-response-common" } } } }, "4XX": { "description": "Upsert hashes failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pages_api-response-common-failure" } } } } }, "security": [ { "pages_upload_token": [] } ], "tags": [ "Pages Assets" ], "x-forge-hidden": true } }, "/radar/agent_readiness/summary/{dimension}": { "get": { "operationId": "radar-get-agent-readiness-summary", "summary": "Get agent readiness summary", "description": "Returns a summary of AI agent readiness scores across scanned domains, grouped by the specified dimension. Data is sourced from weekly bulk scans. All values are raw domain counts.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the agent readiness data dimension by which to group the results.", "required": true, "schema": { "description": "Specifies the agent readiness data dimension by which to group the results.", "type": "string", "enum": [ "CHECK" ] } }, { "name": "date", "in": "query", "description": "Filters results by the specified date.", "schema": { "description": "Filters results by the specified date.", "type": "string", "format": "date", "example": "2024-09-19" } }, { "name": "domainCategory", "in": "query", "description": "Filters results by domain category.", "schema": { "description": "Filters results by domain category.", "type": "array", "items": { "maxLength": 100, "type": "string" }, "example": "News & Media" } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "date": { "description": "Date of the returned scan (YYYY-MM-DD). May differ from the requested date if no scan exists for that exact date.", "type": "string", "example": "2026-03-24T00:00:00Z" }, "domainCategories": { "description": "Available domain sub-categories with their scan counts. Use as filter options for the domainCategory parameter.", "type": "array", "items": { "properties": { "name": { "description": "Sub-category name.", "type": "string", "example": "News & Media" }, "value": { "description": "Number of successfully scanned domains in this sub-category.", "type": "integer" } }, "required": [ "name", "value" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "successfulDomains": { "description": "Domains successfully scanned (excludes errors).", "type": "integer" }, "totalDomains": { "description": "Total domains attempted in the scan.", "type": "integer" }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "date", "totalDomains", "successfulDomains", "normalization", "lastUpdated", "units", "domainCategories" ] }, "summary_0": { "type": "object", "example": { "markdownNegotiation": "45000", "robotsTxt": "280000" }, "additionalProperties": { "description": "Raw domain count as a numeric string.", "example": "280000", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Agent Readiness" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.agent-readiness", "x-fern-sdk-method-name": "summary", "x-forge-hidden": true } }, "/radar/ai/bots/summary/user_agent": { "get": { "operationId": "radar-get-ai-bots-summary-by-user-agent", "summary": "Get AI user agents summary", "description": "Retrieves the distribution of traffic by AI user agent.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "Amazonbot": "10.274394", "Bytespider": "8.381743", "facebookexternalhit": "63.40249" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AI Bots" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.ai.bots.summary", "x-fern-sdk-method-name": "user-agent", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AI Bots Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/ai/subresources/bots/methods/summary_v2/) instead." } }, "/radar/ai/bots/summary/{dimension}": { "get": { "operationId": "radar-get-ai-bots-summary", "summary": "Get AI bots HTTP requests distribution by dimension", "description": "Retrieves an aggregated summary of AI bots HTTP requests grouped by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "USER_AGENT", "CRAWL_PURPOSE", "INDUSTRY", "VERTICAL", "CONTENT_TYPE", "RESPONSE_STATUS", "RESPONSE_STATUS_CATEGORY" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "crawlPurpose", "in": "query", "description": "Filters results by bot crawl purpose.", "schema": { "description": "Filters results by bot crawl purpose.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "userAgent", "in": "query", "description": "Filters results by user agent.", "schema": { "description": "Filters results by user agent.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "vertical", "in": "query", "description": "Filters results by vertical.", "schema": { "description": "Filters results by vertical.", "type": "array", "items": { "maxLength": 2000, "type": "string" } } }, { "name": "industry", "in": "query", "description": "Filters results by industry.", "schema": { "description": "Filters results by industry.", "type": "array", "items": { "maxLength": 2000, "type": "string" } } }, { "name": "contentType", "in": "query", "description": "Filters results by content type category. When set, results can only be further filtered by location, continent, or Autonomous System.", "schema": { "description": "Filters results by content type category. When set, results can only be further filtered by location, continent, or Autonomous System.", "type": "array", "items": { "enum": [ "HTML", "IMAGES", "JSON", "JAVASCRIPT", "CSS", "PLAIN_TEXT", "FONTS", "XML", "YAML", "VIDEO", "AUDIO", "MARKDOWN", "DOCUMENTS", "BINARY", "SERIALIZATION", "OTHER" ], "type": "string" } } }, { "name": "responseStatus", "in": "query", "description": "Filters results by HTTP response status code (e.g. 200, 403, 404). Only [IANA-registered codes](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) are accepted.", "schema": { "description": "Filters results by HTTP response status code (e.g. 200, 403, 404). Only [IANA-registered codes](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) are accepted.", "type": "array", "items": { "pattern": "^\\d{3}$", "type": "string" } } }, { "name": "responseStatusCategory", "in": "query", "description": "Filters results by HTTP response status code category.", "schema": { "description": "Filters results by HTTP response status code category.", "type": "array", "items": { "enum": [ "INFORMATIONAL", "SUCCESS", "REDIRECTION", "CLIENT_ERROR", "SERVER_ERROR" ], "type": "string" } } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "Amazonbot": "10.274394", "Bytespider": "8.381743", "facebookexternalhit": "63.40249" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AI Bots" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ai.timeseries-groups", "x-fern-sdk-method-name": "summary", "x-forge-hidden": true } }, "/radar/ai/bots/timeseries": { "get": { "operationId": "radar-get-ai-bots-timeseries", "summary": "Get AI bots HTTP requests time series", "description": "Retrieves AI bots HTTP request volume over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "crawlPurpose", "in": "query", "description": "Filters results by bot crawl purpose.", "schema": { "description": "Filters results by bot crawl purpose.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "userAgent", "in": "query", "description": "Filters results by user agent.", "schema": { "description": "Filters results by user agent.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "industry", "in": "query", "description": "Filters results by industry.", "schema": { "description": "Filters results by industry.", "type": "array", "items": { "maxLength": 2000, "type": "string" } } }, { "name": "vertical", "in": "query", "description": "Filters results by vertical.", "schema": { "description": "Filters results by vertical.", "type": "array", "items": { "maxLength": 2000, "type": "string" } } }, { "name": "contentType", "in": "query", "description": "Filters results by content type category. When set, results can only be further filtered by location, continent, or Autonomous System.", "schema": { "description": "Filters results by content type category. When set, results can only be further filtered by location, continent, or Autonomous System.", "type": "array", "items": { "enum": [ "HTML", "IMAGES", "JSON", "JAVASCRIPT", "CSS", "PLAIN_TEXT", "FONTS", "XML", "YAML", "VIDEO", "AUDIO", "MARKDOWN", "DOCUMENTS", "BINARY", "SERIALIZATION", "OTHER" ], "type": "string" } } }, { "name": "responseStatus", "in": "query", "description": "Filters results by HTTP response status code (e.g. 200, 403, 404). Only [IANA-registered codes](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) are accepted.", "schema": { "description": "Filters results by HTTP response status code (e.g. 200, 403, 404). Only [IANA-registered codes](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) are accepted.", "type": "array", "items": { "pattern": "^\\d{3}$", "type": "string" } } }, { "name": "responseStatusCategory", "in": "query", "description": "Filters results by HTTP response status code category.", "schema": { "description": "Filters results by HTTP response status code category.", "type": "array", "items": { "enum": [ "INFORMATIONAL", "SUCCESS", "REDIRECTION", "CLIENT_ERROR", "SERVER_ERROR" ], "type": "string" } } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "additionalProperties": { "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } }, "values": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "timestamps", "values" ], "type": "object" }, "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] } }, "required": [ "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AI Bots" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ai.bots", "x-fern-sdk-method-name": "timeseries", "x-forge-hidden": true } }, "/radar/ai/bots/timeseries_groups/user_agent": { "get": { "operationId": "radar-get-ai-bots-timeseries-group-by-user-agent", "summary": "Get AI user agents time series", "description": "Retrieves the distribution of traffic by AI user agent over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "facebookexternalhit": [ "0.862022" ], "timestamps": [ "2024-07-30T03:00:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AI Bots" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.ai.timeseries-groups", "x-fern-sdk-method-name": "user-agent", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AI Bots Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/ai/subresources/bots/methods/timeseries_groups/) instead." } }, "/radar/ai/bots/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-ai-bots-timeseries-group", "summary": "Get time series distribution of AI bots HTTP requests by dimension.", "description": "Retrieves the distribution of HTTP requests from AI bots, grouped by the specified dimension over time.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "USER_AGENT", "CRAWL_PURPOSE", "INDUSTRY", "VERTICAL", "CONTENT_TYPE", "RESPONSE_STATUS", "RESPONSE_STATUS_CATEGORY" ] } }, { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "crawlPurpose", "in": "query", "description": "Filters results by bot crawl purpose.", "schema": { "description": "Filters results by bot crawl purpose.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "userAgent", "in": "query", "description": "Filters results by user agent.", "schema": { "description": "Filters results by user agent.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "industry", "in": "query", "description": "Filters results by industry.", "schema": { "description": "Filters results by industry.", "type": "array", "items": { "maxLength": 2000, "type": "string" } } }, { "name": "vertical", "in": "query", "description": "Filters results by vertical.", "schema": { "description": "Filters results by vertical.", "type": "array", "items": { "maxLength": 2000, "type": "string" } } }, { "name": "contentType", "in": "query", "description": "Filters results by content type category. When set, results can only be further filtered by location, continent, or Autonomous System.", "schema": { "description": "Filters results by content type category. When set, results can only be further filtered by location, continent, or Autonomous System.", "type": "array", "items": { "enum": [ "HTML", "IMAGES", "JSON", "JAVASCRIPT", "CSS", "PLAIN_TEXT", "FONTS", "XML", "YAML", "VIDEO", "AUDIO", "MARKDOWN", "DOCUMENTS", "BINARY", "SERIALIZATION", "OTHER" ], "type": "string" } } }, { "name": "responseStatus", "in": "query", "description": "Filters results by HTTP response status code (e.g. 200, 403, 404). Only [IANA-registered codes](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) are accepted.", "schema": { "description": "Filters results by HTTP response status code (e.g. 200, 403, 404). Only [IANA-registered codes](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) are accepted.", "type": "array", "items": { "pattern": "^\\d{3}$", "type": "string" } } }, { "name": "responseStatusCategory", "in": "query", "description": "Filters results by HTTP response status code category.", "schema": { "description": "Filters results by HTTP response status code category.", "type": "array", "items": { "enum": [ "INFORMATIONAL", "SUCCESS", "REDIRECTION", "CLIENT_ERROR", "SERVER_ERROR" ], "type": "string" } } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `PERCENTAGE_CHANGE` requires exactly one comparison series (e.g. a `control` date range).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `PERCENTAGE_CHANGE` requires exactly one comparison series (e.g. a `control` date range).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX", "PERCENTAGE_CHANGE" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "facebookexternalhit": [ "0.862022" ], "timestamps": [ "2024-07-30T03:00:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AI Bots" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ai.bots", "x-fern-sdk-method-name": "timeseries-groups", "x-forge-hidden": true } }, "/radar/ai/inference/summary/model": { "get": { "operationId": "radar-get-ai-inference-summary-by-model", "summary": "Get Workers AI models summary", "description": "Retrieves the distribution of the number of inferences by model.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "@cf/meta/llama-3-8b-instruct": "8.381743", "@cf/meta/m2m100-1.2b": "22.904", "@cf/stabilityai/stable-diffusion-xl-base-1.0": "10.274394" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AI Inference" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.ai.inference.summary", "x-fern-sdk-method-name": "model", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AI Inference Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/ai/subresources/inference/methods/summary_v2/) instead." } }, "/radar/ai/inference/summary/task": { "get": { "operationId": "radar-get-ai-inference-summary-by-task", "summary": "Get Workers AI tasks summary", "description": "Retrieves the distribution of the number of inferences by task.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "text generation": "10.274394", "text-to-image": "22.904" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AI Inference" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.ai.inference.summary", "x-fern-sdk-method-name": "task", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AI Inference Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/ai/subresources/inference/methods/summary_v2/) instead." } }, "/radar/ai/inference/summary/{dimension}": { "get": { "operationId": "radar-get-ai-inference-summary", "summary": "Get Workers AI inference distribution by dimension", "description": "Retrieves an aggregated summary of the number of inferences run on Workers AI, grouped by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "MODEL", "TASK" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "@cf/meta/llama-3-8b-instruct": "8.381743", "@cf/meta/m2m100-1.2b": "22.904", "@cf/stabilityai/stable-diffusion-xl-base-1.0": "10.274394" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AI Inference" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ai.inference", "x-fern-sdk-method-name": "summary-v2", "x-forge-hidden": true } }, "/radar/ai/inference/timeseries_groups/model": { "get": { "operationId": "radar-get-ai-inference-timeseries-group-by-model", "summary": "Get Workers AI models time series", "description": "Retrieves the distribution of the number of inferences by model over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "@cf/meta/m2m100-1.2b": [ "67.701863" ], "timestamps": [ "2024-07-30T03:00:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AI Inference" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.ai.inference.timeseries-groups.summary", "x-fern-sdk-method-name": "model", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AI Inference Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/ai/subresources/inference/methods/timeseries_groups_v2/) instead." } }, "/radar/ai/inference/timeseries_groups/task": { "get": { "operationId": "radar-get-ai-inference-timeseries-group-by-task", "summary": "Get Workers AI tasks time series", "description": "Retrieves the distribution of the number of inferences by task over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "text-to-image": [ "67.701863" ], "timestamps": [ "2024-07-30T03:00:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AI Inference" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.ai.inference.timeseries-groups.summary", "x-fern-sdk-method-name": "task", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AI Inference Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/ai/subresources/inference/methods/timeseries_groups_v2/) instead." } }, "/radar/ai/inference/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-ai-inference-timeseries-group", "summary": "Get time series distribution of Workers AI inference by dimension.", "description": "Retrieves the distribution of the number of inferences run on Workers AI, grouped by the specified dimension over time.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "MODEL", "TASK" ] } }, { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "@cf/meta/m2m100-1.2b": [ "67.701863" ], "text-to-image": [ "22.904" ], "timestamps": [ "2024-07-30T03:00:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AI Inference" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ai.inference", "x-fern-sdk-method-name": "timeseries-groups-v2", "x-forge-hidden": true } }, "/radar/ai/markdown_for_agents/summary": { "get": { "operationId": "radar-get-ai-markdown-for-agents-summary", "summary": "Get AI markdown for agents reduction ratio summary", "description": "Retrieves the overall median HTML-to-markdown reduction ratio for AI agent requests over the given date range.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "value": "10.6" }, "properties": { "value": { "description": "A numeric string that can include decimals and infinity values.", "type": "string", "example": "10.5", "pattern": "^-?(?:\\d+(?:\\.\\d+)?|inf)$" } }, "required": [ "value" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Markdown for Agents" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ai.markdown-for-agents", "x-fern-sdk-method-name": "summary", "x-forge-hidden": true } }, "/radar/ai/markdown_for_agents/timeseries": { "get": { "operationId": "radar-get-ai-markdown-for-agents-timeseries", "summary": "Get AI markdown for agents reduction ratio time series", "description": "Retrieves the median HTML-to-markdown reduction ratio over time for AI agent requests.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "additionalProperties": { "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } }, "values": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "timestamps", "values" ], "type": "object" }, "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] } }, "required": [ "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Markdown for Agents" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ai.markdown-for-agents", "x-fern-sdk-method-name": "timeseries", "x-forge-hidden": true } }, "/radar/annotations": { "get": { "operationId": "radar-get-annotations", "summary": "Get latest annotations", "description": "Retrieves the latest annotations.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Skips the specified number of objects before fetching the results.", "schema": { "description": "Skips the specified number of objects before fetching the results.", "type": "integer", "minimum": 0 } }, { "name": "dateRange", "in": "query", "description": "Filters results by a relative date range ending at the current time. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`), e.g. `7d`. Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `3dcontrol` covers days -10 to -7, `7dcontrol` covers days -14 to -7, `28dcontrol` covers days -56 to -28, and `10dcontrol` covers days -24 to -14). Mutually exclusive with `dateStart`/`dateEnd`.", "schema": { "description": "Filters results by a relative date range ending at the current time. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`), e.g. `7d`. Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `3dcontrol` covers days -10 to -7, `7dcontrol` covers days -14 to -7, `28dcontrol` covers days -56 to -28, and `10dcontrol` covers days -24 to -14). Mutually exclusive with `dateStart`/`dateEnd`.", "type": "string", "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "schema": { "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dataSource", "in": "query", "description": "Filters results by data source.", "schema": { "description": "Filters results by data source.", "type": "string", "example": "ALL", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] } }, { "name": "eventType", "in": "query", "description": "Filters results by event type. EVENT is a legacy alias for GENERAL.", "schema": { "description": "Filters results by event type. EVENT is a legacy alias for GENERAL.", "type": "string", "example": "OUTAGE", "enum": [ "EVENT", "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] } }, { "name": "outageType", "in": "query", "description": "Filters results by outage type.", "schema": { "description": "Filters results by outage type.", "type": "string", "enum": [ "NATIONWIDE", "REGIONAL", "NETWORK", "PLATFORM" ] } }, { "name": "outageCause", "in": "query", "description": "Filters results by outage cause.", "schema": { "description": "Filters results by outage cause.", "type": "string", "enum": [ "BLOCKING", "CABLE_CUT", "CYBERATTACK", "DNS", "FIRE", "GOVERNMENT_DIRECTED", "MAINTENANCE", "MECHANICAL", "MILITARY_ACTION", "MISCONFIGURATION", "NATURAL_DISASTER", "NETWORK_PROBLEM", "POWER_OUTAGE", "SOFTWARE", "TECHNICAL_PROBLEM", "UNKNOWN", "WEATHER" ] } }, { "name": "tags", "in": "query", "description": "Filters results by annotation tag. Matches annotations carrying at least one of the given tags.", "schema": { "description": "Filters results by annotation tag. Matches annotations carrying at least one of the given tags.", "type": "array", "items": { "description": "Dimension tag an annotation applies to.", "enum": [ "ADM1", "ADM2", "API_TRAFFIC", "ARC", "AS", "ASN", "ATTACKS", "AUTHOR", "BANDWIDTH", "BITRATE", "BOT", "BOT_CATEGORY", "BOT_CLASS", "BOT_KIND", "BOT_OPERATOR", "BROWSER", "BROWSER_FAMILY", "BYTES", "CA", "CACHE_HIT", "CA_OWNER", "CHECK_RESULT", "CLIENT_TYPE", "COMPROMISED", "CONTENT_TYPE", "CRAWL_PURPOSE", "CRAWL_REFER_RATIO", "DEVICE_TYPE", "DKIM", "DMARC", "DNS", "DNSSEC", "DNSSEC_AWARE", "DNSSEC_E2E", "DOMAIN_CATEGORY", "DURATION", "EDNS", "ENCRYPTED", "ENTRY_TYPE", "EXPIRATION_STATUS", "HAS_IPS", "HAS_MATCHING_ANSWER", "HAS_WILDCARDS", "HTTP_METHOD", "HTTP_PROTOCOL", "HTTP_VERSION", "INDUSTRY", "IP_VERSION", "JITTER", "KEY_AGREEMENT", "LATENCY", "LOCATION", "LOCATION_LATENCY", "LOG", "LOG_API", "LOG_OPERATOR", "MALICIOUS", "MANAGED_RULES", "MITIGATION_PRODUCT", "MODEL", "NAMESERVER_LATENCY", "ORIGIN", "ORIGIN_AS", "ORIGIN_LOCATION", "ORIGIN_TARGET_LOCATION_PAIR", "OS", "PERCENTILE", "POST_QUANTUM", "PREFIX", "PRODUCT", "PROTOCOL", "PROVIDER", "PUBLIC_KEY_ALGORITHM", "QUERY_TYPE", "REFERER", "REGION", "RESPONSE_CODE", "RESPONSE_STATUS", "RESPONSE_STATUS_CATEGORY", "RESPONSE_TTL", "SIGNATURE_ALGORITHM", "SPAM", "SPF", "SPOOF", "SUCCESS_RATE", "TARGET_LOCATION", "TASK", "THREAT_CATEGORY", "TLD", "TLD_DNS_MAGNITUDE", "TLS_VERSION", "UPDATE_TYPE", "USER_AGENT", "VALIDATION_LEVEL", "VECTOR", "VERTICAL" ], "type": "string" } } }, { "name": "query", "in": "query", "description": "Filters results by a free-text match on the annotation description, id, or linked entities (location, ASN, origin).", "schema": { "description": "Filters results by a free-text match on the annotation description, id, or linked entities (location, ASN, origin).", "type": "string", "example": "portugal", "maxLength": 100 } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify a single Autonomous System Number (ASN) as integer.", "schema": { "description": "Filters results by Autonomous System. Specify a single Autonomous System Number (ASN) as integer.", "type": "integer", "example": 174 } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify an alpha-2 location code.", "schema": { "description": "Filters results by location. Specify an alpha-2 location code.", "type": "string", "example": "US", "maxLength": 2, "minLength": 2 } }, { "name": "geoId", "in": "query", "description": "Filters results by geolocation. Refer to [GeoNames](https://download.geonames.org/export/dump/readme.txt).", "schema": { "description": "Filters results by geolocation. Refer to [GeoNames](https://download.geonames.org/export/dump/readme.txt).", "type": "string", "example": "3190509", "maxLength": 100 } }, { "name": "origin", "in": "query", "description": "Filters results by origin.", "schema": { "description": "Filters results by origin.", "type": "string", "example": "amazon-us-east-1", "maxLength": 100 } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain.", "schema": { "description": "Filters results by top-level domain.", "type": "string", "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$" } }, { "name": "ca", "in": "query", "description": "Filters results by certificate authority.", "schema": { "description": "Filters results by certificate authority.", "type": "string", "maxLength": 100 } }, { "name": "log", "in": "query", "description": "Filters results by certificate log.", "schema": { "description": "Filters results by certificate log.", "type": "string", "maxLength": 100 } }, { "name": "bot", "in": "query", "description": "Filters results by bot.", "schema": { "description": "Filters results by bot.", "type": "string", "example": "gptbot", "maxLength": 100 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "properties": { "asns": { "type": "array", "items": { "example": 189, "type": "integer" } }, "asnsDetails": { "type": "array", "items": { "properties": { "asn": { "type": "string", "example": "189" }, "location": { "type": "object", "nullable": true, "properties": { "code": { "type": "string", "example": "US" }, "name": { "type": "string", "example": "United States" } }, "required": [ "code", "name" ] }, "name": { "type": "string", "example": "LUMEN-LEGACY-L3-PARTITION", "nullable": true } }, "required": [ "asn", "name", "location" ], "type": "object" } }, "dataSource": { "type": "string", "example": "ALL" }, "description": { "type": "string", "example": "example", "nullable": true }, "endDate": { "type": "string", "example": "2022-09-08T10:00:28Z", "nullable": true }, "entities": { "type": "array", "items": { "properties": { "entityName": { "type": "string", "example": "GPTBot", "nullable": true }, "entityType": { "type": "string", "example": "BOT" }, "entityValue": { "type": "string", "example": "gptbot" } }, "required": [ "entityType", "entityValue", "entityName" ], "type": "object" } }, "eventType": { "type": "string", "example": "OUTAGE" }, "geoIds": { "type": "array", "items": { "example": "2267057", "type": "string" } }, "id": { "type": "string", "example": "550" }, "linkedUrl": { "type": "string", "example": "http://example.com", "nullable": true }, "locations": { "type": "array", "items": { "example": "US", "type": "string" } }, "locationsDetails": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "US" }, "name": { "type": "string", "example": "United States" } }, "required": [ "code", "name" ], "type": "object" } }, "origins": { "type": "array", "items": { "example": "amazon-us-east-1", "type": "string" } }, "originsDetails": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "us-east-1 Amazon Web Services", "nullable": true }, "origin": { "type": "string", "example": "amazon-us-east-1" } }, "required": [ "origin", "name" ], "type": "object" } }, "outage": { "type": "object", "nullable": true, "properties": { "outageCause": { "type": "string", "example": "CABLE_CUT" }, "outageType": { "type": "string", "example": "NATIONWIDE" } }, "required": [ "outageCause", "outageType" ] }, "scope": { "type": "string", "example": "Colima, Michoacán, México", "nullable": true }, "startDate": { "type": "string", "example": "2022-09-06T10:00:28Z" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "dataSource", "description", "scope", "startDate", "endDate", "asns", "asnsDetails", "locations", "geoIds", "entities", "locationsDetails", "origins", "originsDetails", "eventType", "tags", "linkedUrl", "outage" ], "type": "object" } } }, "required": [ "annotations" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Annotations" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.annotations", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/radar/annotations/outages": { "get": { "operationId": "radar-get-annotations-outages", "summary": "Get latest Internet outages and anomalies", "description": "Retrieves the latest Internet outages and anomalies.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Skips the specified number of objects before fetching the results.", "schema": { "description": "Skips the specified number of objects before fetching the results.", "type": "integer", "minimum": 0 } }, { "name": "dateRange", "in": "query", "description": "Filters results by a relative date range ending at the current time. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`), e.g. `7d`. Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `3dcontrol` covers days -10 to -7, `7dcontrol` covers days -14 to -7, `28dcontrol` covers days -56 to -28, and `10dcontrol` covers days -24 to -14). Mutually exclusive with `dateStart`/`dateEnd`.", "schema": { "description": "Filters results by a relative date range ending at the current time. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`), e.g. `7d`. Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `3dcontrol` covers days -10 to -7, `7dcontrol` covers days -14 to -7, `28dcontrol` covers days -56 to -28, and `10dcontrol` covers days -24 to -14). Mutually exclusive with `dateStart`/`dateEnd`.", "type": "string", "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "schema": { "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dataSource", "in": "query", "description": "Filters results by data source.", "schema": { "description": "Filters results by data source.", "type": "string", "example": "ALL", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] } }, { "name": "outageType", "in": "query", "description": "Filters results by outage type.", "schema": { "description": "Filters results by outage type.", "type": "string", "enum": [ "NATIONWIDE", "REGIONAL", "NETWORK", "PLATFORM" ] } }, { "name": "outageCause", "in": "query", "description": "Filters results by outage cause.", "schema": { "description": "Filters results by outage cause.", "type": "string", "enum": [ "BLOCKING", "CABLE_CUT", "CYBERATTACK", "DNS", "FIRE", "GOVERNMENT_DIRECTED", "MAINTENANCE", "MECHANICAL", "MILITARY_ACTION", "MISCONFIGURATION", "NATURAL_DISASTER", "NETWORK_PROBLEM", "POWER_OUTAGE", "SOFTWARE", "TECHNICAL_PROBLEM", "UNKNOWN", "WEATHER" ] } }, { "name": "tags", "in": "query", "description": "Filters results by annotation tag. Matches annotations carrying at least one of the given tags.", "schema": { "description": "Filters results by annotation tag. Matches annotations carrying at least one of the given tags.", "type": "array", "items": { "description": "Dimension tag an annotation applies to.", "enum": [ "ADM1", "ADM2", "API_TRAFFIC", "ARC", "AS", "ASN", "ATTACKS", "AUTHOR", "BANDWIDTH", "BITRATE", "BOT", "BOT_CATEGORY", "BOT_CLASS", "BOT_KIND", "BOT_OPERATOR", "BROWSER", "BROWSER_FAMILY", "BYTES", "CA", "CACHE_HIT", "CA_OWNER", "CHECK_RESULT", "CLIENT_TYPE", "COMPROMISED", "CONTENT_TYPE", "CRAWL_PURPOSE", "CRAWL_REFER_RATIO", "DEVICE_TYPE", "DKIM", "DMARC", "DNS", "DNSSEC", "DNSSEC_AWARE", "DNSSEC_E2E", "DOMAIN_CATEGORY", "DURATION", "EDNS", "ENCRYPTED", "ENTRY_TYPE", "EXPIRATION_STATUS", "HAS_IPS", "HAS_MATCHING_ANSWER", "HAS_WILDCARDS", "HTTP_METHOD", "HTTP_PROTOCOL", "HTTP_VERSION", "INDUSTRY", "IP_VERSION", "JITTER", "KEY_AGREEMENT", "LATENCY", "LOCATION", "LOCATION_LATENCY", "LOG", "LOG_API", "LOG_OPERATOR", "MALICIOUS", "MANAGED_RULES", "MITIGATION_PRODUCT", "MODEL", "NAMESERVER_LATENCY", "ORIGIN", "ORIGIN_AS", "ORIGIN_LOCATION", "ORIGIN_TARGET_LOCATION_PAIR", "OS", "PERCENTILE", "POST_QUANTUM", "PREFIX", "PRODUCT", "PROTOCOL", "PROVIDER", "PUBLIC_KEY_ALGORITHM", "QUERY_TYPE", "REFERER", "REGION", "RESPONSE_CODE", "RESPONSE_STATUS", "RESPONSE_STATUS_CATEGORY", "RESPONSE_TTL", "SIGNATURE_ALGORITHM", "SPAM", "SPF", "SPOOF", "SUCCESS_RATE", "TARGET_LOCATION", "TASK", "THREAT_CATEGORY", "TLD", "TLD_DNS_MAGNITUDE", "TLS_VERSION", "UPDATE_TYPE", "USER_AGENT", "VALIDATION_LEVEL", "VECTOR", "VERTICAL" ], "type": "string" } } }, { "name": "query", "in": "query", "description": "Filters results by a free-text match on the annotation description, id, or linked entities (location, ASN, origin).", "schema": { "description": "Filters results by a free-text match on the annotation description, id, or linked entities (location, ASN, origin).", "type": "string", "example": "portugal", "maxLength": 100 } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify a single Autonomous System Number (ASN) as integer.", "schema": { "description": "Filters results by Autonomous System. Specify a single Autonomous System Number (ASN) as integer.", "type": "integer", "example": 174 } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify an alpha-2 location code.", "schema": { "description": "Filters results by location. Specify an alpha-2 location code.", "type": "string", "example": "US", "maxLength": 2, "minLength": 2 } }, { "name": "geoId", "in": "query", "description": "Filters results by geolocation. Refer to [GeoNames](https://download.geonames.org/export/dump/readme.txt).", "schema": { "description": "Filters results by geolocation. Refer to [GeoNames](https://download.geonames.org/export/dump/readme.txt).", "type": "string", "example": "3190509", "maxLength": 100 } }, { "name": "origin", "in": "query", "description": "Filters results by origin.", "schema": { "description": "Filters results by origin.", "type": "string", "example": "amazon-us-east-1", "maxLength": 100 } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain.", "schema": { "description": "Filters results by top-level domain.", "type": "string", "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$" } }, { "name": "ca", "in": "query", "description": "Filters results by certificate authority.", "schema": { "description": "Filters results by certificate authority.", "type": "string", "maxLength": 100 } }, { "name": "log", "in": "query", "description": "Filters results by certificate log.", "schema": { "description": "Filters results by certificate log.", "type": "string", "maxLength": 100 } }, { "name": "bot", "in": "query", "description": "Filters results by bot.", "schema": { "description": "Filters results by bot.", "type": "string", "example": "gptbot", "maxLength": 100 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "properties": { "asns": { "type": "array", "items": { "example": 189, "type": "integer" } }, "asnsDetails": { "type": "array", "items": { "properties": { "asn": { "type": "string", "example": "189" }, "location": { "type": "object", "nullable": true, "properties": { "code": { "type": "string", "example": "US" }, "name": { "type": "string", "example": "United States" } }, "required": [ "code", "name" ] }, "name": { "type": "string", "example": "LUMEN-LEGACY-L3-PARTITION", "nullable": true } }, "required": [ "asn", "name", "location" ], "type": "object" } }, "dataSource": { "type": "string", "example": "ALL" }, "description": { "type": "string", "example": "example", "nullable": true }, "endDate": { "type": "string", "format": "date-time", "nullable": true }, "entities": { "type": "array", "items": { "properties": { "entityName": { "type": "string", "example": "GPTBot", "nullable": true }, "entityType": { "type": "string", "example": "BOT" }, "entityValue": { "type": "string", "example": "gptbot" } }, "required": [ "entityType", "entityValue", "entityName" ], "type": "object" } }, "eventType": { "type": "string", "example": "OUTAGE" }, "geoIds": { "type": "array", "items": { "example": "2267057", "type": "string" } }, "id": { "type": "string", "example": "550" }, "linkedUrl": { "type": "string", "example": "http://example.com", "nullable": true }, "locations": { "type": "array", "items": { "example": "US", "type": "string" } }, "locationsDetails": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "US" }, "name": { "type": "string", "example": "United States" } }, "required": [ "code", "name" ], "type": "object" } }, "origins": { "type": "array", "items": { "example": "amazon-us-east-1", "type": "string" } }, "originsDetails": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "us-east-1 Amazon Web Services", "nullable": true }, "origin": { "type": "string", "example": "amazon-us-east-1" } }, "required": [ "origin", "name" ], "type": "object" } }, "outage": { "type": "object", "nullable": true, "properties": { "outageCause": { "type": "string", "example": "CABLE_CUT" }, "outageType": { "type": "string", "example": "NATIONWIDE" } }, "required": [ "outageCause", "outageType" ] }, "scope": { "type": "string", "example": "Colima, Michoacán, México", "nullable": true }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "dataSource", "description", "scope", "startDate", "endDate", "asns", "asnsDetails", "locations", "geoIds", "entities", "locationsDetails", "origins", "originsDetails", "eventType", "tags", "linkedUrl", "outage" ], "type": "object" } } }, "required": [ "annotations" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Annotations" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.annotations.outages", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/annotations/outages/locations": { "get": { "operationId": "radar-get-annotations-outages-top", "summary": "Get the number of outages by location", "description": "Retrieves the number of outages by location.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "dateRange", "in": "query", "description": "Filters results by a relative date range ending at the current time. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`), e.g. `7d`. Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `3dcontrol` covers days -10 to -7, `7dcontrol` covers days -14 to -7, `28dcontrol` covers days -56 to -28, and `10dcontrol` covers days -24 to -14). Mutually exclusive with `dateStart`/`dateEnd`.", "schema": { "description": "Filters results by a relative date range ending at the current time. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`), e.g. `7d`. Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `3dcontrol` covers days -10 to -7, `7dcontrol` covers days -14 to -7, `28dcontrol` covers days -56 to -28, and `10dcontrol` covers days -24 to -14). Mutually exclusive with `dateStart`/`dateEnd`.", "type": "string", "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "schema": { "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "PT" }, "clientCountryName": { "type": "string", "example": "Portugal" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryAlpha2", "clientCountryName", "value" ], "type": "object" } } }, "required": [ "annotations" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Annotations" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.annotations.outages", "x-fern-sdk-method-name": "locations", "x-forge-hidden": true } }, "/radar/annotations/{id}": { "get": { "operationId": "radar-get-annotation-by-id", "summary": "Get annotation by ID", "description": "Retrieves a single annotation by ID.", "parameters": [ { "name": "id", "in": "path", "description": "Annotation ID.", "required": true, "schema": { "description": "Annotation ID.", "type": "string", "example": "550", "pattern": "^[1-9]\\d{0,18}$" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "annotation": { "type": "object", "properties": { "asns": { "type": "array", "items": { "example": 189, "type": "integer" } }, "asnsDetails": { "type": "array", "items": { "properties": { "asn": { "type": "string", "example": "189" }, "location": { "type": "object", "nullable": true, "properties": { "code": { "type": "string", "example": "US" }, "name": { "type": "string", "example": "United States" } }, "required": [ "code", "name" ] }, "name": { "type": "string", "example": "LUMEN-LEGACY-L3-PARTITION", "nullable": true } }, "required": [ "asn", "name", "location" ], "type": "object" } }, "dataSource": { "type": "string", "example": "ALL" }, "description": { "type": "string", "example": "example", "nullable": true }, "endDate": { "type": "string", "format": "date-time", "nullable": true }, "entities": { "type": "array", "items": { "properties": { "entityName": { "type": "string", "example": "GPTBot", "nullable": true }, "entityType": { "type": "string", "example": "BOT" }, "entityValue": { "type": "string", "example": "gptbot" } }, "required": [ "entityType", "entityValue", "entityName" ], "type": "object" } }, "eventType": { "type": "string", "example": "OUTAGE" }, "geoIds": { "type": "array", "items": { "example": "2267057", "type": "string" } }, "id": { "type": "string", "example": "550" }, "linkedUrl": { "type": "string", "example": "http://example.com", "nullable": true }, "locations": { "type": "array", "items": { "example": "US", "type": "string" } }, "locationsDetails": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "US" }, "name": { "type": "string", "example": "United States" } }, "required": [ "code", "name" ], "type": "object" } }, "origins": { "type": "array", "items": { "example": "amazon-us-east-1", "type": "string" } }, "originsDetails": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "us-east-1 Amazon Web Services", "nullable": true }, "origin": { "type": "string", "example": "amazon-us-east-1" } }, "required": [ "origin", "name" ], "type": "object" } }, "outage": { "type": "object", "nullable": true, "properties": { "outageCause": { "type": "string", "example": "CABLE_CUT" }, "outageType": { "type": "string", "example": "NATIONWIDE" } }, "required": [ "outageCause", "outageType" ] }, "scope": { "type": "string", "example": "Colima, Michoacán, México", "nullable": true }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "dataSource", "description", "scope", "startDate", "endDate", "asns", "asnsDetails", "locations", "geoIds", "entities", "locationsDetails", "origins", "originsDetails", "eventType", "tags", "linkedUrl", "outage" ] } }, "required": [ "annotation" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Annotations" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.annotations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/as112/summary/dnssec": { "get": { "operationId": "radar-get-dns-as112-timeseries-by-dnssec", "summary": "Get AS112 DNS queries by DNSSEC summary", "description": "Retrieves the distribution of DNS queries to AS112 by DNSSEC (DNS Security Extensions) support.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "NOT_SUPPORTED": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "SUPPORTED": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "SUPPORTED", "NOT_SUPPORTED" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.as112.summary", "x-fern-sdk-method-name": "dnssec", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AS112 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/as112/methods/summary_v2/) instead." } }, "/radar/as112/summary/edns": { "get": { "operationId": "radar-get-dns-as112-timeseries-by-edns", "summary": "Get AS112 DNS queries by EDNS summary", "description": "Retrieves the distribution of DNS queries to AS112 by EDNS (Extension Mechanisms for DNS) support.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "NOT_SUPPORTED": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "SUPPORTED": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "SUPPORTED", "NOT_SUPPORTED" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.as112.summary", "x-fern-sdk-method-name": "edns", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AS112 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/as112/methods/summary_v2/) instead." } }, "/radar/as112/summary/ip_version": { "get": { "operationId": "radar-get-dns-as112-timeseries-by-ip-version", "summary": "Get AS112 DNS queries by IP version summary", "description": "Retrieves the distribution of DNS queries to AS112 by IP version.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "IPv4": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "IPv6": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "IPv4", "IPv6" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.as112.summary", "x-fern-sdk-method-name": "ip-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AS112 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/as112/methods/summary_v2/) instead." } }, "/radar/as112/summary/protocol": { "get": { "operationId": "radar-get-dns-as112-timeseries-by-protocol", "summary": "Get AS112 DNS queries by DNS protocol summary", "description": "Retrieves the distribution of DNS queries to AS112 by protocol.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "HTTPS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "TCP": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "TLS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "UDP": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "UDP", "TLS", "HTTPS", "TCP" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.as112.summary", "x-fern-sdk-method-name": "protocol", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AS112 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/as112/methods/summary_v2/) instead." } }, "/radar/as112/summary/query_type": { "get": { "operationId": "radar-get-dns-as112-timeseries-by-query-type", "summary": "Get AS112 DNS queries by type summary", "description": "Retrieves the distribution of DNS queries to AS112 by type.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "A": "19", "AAAA": "1", "PTR": "74", "SOA": "5", "SRV": "1" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.as112.summary", "x-fern-sdk-method-name": "query-type", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AS112 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/as112/methods/summary_v2/) instead." } }, "/radar/as112/summary/response_codes": { "get": { "operationId": "radar-get-dns-as112-timeseries-by-response-codes", "summary": "Get AS112 DNS queries by response code summary", "description": "Retrieves the distribution of AS112 DNS requests classified by response code.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "NOERROR": "70", "NOTIMP": "5", "NXDOMAIN": "10", "REFUSED": "5", "SERVFAIL": "5" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.as112.summary", "x-fern-sdk-method-name": "response-codes", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AS112 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/as112/methods/summary_v2/) instead." } }, "/radar/as112/summary/{dimension}": { "get": { "operationId": "radar-get-dns-as112-summary", "summary": "Get AS112 summary by dimension", "description": "Retrieves the distribution of AS112 queries by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "DNSSEC", "EDNS", "IP_VERSION", "PROTOCOL", "QUERY_TYPE", "RESPONSE_CODE" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "IPv4": "50.168733", "IPv6": "25.084366" }, "additionalProperties": { "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.as112", "x-fern-sdk-method-name": "summary-v2", "x-forge-hidden": true } }, "/radar/as112/timeseries": { "get": { "operationId": "radar-get-dns-as112-timeseries", "summary": "Get AS112 DNS queries time series", "description": "Retrieves the AS112 DNS queries over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "additionalProperties": { "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } }, "values": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "timestamps", "values" ], "type": "object" }, "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] } }, "required": [ "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.as112", "x-fern-sdk-method-name": "timeseries", "x-forge-hidden": true } }, "/radar/as112/timeseries_groups/dnssec": { "get": { "operationId": "radar-get-dns-as112-timeseries-group-by-dnssec", "summary": "Get AS112 DNS queries by DNSSEC support time series", "description": "Retrieves the distribution of AS112 DNS queries by DNSSEC (DNS Security Extensions) support over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "NOT_SUPPORTED": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "SUPPORTED": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "SUPPORTED", "NOT_SUPPORTED" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.as112.timeseries-groups", "x-fern-sdk-method-name": "dnssec", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AS112 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/as112/methods/timeseries_groups_v2/) instead." } }, "/radar/as112/timeseries_groups/edns": { "get": { "operationId": "radar-get-dns-as112-timeseries-group-by-edns", "summary": "Get AS112 DNS queries by EDNS support summary", "description": "Retrieves the distribution of AS112 DNS queries by EDNS (Extension Mechanisms for DNS) support over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "NOT_SUPPORTED": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "SUPPORTED": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "SUPPORTED", "NOT_SUPPORTED" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.as112.timeseries-groups", "x-fern-sdk-method-name": "edns", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AS112 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/as112/methods/timeseries_groups_v2/) instead." } }, "/radar/as112/timeseries_groups/ip_version": { "get": { "operationId": "radar-get-dns-as112-timeseries-group-by-ip-version", "summary": "Get AS112 DNS queries by IP version time series", "description": "Retrieves the distribution of AS112 DNS queries by IP version over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "IPv4": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "IPv6": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "IPv4", "IPv6" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.as112.timeseries-groups", "x-fern-sdk-method-name": "ip-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AS112 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/as112/methods/timeseries_groups_v2/) instead." } }, "/radar/as112/timeseries_groups/protocol": { "get": { "operationId": "radar-get-dns-as112-timeseries-group-by-protocol", "summary": "Get AS112 DNS queries by DNS protocol time series", "description": "Retrieves the distribution of AS112 DNS requests classified by protocol over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "HTTPS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "TCP": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "TLS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "UDP": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "UDP", "TLS", "HTTPS", "TCP" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.as112.timeseries-groups", "x-fern-sdk-method-name": "protocol", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AS112 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/as112/methods/timeseries_groups_v2/) instead." } }, "/radar/as112/timeseries_groups/query_type": { "get": { "operationId": "radar-get-dns-as112-timeseries-group-by-query-type", "summary": "Get AS112 DNS queries by type time series", "description": "Retrieves the distribution of AS112 DNS queries by type over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "A": [ "20" ], "AAAA": [ "20" ], "HTTPS": [ "20" ], "NS": [ "20" ], "PTR": [ "20" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.as112.timeseries-groups", "x-fern-sdk-method-name": "query-type", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AS112 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/as112/methods/timeseries_groups_v2/) instead." } }, "/radar/as112/timeseries_groups/response_codes": { "get": { "operationId": "radar-get-dns-as112-timeseries-group-by-response-codes", "summary": "Get AS112 DNS queries by response code time series", "description": "Retrieves the distribution of AS112 DNS requests classified by response code over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "NOERROR": [ "70" ], "NOTIMP": [ "5" ], "NXDOMAIN": [ "10" ], "REFUSED": [ "5" ], "SERVFAIL": [ "5" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.as112.timeseries-groups", "x-fern-sdk-method-name": "response-codes", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar AS112 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/as112/methods/timeseries_groups_v2/) instead." } }, "/radar/as112/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-dns-as112-timeseries-group", "summary": "Get AS112 time series grouped by dimension", "description": "Retrieves the distribution of AS112 queries grouped by dimension over time.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "DNSSEC", "EDNS", "IP_VERSION", "PROTOCOL", "QUERY_TYPE", "RESPONSE_CODE" ] } }, { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "IPv4": [ "50.168733" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.as112", "x-fern-sdk-method-name": "timeseries-groups-v2", "x-forge-hidden": true } }, "/radar/as112/top/locations": { "get": { "operationId": "radar-get-dns-as112-top-locations", "summary": "Get top locations by AS112 DNS queries", "description": "Retrieves the top locations by AS112 DNS queries.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "US" }, "clientCountryName": { "type": "string", "example": "United States" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryAlpha2", "clientCountryName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.as112.top", "x-fern-sdk-method-name": "locations", "x-forge-hidden": true } }, "/radar/as112/top/locations/dnssec/{dnssec}": { "get": { "operationId": "radar-get-dns-as112-top-locations-by-dnssec", "summary": "Get top locations by AS112 DNS queries with DNSSEC support", "description": "Retrieves the top locations of DNS queries to AS112 with DNSSEC (DNS Security Extensions) support.", "parameters": [ { "name": "dnssec", "in": "path", "description": "DNSSEC (DNS Security Extensions) status.", "required": true, "schema": { "description": "DNSSEC (DNS Security Extensions) status.", "type": "string", "example": "SUPPORTED", "enum": [ "SUPPORTED", "NOT_SUPPORTED" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "US" }, "clientCountryName": { "type": "string", "example": "United States" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryAlpha2", "clientCountryName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.as112.top", "x-fern-sdk-method-name": "dnssec", "x-forge-hidden": true } }, "/radar/as112/top/locations/edns/{edns}": { "get": { "operationId": "radar-get-dns-as112-top-locations-by-edns", "summary": "Get top locations by AS112 DNS queries with EDNS support", "description": "Retrieves the top locations of DNS queries to AS112 with EDNS (Extension Mechanisms for DNS) support.", "parameters": [ { "name": "edns", "in": "path", "description": "EDNS (Extension Mechanisms for DNS) status.", "required": true, "schema": { "description": "EDNS (Extension Mechanisms for DNS) status.", "type": "string", "example": "SUPPORTED", "enum": [ "SUPPORTED", "NOT_SUPPORTED" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "US" }, "clientCountryName": { "type": "string", "example": "United States" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryAlpha2", "clientCountryName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.as112.top", "x-fern-sdk-method-name": "edns", "x-forge-hidden": true } }, "/radar/as112/top/locations/ip_version/{ip_version}": { "get": { "operationId": "radar-get-dns-as112-top-locations-by-ip-version", "summary": "Get top locations by AS112 DNS queries for an IP version", "description": "Retrieves the top locations of DNS queries to AS112 for an IP version.", "parameters": [ { "name": "ip_version", "in": "path", "description": "IP version.", "required": true, "schema": { "description": "IP version.", "type": "string", "enum": [ "IPv4", "IPv6" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "US" }, "clientCountryName": { "type": "string", "example": "United States" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryAlpha2", "clientCountryName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar AS112" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.as112.top", "x-fern-sdk-method-name": "ip-version", "x-forge-hidden": true } }, "/radar/attacks/layer3/summary/bitrate": { "get": { "operationId": "radar-get-attacks-layer3-summary-by-bitrate", "summary": "Get layer 3 attacks by bitrate summary", "description": "Retrieves the distribution of layer 3 attacks by bitrate.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "OVER_100_GBPS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "UNDER_500_MBPS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "_10_GBPS_TO_100_GBPS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "_1_GBPS_TO_10_GBPS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "_500_MBPS_TO_1_GBPS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "UNDER_500_MBPS", "OVER_100_GBPS", "_1_GBPS_TO_10_GBPS", "_500_MBPS_TO_1_GBPS", "_10_GBPS_TO_100_GBPS" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer3.summary", "x-fern-sdk-method-name": "bitrate", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 3 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer3/methods/summary_v2/) instead." } }, "/radar/attacks/layer3/summary/duration": { "get": { "operationId": "radar-get-attacks-layer3-summary-by-duration", "summary": "Get layer 3 attacks by duration summary", "description": "Retrieves the distribution of layer 3 attacks by duration.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "OVER_3_HOURS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "UNDER_10_MINS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "_10_MINS_TO_20_MINS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "_1_HOUR_TO_3_HOURS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "_20_MINS_TO_40_MINS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "_40_MINS_TO_1_HOUR": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "UNDER_10_MINS", "_10_MINS_TO_20_MINS", "OVER_3_HOURS", "_1_HOUR_TO_3_HOURS", "_20_MINS_TO_40_MINS", "_40_MINS_TO_1_HOUR" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer3.summary", "x-fern-sdk-method-name": "duration", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 3 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer3/methods/summary_v2/) instead." } }, "/radar/attacks/layer3/summary/industry": { "get": { "operationId": "radar-get-attacks-layer3-summary-by-industry", "summary": "Get layer 3 attacks by targeted industry summary", "description": "Retrieves the distribution of layer 3 attacks by targeted industry.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "Computer Software": "65" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer3.summary", "x-fern-sdk-method-name": "industry", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 3 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer3/methods/summary_v2/) instead." } }, "/radar/attacks/layer3/summary/ip_version": { "get": { "operationId": "radar-get-attacks-layer3-summary-by-ip-version", "summary": "Get layer 3 attacks by IP version summary", "description": "Retrieves the distribution of layer 3 attacks by IP version.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "IPv4": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "IPv6": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "IPv4", "IPv6" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer3.summary", "x-fern-sdk-method-name": "ip-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 3 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer3/methods/summary_v2/) instead." } }, "/radar/attacks/layer3/summary/protocol": { "get": { "operationId": "radar-get-attacks-layer3-summary-by-protocol", "summary": "Get layer 3 attacks by protocol summary", "description": "Retrieves the distribution of layer 3 attacks by protocol.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "GRE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "ICMP": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "TCP": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "UDP": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "TCP", "UDP", "GRE", "ICMP" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer3.summary", "x-fern-sdk-method-name": "protocol", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 3 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer3/methods/summary_v2/) instead." } }, "/radar/attacks/layer3/summary/vector": { "get": { "operationId": "radar-get-attacks-layer3-summary-by-vector", "summary": "Get layer 3 attacks by vector summary", "description": "Retrieves the distribution of layer 3 attacks by vector.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "ACK Flood": "65.662148", "SYN Flood": "16.86401" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer3.summary", "x-fern-sdk-method-name": "vector", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 3 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer3/methods/summary_v2/) instead." } }, "/radar/attacks/layer3/summary/vertical": { "get": { "operationId": "radar-get-attacks-layer3-summary-by-vertical", "summary": "Get layer 3 attacks by targeted vertical summary", "description": "Retrieves the distribution of layer 3 attacks by targeted vertical.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "Internet and Telecom": "5.519081" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer3.summary", "x-fern-sdk-method-name": "vertical", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 3 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer3/methods/summary_v2/) instead." } }, "/radar/attacks/layer3/summary/{dimension}": { "get": { "operationId": "radar-get-attacks-layer3-summary", "summary": "Get layer 3 attacks summary by dimension", "description": "Retrieves the distribution of layer 3 attacks by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "PROTOCOL", "IP_VERSION", "VECTOR", "DURATION", "BITRATE", "VERTICAL", "INDUSTRY" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "TCP": "50.168733", "UDP": "25.084366" }, "additionalProperties": { "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.attacks.layer3", "x-fern-sdk-method-name": "summary-v2", "x-forge-hidden": true } }, "/radar/attacks/layer3/timeseries": { "get": { "operationId": "radar-get-attacks-layer3-timeseries-by-bytes", "summary": "Get layer 3 attacks by bytes time series", "description": "Retrieves layer 3 attacks over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `PERCENTAGE_CHANGE` requires exactly one comparison series (e.g. a `control` date range).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `PERCENTAGE_CHANGE` requires exactly one comparison series (e.g. a `control` date range).", "type": "string", "example": "MIN0_MAX", "enum": [ "PERCENTAGE_CHANGE", "MIN0_MAX" ] } }, { "name": "metric", "in": "query", "description": "Measurement units, eg. bytes.", "schema": { "description": "Measurement units, eg. bytes.", "type": "string", "default": "bytes", "enum": [ "BYTES", "BYTES_OLD" ] } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "additionalProperties": { "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } }, "values": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "timestamps", "values" ], "type": "object" }, "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] } }, "required": [ "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.attacks.layer3", "x-fern-sdk-method-name": "timeseries", "x-forge-hidden": true } }, "/radar/attacks/layer3/timeseries_groups/bitrate": { "get": { "operationId": "radar-get-attacks-layer3-timeseries-group-by-bitrate", "summary": "Get layer 3 attacks by bitrate time series", "description": "Retrieves the distribution of layer 3 attacks by bitrate over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "OVER_100_GBPS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "UNDER_500_MBPS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "_10_GBPS_TO_100_GBPS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "_1_GBPS_TO_10_GBPS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "_500_MBPS_TO_1_GBPS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "UNDER_500_MBPS", "OVER_100_GBPS", "_1_GBPS_TO_10_GBPS", "_500_MBPS_TO_1_GBPS", "_10_GBPS_TO_100_GBPS" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer3.timeseries-groups", "x-fern-sdk-method-name": "bitrate", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 3 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer3/methods/timeseries_groups_v2/) instead." } }, "/radar/attacks/layer3/timeseries_groups/duration": { "get": { "operationId": "radar-get-attacks-layer3-timeseries-group-by-duration", "summary": "Get layer 3 attacks by duration time series", "description": "Retrieves the distribution of layer 3 attacks by duration over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "OVER_3_HOURS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "UNDER_10_MINS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "_10_MINS_TO_20_MINS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "_1_HOUR_TO_3_HOURS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "_20_MINS_TO_40_MINS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "_40_MINS_TO_1_HOUR": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "UNDER_10_MINS", "_10_MINS_TO_20_MINS", "OVER_3_HOURS", "_1_HOUR_TO_3_HOURS", "_20_MINS_TO_40_MINS", "_40_MINS_TO_1_HOUR" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer3.timeseries-groups", "x-fern-sdk-method-name": "duration", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 3 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer3/methods/timeseries_groups_v2/) instead." } }, "/radar/attacks/layer3/timeseries_groups/industry": { "get": { "operationId": "radar-get-attacks-layer3-timeseries-group-by-industry", "summary": "Get layer 3 attacks by target industries time series", "description": "Retrieves the distribution of layer 3 attacks by targeted industry over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "Internet": [ "5.519081" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer3.timeseries-groups", "x-fern-sdk-method-name": "industry", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 3 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer3/methods/timeseries_groups_v2/) instead." } }, "/radar/attacks/layer3/timeseries_groups/ip_version": { "get": { "operationId": "radar-get-attacks-layer3-timeseries-group-by-ip-version", "summary": "Get layer 3 attacks by IP version time series", "description": "Retrieves the distribution of layer 3 attacks by IP version over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "IPv4": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "IPv6": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "IPv4", "IPv6" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer3.timeseries-groups", "x-fern-sdk-method-name": "ip-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 3 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer3/methods/timeseries_groups_v2/) instead." } }, "/radar/attacks/layer3/timeseries_groups/protocol": { "get": { "operationId": "radar-get-attacks-layer3-timeseries-group-by-protocol", "summary": "Get layer 3 attacks by protocol time series", "description": "Retrieves the distribution of layer 3 attacks by protocol over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "GRE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "ICMP": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "TCP": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "UDP": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "TCP", "UDP", "GRE", "ICMP" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer3.timeseries-groups", "x-fern-sdk-method-name": "protocol", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 3 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer3/methods/timeseries_groups_v2/) instead." } }, "/radar/attacks/layer3/timeseries_groups/vector": { "get": { "operationId": "radar-get-attacks-layer3-timeseries-group-by-vector", "summary": "Get layer 3 attacks by vector time series", "description": "Retrieves the distribution of layer 3 attacks by vector over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "ACK Flood": [ "97.28898" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer3.timeseries-groups", "x-fern-sdk-method-name": "vector", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 3 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer3/methods/timeseries_groups_v2/) instead." } }, "/radar/attacks/layer3/timeseries_groups/vertical": { "get": { "operationId": "radar-get-attacks-layer3-timeseries-group-by-vertical", "summary": "Get layer 3 attacks by vertical time series", "description": "Retrieves the distribution of layer 3 attacks by targeted vertical over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "Internet and Telecom": [ "5.519081" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer3.timeseries-groups", "x-fern-sdk-method-name": "vertical", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 3 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer3/methods/timeseries_groups_v2/) instead." } }, "/radar/attacks/layer3/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-attacks-layer3-timeseries-group", "summary": "Get layer 3 attacks time series grouped by dimension", "description": "Retrieves the distribution of layer 3 attacks grouped by dimension over time.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "PROTOCOL", "IP_VERSION", "VECTOR", "DURATION", "BITRATE", "VERTICAL", "INDUSTRY" ] } }, { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "direction", "in": "query", "description": "Specifies whether the `location` filter applies to the source or target location.", "schema": { "description": "Specifies whether the `location` filter applies to the source or target location.", "type": "string", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "TCP": [ "50.168733" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.attacks.layer3", "x-fern-sdk-method-name": "timeseries-groups-v2", "x-forge-hidden": true } }, "/radar/attacks/layer3/top/attacks": { "get": { "operationId": "radar-get-attacks-layer3-top-attacks", "summary": "Get top layer 3 attack pairs (origin and target locations)", "description": "Retrieves the top layer 3 attacks from origin to target location. Values are a percentage out of the total layer 3 attacks (with billing country). You can optionally limit the number of attacks by origin/target location (useful if all the top attacks are from or to the same location).", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "limitDirection", "in": "query", "description": "Specifies whether the `limitPerLocation` applies to the source or target location.", "schema": { "description": "Specifies whether the `limitPerLocation` applies to the source or target location.", "type": "string", "example": "ORIGIN", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "limitPerLocation", "in": "query", "description": "Limits the number of attacks per origin/target (refer to `limitDirection` parameter) location.", "schema": { "description": "Limits the number of attacks per origin/target (refer to `limitDirection` parameter) location.", "type": "integer", "example": 10, "default": 10, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "magnitude", "in": "query", "description": "Orders results based on attack magnitude, defined by total mitigated bytes or total mitigated attacks.", "schema": { "description": "Orders results based on attack magnitude, defined by total mitigated bytes or total mitigated attacks.", "type": "string", "example": "MITIGATED_BYTES", "enum": [ "MITIGATED_BYTES", "MITIGATED_ATTACKS" ] } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN_MAX" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "originCountryAlpha2": { "type": "string", "example": "FR" }, "originCountryName": { "type": "string", "example": "France" }, "value": { "type": "string", "example": "4.323214" } }, "required": [ "originCountryAlpha2", "originCountryName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.attacks.layer3.top", "x-fern-sdk-method-name": "attacks", "x-forge-hidden": true } }, "/radar/attacks/layer3/top/industry": { "get": { "operationId": "radar-get-attacks-layer3-top-industries", "summary": "Get top industries targeted by layer 3 attacks", "description": "This endpoint is deprecated. To continue getting this data, switch to the summary by industry endpoint.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Computer Software" }, "value": { "type": "string", "example": "65" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer3.top", "x-fern-sdk-method-name": "industry", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 3 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer3/methods/summary_v2/) instead." } }, "/radar/attacks/layer3/top/locations/origin": { "get": { "operationId": "radar-get-attacks-layer3-top-origin-locations", "summary": "Get top origin locations of layer 3 attacks", "description": "Retrieves the origin locations of layer 3 attacks.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "originCountryAlpha2": { "type": "string", "example": "FR" }, "originCountryName": { "type": "string", "example": "France" }, "rank": { "type": "number", "example": 1 }, "value": { "type": "string", "example": "4.323214" } }, "required": [ "originCountryAlpha2", "originCountryName", "value", "rank" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.attacks.layer3.top.locations", "x-fern-sdk-method-name": "origin", "x-forge-hidden": true } }, "/radar/attacks/layer3/top/locations/target": { "get": { "operationId": "radar-get-attacks-layer3-top-target-locations", "summary": "Get top target locations of layer 3 attacks", "description": "Retrieves the target locations of layer 3 attacks.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "rank": { "type": "number", "example": 1 }, "targetCountryAlpha2": { "type": "string", "example": "FR" }, "targetCountryName": { "type": "string", "example": "France" }, "value": { "type": "string", "example": "4.323214" } }, "required": [ "targetCountryAlpha2", "targetCountryName", "value", "rank" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.attacks.layer3.top.locations", "x-fern-sdk-method-name": "target", "x-forge-hidden": true } }, "/radar/attacks/layer3/top/vertical": { "get": { "operationId": "radar-get-attacks-layer3-top-verticals", "summary": "Get top verticals targeted by layer 3 attacks", "description": "This endpoint is deprecated. To continue getting this data, switch to the summary by vertical endpoint.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "protocol", "in": "query", "description": "Filters the results by layer 3/4 protocol.", "schema": { "description": "Filters the results by layer 3/4 protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "ICMP", "GRE" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Internet and Telecom" }, "value": { "type": "string", "example": "65" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 3 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer3.top", "x-fern-sdk-method-name": "vertical", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 3 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer3/methods/summary_v2/) instead." } }, "/radar/attacks/layer7/summary/http_method": { "get": { "operationId": "radar-get-attacks-layer7-summary-by-http-method", "summary": "Get layer 7 attacks by HTTP method summary", "description": "Retrieves the distribution of layer 7 attacks by HTTP method.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "GET": "99.100257", "POST": "0.899743" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer7.summary", "x-fern-sdk-method-name": "http-method", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 7 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer7/methods/summary_v2/) instead." } }, "/radar/attacks/layer7/summary/http_version": { "get": { "operationId": "radar-get-attacks-layer7-summary-by-http-version", "summary": "Get layer 7 attacks by HTTP version summary", "description": "Retrieves the distribution of layer 7 attacks by HTTP version.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "HTTP/1.x": "21.722365", "HTTP/2": "77.056555", "HTTP/3": "1.22108" }, "properties": { "HTTP/1.x": { "type": "string" }, "HTTP/2": { "type": "string" }, "HTTP/3": { "type": "string" } }, "required": [ "HTTP/2", "HTTP/1.x", "HTTP/3" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer7.summary", "x-fern-sdk-method-name": "http-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 7 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer7/methods/summary_v2/) instead." } }, "/radar/attacks/layer7/summary/industry": { "get": { "operationId": "radar-get-attacks-layer7-summary-by-industry", "summary": "Get layer 7 attacks by targeted industry summary", "description": "Retrieves the distribution of layer 7 attacks by targeted industry.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "Computer Software": "65" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer7.summary", "x-fern-sdk-method-name": "industry", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 7 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer7/methods/summary_v2/) instead." } }, "/radar/attacks/layer7/summary/ip_version": { "get": { "operationId": "radar-get-attacks-layer7-summary-by-ip-version", "summary": "Get layer 7 attacks by IP version summary", "description": "Retrieves the distribution of layer 7 attacks by IP version.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "IPv4": "99.935733", "IPv6": "0.064267" }, "properties": { "IPv4": { "type": "string" }, "IPv6": { "type": "string" } }, "required": [ "IPv4", "IPv6" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer7.summary", "x-fern-sdk-method-name": "ip-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 7 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer7/methods/summary_v2/) instead." } }, "/radar/attacks/layer7/summary/managed_rules": { "get": { "operationId": "radar-get-attacks-layer7-summary-by-managed-rules", "summary": "Get layer 7 attacks by managed rules summary", "description": "Retrieves the distribution of layer 7 attacks by managed rules.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "HTTP Anomaly": "85.714286", "XSS": "10.274394" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer7.summary", "x-fern-sdk-method-name": "managed-rules", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 7 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer7/methods/summary_v2/) instead." } }, "/radar/attacks/layer7/summary/mitigation_product": { "get": { "operationId": "radar-get-attacks-layer7-summary-by-mitigation-product", "summary": "Get layer 7 attacks by mitigation product summary", "description": "Retrieves the distribution of layer 7 attacks by mitigation product.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "DDOS": "24.421594", "WAF": "53.213368" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer7.summary", "x-fern-sdk-method-name": "mitigation-product", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 7 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer7/methods/summary_v2/) instead." } }, "/radar/attacks/layer7/summary/vertical": { "get": { "operationId": "radar-get-attacks-layer7-summary-by-vertical", "summary": "Get layer 7 attacks by targeted vertical summary", "description": "Retrieves the distribution of layer 7 attacks by targeted vertical.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "Internet and Telecom": "5.519081" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer7.summary", "x-fern-sdk-method-name": "vertical", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 7 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer7/methods/summary_v2/) instead." } }, "/radar/attacks/layer7/summary/{dimension}": { "get": { "operationId": "radar-get-attacks-layer7-summary", "summary": "Get layer 7 attacks summary by dimension", "description": "Retrieves the distribution of layer 7 attacks by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "HTTP_METHOD", "HTTP_VERSION", "IP_VERSION", "MANAGED_RULES", "MITIGATION_PRODUCT", "VERTICAL", "INDUSTRY" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "GET": "50.168733", "POST": "25.084366" }, "additionalProperties": { "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.attacks.layer7", "x-fern-sdk-method-name": "summary-v2", "x-forge-hidden": true } }, "/radar/attacks/layer7/timeseries": { "get": { "operationId": "radar-get-attacks-layer7-timeseries", "summary": "Get layer 7 attacks time series", "description": "Retrieves layer 7 attacks over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `PERCENTAGE_CHANGE` requires exactly one comparison series (e.g. a `control` date range).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `PERCENTAGE_CHANGE` requires exactly one comparison series (e.g. a `control` date range).", "type": "string", "example": "MIN0_MAX", "enum": [ "PERCENTAGE_CHANGE", "MIN0_MAX" ] } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } }, "values": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "timestamps", "values" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.attacks.layer7", "x-fern-sdk-method-name": "timeseries", "x-forge-hidden": true } }, "/radar/attacks/layer7/timeseries_groups/http_method": { "get": { "operationId": "radar-get-attacks-layer7-timeseries-group-by-http-method", "summary": "Get layer 7 attacks by HTTP method time series", "description": "Retrieves the distribution of layer 7 attacks by HTTP method over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "GET": [ "70.970199" ], "timestamps": [ "2023-10-01T00:00:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer7.timeseries-groups", "x-fern-sdk-method-name": "http-method", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 7 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer7/methods/timeseries_groups_v2/) instead." } }, "/radar/attacks/layer7/timeseries_groups/http_version": { "get": { "operationId": "radar-get-attacks-layer7-timeseries-group-by-http-version", "summary": "Get layer 7 attacks by HTTP version time series", "description": "Retrieves the distribution of layer 7 attacks by HTTP version over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "HTTP/1.x": [ "50.338734" ], "HTTP/2": [ "48.661266" ], "HTTP/3": [ "1.22108" ], "timestamps": [ "2023-10-01T00:00:00Z" ] }, "properties": { "HTTP/1.x": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "HTTP/2": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "HTTP/3": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "HTTP/1.x", "HTTP/2", "HTTP/3" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer7.timeseries-groups", "x-fern-sdk-method-name": "http-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 7 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer7/methods/timeseries_groups_v2/) instead." } }, "/radar/attacks/layer7/timeseries_groups/industry": { "get": { "operationId": "radar-get-attacks-layer7-timeseries-group-by-industry", "summary": "Get layer 7 attacks by target industries time series", "description": "Retrieves the distribution of layer 7 attacks by targeted industry over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "Internet": [ "5.519081" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer7.timeseries-groups", "x-fern-sdk-method-name": "industry", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 7 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer7/methods/timeseries_groups_v2/) instead." } }, "/radar/attacks/layer7/timeseries_groups/ip_version": { "get": { "operationId": "radar-get-attacks-layer7-timeseries-group-by-ip-version", "summary": "Get layer 7 attacks by IP version time series", "description": "Retrieves the distribution of layer 7 attacks by IP version used over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "IPv4": [ "99.935733" ], "IPv6": [ "0.064267" ], "timestamps": [ "2023-10-01T00:00:00Z" ] }, "properties": { "IPv4": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "IPv6": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "IPv4", "IPv6" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer7.timeseries-groups", "x-fern-sdk-method-name": "ip-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 7 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer7/methods/timeseries_groups_v2/) instead." } }, "/radar/attacks/layer7/timeseries_groups/managed_rules": { "get": { "operationId": "radar-get-attacks-layer7-timeseries-group-by-managed-rules", "summary": "Get layer 7 attacks by managed rules time series", "description": "Retrieves the distribution of layer 7 attacks by managed rules over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "XSS": [ "0.324198" ], "timestamps": [ "2023-10-01T00:00:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer7.timeseries-groups", "x-fern-sdk-method-name": "managed-rules", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 7 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer7/methods/timeseries_groups_v2/) instead." } }, "/radar/attacks/layer7/timeseries_groups/mitigation_product": { "get": { "operationId": "radar-get-attacks-layer7-timeseries-group-by-mitigation-product", "summary": "Get layer 7 attacks by mitigation product time series", "description": "Retrieves the distribution of layer 7 attacks by mitigation product over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "DDOS": [ "48.926354" ], "timestamps": [ "2023-10-01T00:00:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer7.timeseries-groups", "x-fern-sdk-method-name": "mitigation-product", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 7 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer7/methods/timeseries_groups_v2/) instead." } }, "/radar/attacks/layer7/timeseries_groups/vertical": { "get": { "operationId": "radar-get-attacks-layer7-timeseries-group-by-vertical", "summary": "Get layer 7 attacks by vertical time series", "description": "Retrieves the distribution of layer 7 attacks by targeted vertical over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "Internet and Telecom": [ "5.519081" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer7.timeseries-groups", "x-fern-sdk-method-name": "vertical", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 7 Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer7/methods/timeseries_groups_v2/) instead." } }, "/radar/attacks/layer7/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-attacks-layer7-timeseries-group", "summary": "Get layer 7 attacks time series grouped by dimension", "description": "Retrieves the distribution of layer 7 attacks grouped by dimension over time.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "HTTP_METHOD", "HTTP_VERSION", "IP_VERSION", "MANAGED_RULES", "MITIGATION_PRODUCT", "VERTICAL", "INDUSTRY" ] } }, { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "GET": [ "50.168733" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.attacks.layer7", "x-fern-sdk-method-name": "timeseries-groups-v2", "x-forge-hidden": true } }, "/radar/attacks/layer7/top/ases/origin": { "get": { "operationId": "radar-get-attacks-layer7-top-origin-as", "summary": "Get top origin ASes of layer 7 attacks", "description": "Retrieves the top origin autonomous systems of layer 7 attacks. Values are percentages of the total layer 7 attacks, with the origin autonomous systems determined by the client IP address.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "originAsn": { "type": "string", "example": "55836" }, "originAsnName": { "type": "string", "example": "RELIANCEJIO-IN Reliance Jio Infocomm Limited" }, "rank": { "type": "number", "example": 1 }, "value": { "type": "string", "example": "4.323214" } }, "required": [ "originAsnName", "originAsn", "value", "rank" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.attacks.layer7.top.ases", "x-fern-sdk-method-name": "origin", "x-forge-hidden": true } }, "/radar/attacks/layer7/top/attacks": { "get": { "operationId": "radar-get-attacks-layer7-top-attacks", "summary": "Get top layer 7 attack pairs (origin and target locations)", "description": "Retrieves the top attacks from origin to target location. Values are percentages of the total layer 7 attacks (with billing country). The attack magnitude can be defined by the number of mitigated requests or by the number of zones affected. You can optionally limit the number of attacks by origin/target location (useful if all the top attacks are from or to the same location).", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "limitDirection", "in": "query", "description": "Specifies whether the `limitPerLocation` applies to the source or target location.", "schema": { "description": "Specifies whether the `limitPerLocation` applies to the source or target location.", "type": "string", "example": "ORIGIN", "default": "ORIGIN", "enum": [ "ORIGIN", "TARGET" ] } }, { "name": "limitPerLocation", "in": "query", "description": "Limits the number of attacks per origin/target (refer to `limitDirection` parameter) location.", "schema": { "description": "Limits the number of attacks per origin/target (refer to `limitDirection` parameter) location.", "type": "integer", "example": 10, "default": 10, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN_MAX" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "originCountryAlpha2": { "type": "string", "example": "US" }, "originCountryName": { "type": "string", "example": "United States" }, "targetCountryAlpha2": { "type": "string", "example": "FR" }, "targetCountryName": { "type": "string", "example": "France" }, "value": { "type": "string", "example": "4.323214" } }, "required": [ "originCountryAlpha2", "originCountryName", "targetCountryAlpha2", "targetCountryName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.attacks.layer7.top", "x-fern-sdk-method-name": "attacks", "x-forge-hidden": true } }, "/radar/attacks/layer7/top/industry": { "get": { "operationId": "radar-get-attacks-layer7-top-industries", "summary": "Get top industries targeted by layer 7 attacks", "description": "This endpoint is deprecated. To continue getting this data, switch to the summary by industry endpoint.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Computer Software" }, "value": { "type": "string", "example": "65" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer7.top", "x-fern-sdk-method-name": "industry", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 7 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer7/methods/summary_v2/) instead." } }, "/radar/attacks/layer7/top/locations/origin": { "get": { "operationId": "radar-get-attacks-layer7-top-origin-location", "summary": "Get top origin locations of layer 7 attacks", "description": "Retrieves the top origin locations of layer 7 attacks. Values are percentages of the total layer 7 attacks, with the origin location determined by the client IP address.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "originCountryAlpha2": { "type": "string", "example": "FR" }, "originCountryName": { "type": "string", "example": "France" }, "rank": { "type": "number", "example": 1 }, "value": { "type": "string", "example": "4.323214" } }, "required": [ "originCountryAlpha2", "originCountryName", "value", "rank" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.attacks.layer7.top.locations", "x-fern-sdk-method-name": "origin", "x-forge-hidden": true } }, "/radar/attacks/layer7/top/locations/target": { "get": { "operationId": "radar-get-attacks-layer7-top-target-location", "summary": "Get top target locations of layer 7 attacks", "description": "Retrieves the top target locations of and by layer 7 attacks. Values are a percentage out of the total layer 7 attacks. The target location is determined by the attacked zone's billing country, when available.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "rank": { "type": "number", "example": 1 }, "targetCountryAlpha2": { "type": "string", "example": "FR" }, "targetCountryName": { "type": "string", "example": "France" }, "value": { "type": "string", "example": "4.323214" } }, "required": [ "targetCountryAlpha2", "targetCountryName", "value", "rank" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.attacks.layer7.top.locations", "x-fern-sdk-method-name": "target", "x-forge-hidden": true } }, "/radar/attacks/layer7/top/vertical": { "get": { "operationId": "radar-get-attacks-layer7-top-verticals", "summary": "Get top verticals targeted by layer 7 attacks", "description": "This endpoint is deprecated. To continue getting this data, switch to the summary by vertical endpoint.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "httpMethod", "in": "query", "description": "Filters results by HTTP method.", "schema": { "description": "Filters results by HTTP method.", "type": "array", "items": { "enum": [ "GET", "POST", "DELETE", "PUT", "HEAD", "PURGE", "OPTIONS", "PROPFIND", "MKCOL", "PATCH", "ACL", "BCOPY", "BDELETE", "BMOVE", "BPROPFIND", "BPROPPATCH", "CHECKIN", "CHECKOUT", "CONNECT", "COPY", "LABEL", "LOCK", "MERGE", "MKACTIVITY", "MKWORKSPACE", "MOVE", "NOTIFY", "ORDERPATCH", "POLL", "PROPPATCH", "REPORT", "SEARCH", "SUBSCRIBE", "TRACE", "UNCHECKOUT", "UNLOCK", "UNSUBSCRIBE", "UPDATE", "VERSIONCONTROL", "BASELINECONTROL", "XMSENUMATTS", "RPC_OUT_DATA", "RPC_IN_DATA", "JSON", "COOK", "TRACK" ], "type": "string" }, "example": "GET" } }, { "name": "mitigationProduct", "in": "query", "description": "Filters the results by layer 7 mitigation product.", "schema": { "description": "Filters the results by layer 7 mitigation product.", "type": "array", "items": { "enum": [ "DDOS", "WAF", "BOT_MANAGEMENT", "ACCESS_RULES", "IP_REPUTATION", "API_SHIELD", "DATA_LOSS_PREVENTION" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Internet and Telecom" }, "value": { "type": "string", "example": "65" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Layer 7 Attacks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.attacks.layer7.top", "x-fern-sdk-method-name": "vertical", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Attacks Layer 7 Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/attacks/subresources/layer7/methods/summary_v2/) instead." } }, "/radar/bgp/hijacks/events": { "get": { "operationId": "radar-get-bgp-hijacks-events", "summary": "Get BGP hijack events", "description": "Retrieves the BGP hijack events.", "parameters": [ { "name": "page", "in": "query", "description": "Current page number, starting from 1.", "schema": { "description": "Current page number, starting from 1.", "type": "integer", "default": 1, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "per_page", "in": "query", "description": "Number of entries per page.", "schema": { "description": "Number of entries per page.", "type": "integer", "default": 50, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "eventId", "in": "query", "description": "The unique identifier of a event.", "schema": { "description": "The unique identifier of a event.", "type": "integer" } }, { "name": "hijackerAsn", "in": "query", "description": "The potential hijacker AS of a BGP hijack event.", "schema": { "description": "The potential hijacker AS of a BGP hijack event.", "type": "integer" } }, { "name": "victimAsn", "in": "query", "description": "The potential victim AS of a BGP hijack event.", "schema": { "description": "The potential victim AS of a BGP hijack event.", "type": "integer" } }, { "name": "involvedAsn", "in": "query", "description": "The potential hijacker or victim AS of a BGP hijack event.", "schema": { "description": "The potential hijacker or victim AS of a BGP hijack event.", "type": "integer" } }, { "name": "involvedCountry", "in": "query", "description": "The country code of the potential hijacker or victim AS of a BGP hijack event.", "schema": { "description": "The country code of the potential hijacker or victim AS of a BGP hijack event.", "type": "string", "example": "PT", "maxLength": 2, "minLength": 2 } }, { "name": "prefix", "in": "query", "schema": { "type": "string", "example": "1.1.1.0/24" } }, { "name": "minConfidence", "in": "query", "description": "Filters events by minimum confidence score (1-4 low, 5-7 mid, 8+ high).", "schema": { "description": "Filters events by minimum confidence score (1-4 low, 5-7 mid, 8+ high).", "type": "integer" } }, { "name": "maxConfidence", "in": "query", "description": "Filters events by maximum confidence score (1-4 low, 5-7 mid, 8+ high).", "schema": { "description": "Filters events by maximum confidence score (1-4 low, 5-7 mid, 8+ high).", "type": "integer" } }, { "name": "dateRange", "in": "query", "description": "Filters results by a relative date range ending at the current time. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`), e.g. `7d`. Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `3dcontrol` covers days -10 to -7, `7dcontrol` covers days -14 to -7, `28dcontrol` covers days -56 to -28, and `10dcontrol` covers days -24 to -14). Mutually exclusive with `dateStart`/`dateEnd`.", "schema": { "description": "Filters results by a relative date range ending at the current time. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`), e.g. `7d`. Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `3dcontrol` covers days -10 to -7, `7dcontrol` covers days -14 to -7, `28dcontrol` covers days -56 to -28, and `10dcontrol` covers days -24 to -14). Mutually exclusive with `dateStart`/`dateEnd`.", "type": "string", "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "schema": { "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "sortBy", "in": "query", "description": "Sorts results by the specified field.", "schema": { "description": "Sorts results by the specified field.", "type": "string", "example": "TIME", "enum": [ "ID", "TIME", "CONFIDENCE" ] } }, { "name": "sortOrder", "in": "query", "description": "Sort order.", "schema": { "description": "Sort order.", "type": "string", "example": "desc", "enum": [ "ASC", "DESC" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "asn_info": { "type": "array", "items": { "properties": { "asn": { "type": "integer" }, "country_code": { "type": "string" }, "org_name": { "type": "string" } }, "required": [ "asn", "org_name", "country_code" ], "type": "object" } }, "events": { "type": "array", "items": { "properties": { "confidence_score": { "type": "integer" }, "duration": { "type": "integer" }, "event_type": { "type": "integer" }, "hijack_msgs_count": { "type": "integer" }, "hijacker_asn": { "type": "integer" }, "hijacker_country": { "type": "string" }, "id": { "type": "integer" }, "is_stale": { "type": "boolean" }, "max_hijack_ts": { "type": "string" }, "max_msg_ts": { "type": "string" }, "min_hijack_ts": { "type": "string" }, "on_going_count": { "type": "integer" }, "peer_asns": { "type": "array", "items": { "type": "integer" } }, "peer_ip_count": { "type": "integer" }, "prefixes": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "properties": { "name": { "type": "string" }, "score": { "type": "integer" } }, "required": [ "name", "score" ], "type": "object" } }, "victim_asns": { "type": "array", "items": { "type": "integer" } }, "victim_countries": { "type": "array", "items": { "type": "string" } } }, "required": [ "duration", "event_type", "hijack_msgs_count", "hijacker_asn", "hijacker_country", "victim_asns", "victim_countries", "id", "is_stale", "max_hijack_ts", "min_hijack_ts", "max_msg_ts", "on_going_count", "peer_asns", "peer_ip_count", "prefixes", "confidence_score", "tags" ], "type": "object" } }, "total_monitors": { "type": "integer" } }, "required": [ "asn_info", "events", "total_monitors" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" } }, "required": [ "count", "total_count", "page", "per_page" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "result_info", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.hijacks.events", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/radar/bgp/ips/timeseries": { "get": { "operationId": "radar-get-bgp-ips-timeseries", "summary": "Get announced IP address space time series", "description": "Retrieves time series data for the announced IP space count, represented as the number of IPv4 /24s and IPv6 /48s, for a given ASN.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 location codes.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 location codes.", "type": "array", "items": { "type": "string" }, "example": "US" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "includeDelay", "in": "query", "description": "Includes data delay meta information.", "schema": { "description": "Includes data delay meta information.", "type": "boolean" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "delay": { "type": "object", "properties": { "asn_data": { "type": "object", "properties": { "delaySecs": { "type": "number" }, "delayStr": { "type": "string" }, "healthy": { "type": "boolean" }, "latest": { "type": "object", "properties": { "entries_count": { "type": "number" }, "path": { "type": "string" }, "timestamp": { "type": "number" } }, "required": [ "timestamp", "path", "entries_count" ] } }, "required": [ "delaySecs", "delayStr", "healthy", "latest" ] }, "country_data": { "type": "object", "properties": { "delaySecs": { "type": "number" }, "delayStr": { "type": "string" }, "healthy": { "type": "boolean" }, "latest": { "type": "object", "properties": { "count": { "type": "number" }, "timestamp": { "type": "number" } }, "required": [ "timestamp", "count" ] } }, "required": [ "delaySecs", "delayStr", "healthy", "latest" ] }, "healthy": { "type": "boolean" }, "nowTs": { "type": "number" } }, "required": [ "nowTs", "healthy", "asn_data", "country_data" ] }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "ipv4": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "ipv6": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "ipv4", "ipv6" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.ips", "x-fern-sdk-method-name": "timeseries", "x-forge-hidden": true } }, "/radar/bgp/ips/top/ases": { "get": { "operationId": "radar-get-bgp-ips-top-ases", "summary": "Get top ASes by announced IP space", "description": "Returns the top-N autonomous systems by announced IP space at the nearest 8-hour RIB boundary at or before the requested date. The snapped boundary is returned as `anchor_ts`.", "parameters": [ { "name": "date", "in": "query", "description": "Filters results by the specified datetime (ISO 8601).", "schema": { "description": "Filters results by the specified datetime (ISO 8601).", "type": "string", "format": "date-time", "example": "2024-09-19T00:00:00Z" } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "maximum": 50, "minimum": 1 } }, { "name": "metric", "in": "query", "description": "Ranking metric: IPv4 /24 count or IPv6 /48 count.", "schema": { "description": "Ranking metric: IPv4 /24 count or IPv6 /48 count.", "type": "string", "example": "v4_24s", "enum": [ "v4_24s", "v6_48s" ] } }, { "name": "country", "in": "query", "description": "Optional ISO 3166-1 alpha-2 country filter. Omit for global top-N.", "schema": { "description": "Optional ISO 3166-1 alpha-2 country filter. Omit for global top-N.", "type": "string", "example": "US", "maxLength": 2, "minLength": 2 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "anchorTs": { "type": "string", "format": "date-time", "example": "2026-04-18T16:00:00Z" }, "asns": { "type": "array", "items": { "properties": { "asn": { "type": "integer", "example": 749 }, "v4_24s": { "type": "integer", "example": 875649 }, "v6_48s": { "type": "integer" } }, "required": [ "asn", "v4_24s", "v6_48s" ], "type": "object" } }, "country": { "type": "string", "example": "US", "nullable": true }, "metric": { "type": "string", "example": "v4_24s" } }, "required": [ "anchorTs", "metric", "country", "asns" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.ips.top", "x-fern-sdk-method-name": "ases", "x-forge-hidden": true } }, "/radar/bgp/leaks/events": { "get": { "operationId": "radar-get-bgp-route-leak-events", "summary": "Get BGP route leak events", "description": "Retrieves the BGP route leak events.", "parameters": [ { "name": "page", "in": "query", "description": "Current page number, starting from 1.", "schema": { "description": "Current page number, starting from 1.", "type": "integer", "default": 1, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "per_page", "in": "query", "description": "Number of entries per page.", "schema": { "description": "Number of entries per page.", "type": "integer", "default": 50, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "eventId", "in": "query", "description": "The unique identifier of a event.", "schema": { "description": "The unique identifier of a event.", "type": "integer" } }, { "name": "leakAsn", "in": "query", "description": "The leaking AS of a route leak event.", "schema": { "description": "The leaking AS of a route leak event.", "type": "integer" } }, { "name": "involvedAsn", "in": "query", "description": "ASN that is causing or affected by a route leak event.", "schema": { "description": "ASN that is causing or affected by a route leak event.", "type": "integer" } }, { "name": "involvedCountry", "in": "query", "description": "Country code of a involved ASN in a route leak event.", "schema": { "description": "Country code of a involved ASN in a route leak event.", "type": "string", "example": "PT", "maxLength": 2, "minLength": 2 } }, { "name": "dateRange", "in": "query", "description": "Filters results by a relative date range ending at the current time. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`), e.g. `7d`. Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `3dcontrol` covers days -10 to -7, `7dcontrol` covers days -14 to -7, `28dcontrol` covers days -56 to -28, and `10dcontrol` covers days -24 to -14). Mutually exclusive with `dateStart`/`dateEnd`.", "schema": { "description": "Filters results by a relative date range ending at the current time. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`), e.g. `7d`. Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `3dcontrol` covers days -10 to -7, `7dcontrol` covers days -14 to -7, `28dcontrol` covers days -56 to -28, and `10dcontrol` covers days -24 to -14). Mutually exclusive with `dateStart`/`dateEnd`.", "type": "string", "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "schema": { "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "sortBy", "in": "query", "description": "Sorts results by the specified field.", "schema": { "description": "Sorts results by the specified field.", "type": "string", "example": "TIME", "enum": [ "ID", "LEAKS", "PEERS", "PREFIXES", "ORIGINS", "TIME" ] } }, { "name": "sortOrder", "in": "query", "description": "Sort order.", "schema": { "description": "Sort order.", "type": "string", "example": "desc", "enum": [ "ASC", "DESC" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "asn_info": { "type": "array", "items": { "properties": { "asn": { "type": "integer" }, "country_code": { "type": "string" }, "org_name": { "type": "string" } }, "required": [ "asn", "org_name", "country_code" ], "type": "object" } }, "events": { "type": "array", "items": { "properties": { "countries": { "type": "array", "items": { "type": "string" } }, "detected_ts": { "type": "string" }, "finished": { "type": "boolean" }, "id": { "type": "integer" }, "leak_asn": { "type": "integer" }, "leak_count": { "type": "integer" }, "leak_seg": { "type": "array", "items": { "type": "integer" } }, "leak_type": { "type": "integer" }, "max_ts": { "type": "string" }, "min_ts": { "type": "string" }, "origin_count": { "type": "integer" }, "peer_count": { "type": "integer" }, "prefix_count": { "type": "integer" } }, "required": [ "detected_ts", "finished", "id", "leak_asn", "leak_count", "leak_seg", "leak_type", "max_ts", "min_ts", "origin_count", "peer_count", "prefix_count", "countries" ], "type": "object" } } }, "required": [ "asn_info", "events" ] }, "result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" } }, "required": [ "count", "total_count", "page", "per_page" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "result_info", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.leaks.events", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/radar/bgp/routes/ases": { "get": { "operationId": "radar-get-bgp-routes-asns", "summary": "List ASes from global routing tables", "description": "Retrieves all ASes in the current global routing tables with routing statistics.", "parameters": [ { "name": "location", "in": "query", "description": "Filters results by location. Specify an alpha-2 location code.", "schema": { "description": "Filters results by location. Specify an alpha-2 location code.", "type": "string", "example": "US", "maxLength": 2, "minLength": 2 } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "sortBy", "in": "query", "description": "Sorts results by the specified field.", "schema": { "description": "Sorts results by the specified field.", "type": "string", "example": "ipv4", "enum": [ "cone", "pfxs", "ipv4", "ipv6", "rpki_valid", "rpki_invalid", "rpki_unknown" ] } }, { "name": "sortOrder", "in": "query", "description": "Sort order.", "schema": { "description": "Sort order.", "type": "string", "example": "desc", "enum": [ "ASC", "DESC" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "asns": { "type": "array", "items": { "properties": { "asn": { "type": "integer" }, "coneSize": { "description": "AS's customer cone size.", "type": "integer" }, "country": { "description": "Alpha-2 code for the AS's registration country.", "type": "string", "example": "US" }, "ipv4Count": { "description": "Number of IPv4 addresses originated by the AS.", "type": "integer" }, "ipv6Count": { "description": "Number of IPv6 addresses originated by the AS.", "type": "string", "example": "1.21e24" }, "name": { "description": "Name of the AS.", "type": "string" }, "pfxsCount": { "description": "Number of total IP prefixes originated by the AS.", "type": "integer" }, "rpkiInvalid": { "description": "Number of RPKI invalid prefixes originated by the AS.", "type": "integer" }, "rpkiUnknown": { "description": "Number of RPKI unknown prefixes originated by the AS.", "type": "integer" }, "rpkiValid": { "description": "Number of RPKI valid prefixes originated by the AS.", "type": "integer" } }, "required": [ "asn", "name", "coneSize", "country", "ipv4Count", "ipv6Count", "pfxsCount", "rpkiValid", "rpkiInvalid", "rpkiUnknown" ], "type": "object" } }, "meta": { "type": "object", "properties": { "dataTime": { "description": "The timestamp of when the data is generated.", "type": "string", "example": "2024-06-03T14:00:00" }, "queryTime": { "description": "The timestamp of the query.", "type": "string", "example": "2024-06-03T14:00:00" }, "totalPeers": { "description": "Total number of route collector peers used to generate this data.", "type": "integer" } }, "required": [ "dataTime", "queryTime", "totalPeers" ] } }, "required": [ "asns", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.routes", "x-fern-sdk-method-name": "ases", "x-forge-hidden": true } }, "/radar/bgp/routes/moas": { "get": { "operationId": "radar-get-bgp-pfx2as-moas", "summary": "Get Multi-Origin AS (MOAS) prefixes", "description": "Retrieves all Multi-Origin AS (MOAS) prefixes in the global routing tables.", "parameters": [ { "name": "origin", "in": "query", "description": "Lookup MOASes originated by the given ASN.", "schema": { "description": "Lookup MOASes originated by the given ASN.", "type": "integer" } }, { "name": "prefix", "in": "query", "schema": { "type": "string", "example": "1.1.1.0/24" } }, { "name": "invalid_only", "in": "query", "description": "Lookup only RPKI invalid MOASes.", "schema": { "description": "Lookup only RPKI invalid MOASes.", "type": "boolean" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "data_time": { "type": "string" }, "query_time": { "type": "string" }, "total_peers": { "type": "integer" } }, "required": [ "data_time", "query_time", "total_peers" ] }, "moas": { "type": "array", "items": { "properties": { "origins": { "type": "array", "items": { "properties": { "origin": { "type": "integer" }, "peer_count": { "type": "integer" }, "rpki_validation": { "type": "string" } }, "required": [ "origin", "peer_count", "rpki_validation" ], "type": "object" } }, "prefix": { "type": "string" } }, "required": [ "prefix", "origins" ], "type": "object" } } }, "required": [ "moas", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.routes", "x-fern-sdk-method-name": "moas", "x-forge-hidden": true } }, "/radar/bgp/routes/paths/{asn}": { "get": { "operationId": "radar-get-bgp-routes-paths", "summary": "Get tier-1 path segments for an AS", "description": "Retrieves the paths an AS uses to reach the tier-1 clique, derived from RouteViews RIB snapshots. Each entry is an ordered AS-path segment (from the queried AS toward a tier-1) with the number of observed paths and peers, and the collectors that observed it. By default segments are merged across all active collectors; pass \"collector\" to scope to one. The response also includes an \"asnInfo\" map (keyed by ASN) with the name and country for every ASN in the returned segments plus the queried ASN (best-effort; null when unavailable).", "parameters": [ { "name": "asn", "in": "path", "description": "Single Autonomous System Number (ASN) as integer.", "required": true, "schema": { "description": "Single Autonomous System Number (ASN) as integer.", "type": "integer", "example": 174 } }, { "name": "ipVersion", "in": "query", "description": "Address family of the observed paths. Defaults to IPv4.", "schema": { "description": "Address family of the observed paths. Defaults to IPv4.", "type": "string", "example": "IPv4", "default": "IPv4", "enum": [ "IPv4", "IPv6" ] } }, { "name": "collector", "in": "query", "description": "Scope to a single RouteViews collector (e.g. \"route-views3\"). Omit to merge across all active collectors (identical path segments are deduplicated, observation counts summed, and every contributing collector listed).", "schema": { "description": "Scope to a single RouteViews collector (e.g. \"route-views3\"). Omit to merge across all active collectors (identical path segments are deduplicated, observation counts summed, and every contributing collector listed).", "type": "string", "example": "route-views3", "maxLength": 100 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "asnInfo": { "type": "object", "example": { "13335": { "asn": 13335, "country": "US", "name": "Cloudflare" } }, "additionalProperties": { "properties": { "asn": { "description": "ASN number.", "type": "integer" }, "country": { "description": "Alpha-2 country code.", "type": "string", "nullable": true }, "name": { "description": "AS name.", "type": "string", "nullable": true } }, "required": [ "asn", "name", "country" ], "type": "object" }, "nullable": true }, "collectors": { "type": "array", "items": { "type": "string" } }, "meta": { "type": "object", "properties": { "dataTime": { "description": "Timestamp of the underlying RIB data.", "type": "string", "format": "date-time", "nullable": true }, "effectiveCollector": { "type": "string", "nullable": true }, "queryTime": { "description": "Timestamp when the query was executed.", "type": "string", "format": "date-time", "nullable": true }, "stale": { "type": "boolean" } }, "required": [ "dataTime", "queryTime", "effectiveCollector", "stale" ] }, "paths": { "type": "array", "items": { "properties": { "collectors": { "type": "array", "items": { "type": "string" } }, "pathsCount": { "type": "integer" }, "peersCount": { "type": "integer" }, "segment": { "type": "array", "items": { "type": "integer" } } }, "required": [ "segment", "pathsCount", "peersCount", "collectors" ], "type": "object" } } }, "required": [ "paths", "collectors", "asnInfo", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.routes.paths", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/radar/bgp/routes/pfx2as": { "get": { "operationId": "radar-get-bgp-pfx2as", "summary": "Get prefix-to-ASN mapping", "description": "Retrieves the prefix-to-ASN mapping from global routing tables.", "parameters": [ { "name": "prefix", "in": "query", "schema": { "type": "string", "example": "1.1.1.0/24" } }, { "name": "origin", "in": "query", "description": "Lookup prefixes originated by the given ASN.", "schema": { "description": "Lookup prefixes originated by the given ASN.", "type": "integer" } }, { "name": "rpkiStatus", "in": "query", "description": "Return only results with matching rpki status: valid, invalid or unknown.", "schema": { "description": "Return only results with matching rpki status: valid, invalid or unknown.", "type": "string", "example": "INVALID", "enum": [ "VALID", "INVALID", "UNKNOWN" ] } }, { "name": "longestPrefixMatch", "in": "query", "description": "Return only results with the longest prefix match for the given prefix. For example, specify a /32 prefix to lookup the origin ASN for an IPv4 address.", "schema": { "description": "Return only results with the longest prefix match for the given prefix. For example, specify a /32 prefix to lookup the origin ASN for an IPv4 address.", "type": "boolean", "example": "true" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "data_time": { "type": "string" }, "query_time": { "type": "string" }, "total_peers": { "type": "integer" } }, "required": [ "data_time", "query_time", "total_peers" ] }, "prefix_origins": { "type": "array", "items": { "properties": { "origin": { "type": "integer" }, "peer_count": { "type": "integer" }, "prefix": { "type": "string" }, "rpki_validation": { "type": "string" } }, "required": [ "origin", "peer_count", "prefix", "rpki_validation" ], "type": "object" } } }, "required": [ "prefix_origins", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.routes", "x-fern-sdk-method-name": "pfx2as", "x-forge-hidden": true } }, "/radar/bgp/routes/realtime": { "get": { "operationId": "radar-get-bgp-routes-realtime", "summary": "Get real-time BGP routes for a prefix", "description": "Retrieves real-time BGP routes for a prefix, using public real-time data collectors (RouteViews and RIPE RIS).", "parameters": [ { "name": "prefix", "in": "query", "schema": { "type": "string", "example": "1.1.1.0/24" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "asn_info": { "type": "array", "items": { "properties": { "as_name": { "description": "Name of the autonomous system.", "type": "string" }, "asn": { "description": "AS number.", "type": "integer" }, "country_code": { "description": "Alpha-2 code for the AS's registration country.", "type": "string" }, "org_id": { "description": "Organization ID.", "type": "string" }, "org_name": { "description": "Organization name.", "type": "string" } }, "required": [ "asn", "as_name", "country_code", "org_id", "org_name" ], "type": "object" } }, "collectors": { "type": "array", "items": { "properties": { "collector": { "description": "Public route collector ID.", "type": "string" }, "latest_realtime_ts": { "description": "Latest real-time stream timestamp for this collector.", "type": "string" }, "latest_rib_ts": { "description": "Latest RIB dump MRT file timestamp for this collector.", "type": "string" }, "latest_updates_ts": { "description": "Latest BGP updates MRT file timestamp for this collector.", "type": "string" }, "peers_count": { "description": "Total number of collector peers used from this collector.", "type": "integer" }, "peers_v4_count": { "description": "Total number of collector peers used from this collector for IPv4 prefixes.", "type": "integer" }, "peers_v6_count": { "description": "Total number of collector peers used from this collector for IPv6 prefixes.", "type": "integer" } }, "required": [ "collector", "latest_realtime_ts", "latest_updates_ts", "latest_rib_ts", "peers_count", "peers_v4_count", "peers_v6_count" ], "type": "object" } }, "data_time": { "description": "The most recent data timestamp for from the real-time sources.", "type": "string" }, "prefix_origins": { "type": "array", "items": { "properties": { "origin": { "description": "Origin ASN.", "type": "integer" }, "prefix": { "description": "IP prefix of this query.", "type": "string" }, "rpki_validation": { "description": "Prefix-origin RPKI validation: valid, invalid, unknown.", "type": "string" }, "total_peers": { "description": "Total number of peers.", "type": "integer" }, "total_visible": { "description": "Total number of peers seeing this prefix.", "type": "integer" }, "visibility": { "description": "Ratio of peers seeing this prefix to total number of peers.", "type": "number" } }, "required": [ "origin", "prefix", "rpki_validation", "total_peers", "total_visible", "visibility" ], "type": "object" } }, "query_time": { "description": "The timestamp of this query.", "type": "string" } }, "required": [ "collectors", "asn_info", "prefix_origins", "data_time", "query_time" ] }, "routes": { "type": "array", "items": { "properties": { "as_path": { "description": "AS-level path for this route, from collector to origin.", "type": "array", "items": { "type": "integer" } }, "collector": { "description": "Public collector ID for this route.", "type": "string" }, "communities": { "description": "BGP community values.", "type": "array", "items": { "type": "string" } }, "prefix": { "description": "IP prefix of this query.", "type": "string" }, "timestamp": { "description": "Latest timestamp of change for this route.", "type": "string" } }, "required": [ "timestamp", "collector", "prefix", "as_path", "communities" ], "type": "object" } } }, "required": [ "routes", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.routes", "x-fern-sdk-method-name": "realtime", "x-forge-hidden": true } }, "/radar/bgp/routes/stats": { "get": { "operationId": "radar-get-bgp-routes-stats", "summary": "Get BGP routing table stats ", "description": "Retrieves the BGP routing table stats.", "parameters": [ { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify a single Autonomous System Number (ASN) as integer.", "schema": { "description": "Filters results by Autonomous System. Specify a single Autonomous System Number (ASN) as integer.", "type": "integer", "example": 174 } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify an alpha-2 location code.", "schema": { "description": "Filters results by location. Specify an alpha-2 location code.", "type": "string", "example": "US", "maxLength": 2, "minLength": 2 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "data_time": { "type": "string" }, "query_time": { "type": "string" }, "total_peers": { "type": "integer" } }, "required": [ "data_time", "query_time", "total_peers" ] }, "stats": { "type": "object", "properties": { "distinct_origins": { "type": "integer" }, "distinct_origins_ipv4": { "type": "integer" }, "distinct_origins_ipv6": { "type": "integer" }, "distinct_prefixes": { "type": "integer" }, "distinct_prefixes_ipv4": { "type": "integer" }, "distinct_prefixes_ipv6": { "type": "integer" }, "routes_invalid": { "type": "integer" }, "routes_invalid_ipv4": { "type": "integer" }, "routes_invalid_ipv6": { "type": "integer" }, "routes_total": { "type": "integer" }, "routes_total_ipv4": { "type": "integer" }, "routes_total_ipv6": { "type": "integer" }, "routes_unknown": { "type": "integer" }, "routes_unknown_ipv4": { "type": "integer" }, "routes_unknown_ipv6": { "type": "integer" }, "routes_valid": { "type": "integer" }, "routes_valid_ipv4": { "type": "integer" }, "routes_valid_ipv6": { "type": "integer" } }, "required": [ "distinct_origins", "distinct_origins_ipv4", "distinct_origins_ipv6", "distinct_prefixes", "distinct_prefixes_ipv4", "distinct_prefixes_ipv6", "routes_invalid", "routes_invalid_ipv4", "routes_invalid_ipv6", "routes_total", "routes_total_ipv4", "routes_total_ipv6", "routes_unknown", "routes_unknown_ipv4", "routes_unknown_ipv6", "routes_valid", "routes_valid_ipv4", "routes_valid_ipv6" ] } }, "required": [ "stats", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.routes", "x-fern-sdk-method-name": "stats", "x-forge-hidden": true } }, "/radar/bgp/routes/upstreams/{asn}/timeseries": { "get": { "operationId": "radar-get-bgp-routes-upstreams-timeseries", "summary": "Get upstream composition time series for an AS", "description": "Retrieves the share of an AS’s observed paths carried by each direct upstream over time, derived from RouteViews RIB snapshots across all collectors (the combined product). Each upstream ASN is returned as its own series of shares (0–1); the least-significant upstreams beyond the requested limit are grouped into an \"OTHER\" series. Series share a common set of timestamps.", "parameters": [ { "name": "asn", "in": "path", "description": "Single Autonomous System Number (ASN) as integer.", "required": true, "schema": { "description": "Single Autonomous System Number (ASN) as integer.", "type": "integer", "example": 174 } }, { "name": "ipVersion", "in": "query", "description": "Address family of the observed paths. Defaults to IPv4.", "schema": { "description": "Address family of the observed paths. Defaults to IPv4.", "type": "string", "example": "IPv4", "default": "IPv4", "enum": [ "IPv4", "IPv6" ] } }, { "name": "dateStart", "in": "query", "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "schema": { "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "limit", "in": "query", "description": "Number of upstream ASNs to return as separate series, ranked by the first bucket. Remaining upstreams are grouped into an \"OTHER\" series. Defaults to 5.", "schema": { "description": "Number of upstream ASNs to return as separate series, ranked by the first bucket. Remaining upstreams are grouped into an \"OTHER\" series. Defaults to 5.", "type": "integer", "example": 5 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "dataTime": { "description": "Timestamp of the underlying RIB data.", "type": "string", "format": "date-time", "nullable": true }, "effectiveCollector": { "type": "string", "nullable": true }, "queryTime": { "description": "Timestamp when the query was executed.", "type": "string", "format": "date-time", "nullable": true }, "stale": { "type": "boolean" } }, "required": [ "dataTime", "queryTime", "effectiveCollector", "stale" ] }, "serie_0": { "type": "object", "example": { "174": [ "0.7", "0.6" ], "OTHER": [ "0.1", "0.4" ], "timestamps": [ "2026-06-01T00:00:00Z", "2026-06-01T00:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.routes.upstreams", "x-fern-sdk-method-name": "timeseries", "x-forge-hidden": true } }, "/radar/bgp/rpki/aspa/changes": { "get": { "operationId": "radar-get-bgp-rpki-aspa-changes", "summary": "Get ASPA changes over time", "description": "Retrieves ASPA (Autonomous System Provider Authorization) changes over time. Returns daily aggregated changes including additions, removals, and modifications of ASPA objects.", "parameters": [ { "name": "dateStart", "in": "query", "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "schema": { "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filter changes involving this ASN (as customer or provider).", "schema": { "description": "Filter changes involving this ASN (as customer or provider).", "type": "integer", "example": 13335 } }, { "name": "includeAsnInfo", "in": "query", "description": "Include ASN metadata (name, country) in response.", "schema": { "description": "Include ASN metadata (name, country) in response.", "type": "boolean" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "asnInfo": { "type": "object", "properties": { "13335": { "type": "object", "properties": { "asn": { "description": "ASN number.", "type": "integer" }, "country": { "description": "Alpha-2 country code.", "type": "string" }, "name": { "description": "AS name.", "type": "string" } }, "required": [ "asn", "name", "country" ] } }, "required": [ "13335" ] }, "changes": { "type": "array", "items": { "properties": { "customersAdded": { "description": "Number of new ASPA objects created.", "type": "integer" }, "customersRemoved": { "description": "Number of ASPA objects deleted.", "type": "integer" }, "date": { "description": "Date of the changes in ISO 8601 format.", "type": "string", "format": "date-time" }, "entries": { "type": "array", "items": { "properties": { "customerAsn": { "description": "The customer ASN affected.", "type": "integer" }, "providers": { "type": "array", "items": { "description": "Provider ASNs involved in the change.", "type": "integer" } }, "type": { "type": "string", "enum": [ "CustomerAdded", "CustomerRemoved", "ProvidersAdded", "ProvidersRemoved" ] } }, "required": [ "type", "customerAsn", "providers" ], "type": "object" } }, "providersAdded": { "description": "Number of providers added to existing objects.", "type": "integer" }, "providersRemoved": { "description": "Number of providers removed from existing objects.", "type": "integer" }, "totalCount": { "description": "Running total of active ASPA objects after this day.", "type": "integer" } }, "required": [ "date", "customersAdded", "customersRemoved", "providersAdded", "providersRemoved", "totalCount", "entries" ], "type": "object" } }, "meta": { "type": "object", "properties": { "dataTime": { "description": "Timestamp of the underlying data.", "type": "string", "format": "date-time" }, "queryTime": { "description": "Timestamp when the query was executed.", "type": "string", "format": "date-time" } }, "required": [ "dataTime", "queryTime" ] } }, "required": [ "changes", "asnInfo", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.rpki.aspa", "x-fern-sdk-method-name": "changes", "x-forge-hidden": true } }, "/radar/bgp/rpki/aspa/snapshot": { "get": { "operationId": "radar-get-bgp-rpki-aspa-snapshot", "summary": "Get ASPA objects snapshot", "description": "Retrieves current or historical ASPA (Autonomous System Provider Authorization) objects. ASPA objects define which ASNs are authorized upstream providers for a customer ASN.", "parameters": [ { "name": "customerAsn", "in": "query", "description": "Filter by customer ASN (the ASN publishing the ASPA object).", "schema": { "description": "Filter by customer ASN (the ASN publishing the ASPA object).", "type": "integer", "example": 13335 } }, { "name": "providerAsn", "in": "query", "description": "Filter by provider ASN (an authorized upstream provider in ASPA objects).", "schema": { "description": "Filter by provider ASN (an authorized upstream provider in ASPA objects).", "type": "integer", "example": 174 } }, { "name": "date", "in": "query", "description": "Filters results by the specified datetime (ISO 8601).", "schema": { "description": "Filters results by the specified datetime (ISO 8601).", "type": "string", "format": "date-time", "example": "2024-09-19T00:00:00Z" } }, { "name": "includeAsnInfo", "in": "query", "description": "Include ASN metadata (name, country) in response.", "schema": { "description": "Include ASN metadata (name, country) in response.", "type": "boolean" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "asnInfo": { "type": "object", "properties": { "13335": { "type": "object", "properties": { "asn": { "description": "ASN number.", "type": "integer" }, "country": { "description": "Alpha-2 country code.", "type": "string" }, "name": { "description": "AS name.", "type": "string" } }, "required": [ "asn", "name", "country" ] } }, "required": [ "13335" ] }, "aspaObjects": { "type": "array", "items": { "properties": { "customerAsn": { "description": "The customer ASN publishing the ASPA object.", "type": "integer" }, "providers": { "type": "array", "items": { "description": "Authorized provider ASNs.", "type": "integer" } } }, "required": [ "customerAsn", "providers" ], "type": "object" } }, "meta": { "type": "object", "properties": { "dataTime": { "description": "Timestamp of the underlying data.", "type": "string", "format": "date-time" }, "queryTime": { "description": "Timestamp when the query was executed.", "type": "string", "format": "date-time" }, "totalCount": { "description": "Total number of ASPA objects.", "type": "integer" } }, "required": [ "dataTime", "queryTime", "totalCount" ] } }, "required": [ "aspaObjects", "asnInfo", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.rpki.aspa", "x-fern-sdk-method-name": "snapshot", "x-forge-hidden": true } }, "/radar/bgp/rpki/aspa/timeseries": { "get": { "operationId": "radar-get-bgp-rpki-aspa-timeseries", "summary": "Get ASPA count time series", "description": "Retrieves ASPA (Autonomous System Provider Authorization) object count over time. Supports filtering by RIR or location (country code) to generate multiple named series. If no RIR or location filter is specified, returns total count.", "parameters": [ { "name": "dateStart", "in": "query", "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "schema": { "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "rir", "in": "query", "description": "Filter by Regional Internet Registry (RIR). Multiple RIRs generate multiple series.", "schema": { "description": "Filter by Regional Internet Registry (RIR). Multiple RIRs generate multiple series.", "type": "array", "items": { "enum": [ "RIPE_NCC", "ARIN", "APNIC", "LACNIC", "AFRINIC" ], "type": "string" }, "example": "RIPE_NCC" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 location codes.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 location codes.", "type": "array", "items": { "type": "string" }, "example": "US" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "dataTime": { "description": "Timestamp of the underlying data.", "type": "string", "format": "date-time" }, "queryTime": { "description": "Timestamp when the query was executed.", "type": "string", "format": "date-time" } }, "required": [ "dataTime", "queryTime" ] }, "serie_0": { "type": "object", "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } }, "values": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "timestamps", "values" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.rpki.aspa", "x-fern-sdk-method-name": "timeseries", "x-forge-hidden": true } }, "/radar/bgp/rpki/roas/timeseries": { "get": { "operationId": "radar-get-bgp-rpki-roas-timeseries", "summary": "Get RPKI ROA deployment time series", "description": "Retrieves RPKI ROA (Route Origin Authorization) validation ratios over time. Returns the selected metric as a time series. Supports filtering by ASN or location (country code) — multiple values of the same filter type produce one series per value. If no ASN or location is specified, returns the global aggregate.", "parameters": [ { "name": "dateStart", "in": "query", "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "schema": { "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "metric", "in": "query", "description": "Which RPKI ROA validation metric to return. validPfxsRatio = ratio of RPKI-valid prefixes (IPv4+IPv6 combined). validPfxsV4Ratio / validPfxsV6Ratio = same, split by IP version. validIpsRatio = ratio of RPKI-valid address space (IPv4 /24s + IPv6 /48s). validIpsV4Ratio / validIpsV6Ratio = same, split by IP version.", "schema": { "description": "Which RPKI ROA validation metric to return. validPfxsRatio = ratio of RPKI-valid prefixes (IPv4+IPv6 combined). validPfxsV4Ratio / validPfxsV6Ratio = same, split by IP version. validIpsRatio = ratio of RPKI-valid address space (IPv4 /24s + IPv6 /48s). validIpsV4Ratio / validIpsV6Ratio = same, split by IP version.", "type": "string", "example": "validPfxsRatio", "default": "validPfxsRatio", "enum": [ "validPfxsRatio", "validPfxsV4Ratio", "validPfxsV6Ratio", "validIpsRatio", "validIpsV4Ratio", "validIpsV6Ratio" ] } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System Number. Specify one or more ASNs. Multiple values generate one series per ASN.", "schema": { "description": "Filters results by Autonomous System Number. Specify one or more ASNs. Multiple values generate one series per ASN.", "type": "array", "items": { "type": "string" }, "example": "13335" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 location codes.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 location codes.", "type": "array", "items": { "type": "string" }, "example": "US" } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "dataTime": { "description": "Timestamp of the underlying data.", "type": "string", "format": "date-time" }, "queryTime": { "description": "Timestamp when the query was executed.", "type": "string", "format": "date-time" } }, "required": [ "dataTime", "queryTime" ] }, "serie_0": { "type": "object", "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } }, "values": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "timestamps", "values" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.rpki.roas", "x-fern-sdk-method-name": "timeseries", "x-forge-hidden": true } }, "/radar/bgp/timeseries": { "get": { "operationId": "radar-get-bgp-timeseries", "summary": "Get BGP time series", "description": "Retrieves BGP updates over time. When requesting updates for an autonomous system, only BGP updates of type announcement are returned.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "prefix", "in": "query", "description": "Filters results by BGP network prefix.", "schema": { "description": "Filters results by BGP network prefix.", "type": "array", "items": { "type": "string" }, "example": "1.1.1.0/24" } }, { "name": "updateType", "in": "query", "description": "Filters results by BGP update type.", "schema": { "description": "Filters results by BGP update type.", "type": "array", "items": { "enum": [ "ANNOUNCEMENT", "WITHDRAWAL" ], "type": "string" }, "example": "ANNOUNCEMENT" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "aggInterval": { "type": "string", "enum": [ "15m", "1h", "1d", "1w" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "type": "string", "format": "date-time" } }, "required": [ "confidenceInfo", "dateRange", "aggInterval", "lastUpdated" ] }, "serie_0": { "type": "object", "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } }, "values": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "timestamps", "values" ] } }, "required": [ "meta", "serie_0" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp", "x-fern-sdk-method-name": "timeseries", "x-forge-hidden": true } }, "/radar/bgp/top/ases": { "get": { "operationId": "radar-get-bgp-top-ases", "summary": "Get top ASes by BGP updates", "description": "Retrieves the top autonomous systems by BGP updates (announcements only).", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "prefix", "in": "query", "description": "Filters results by BGP network prefix.", "schema": { "description": "Filters results by BGP network prefix.", "type": "array", "items": { "type": "string" }, "example": "1.1.1.0/24" } }, { "name": "updateType", "in": "query", "description": "Filters results by BGP update type.", "schema": { "description": "Filters results by BGP update type.", "type": "array", "items": { "enum": [ "ANNOUNCEMENT", "WITHDRAWAL" ], "type": "string" }, "example": "ANNOUNCEMENT" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } } }, "required": [ "dateRange" ] }, "top_0": { "type": "array", "items": { "properties": { "ASName": { "type": "string", "example": "Apple-Engineering" }, "asn": { "type": "integer", "example": 714 }, "value": { "description": "Percentage of updates by this AS out of the total updates by all autonomous systems.", "type": "string", "example": "0.73996" } }, "required": [ "asn", "ASName", "value" ], "type": "object" } } }, "required": [ "meta", "top_0" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.top.ases", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/bgp/top/ases/prefixes": { "get": { "operationId": "radar-get-bgp-top-asns-by-prefixes", "summary": "Get top ASes by prefix count", "description": "Retrieves the full list of autonomous systems on the global routing table ordered by announced prefixes count. The data comes from public BGP MRT data archives and updates every 2 hours.", "parameters": [ { "name": "country", "in": "query", "description": "Alpha-2 country code.", "schema": { "description": "Alpha-2 country code.", "type": "string", "example": "NZ" } }, { "name": "limit", "in": "query", "description": "Maximum number of ASes to return.", "schema": { "description": "Maximum number of ASes to return.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "asns": { "type": "array", "items": { "properties": { "asn": { "type": "integer" }, "country": { "type": "string" }, "name": { "type": "string" }, "pfxs_count": { "type": "integer" } }, "required": [ "asn", "country", "name", "pfxs_count" ], "type": "object" } }, "meta": { "type": "object", "properties": { "data_time": { "type": "string" }, "query_time": { "type": "string" }, "total_peers": { "type": "integer" } }, "required": [ "data_time", "query_time", "total_peers" ] } }, "required": [ "asns", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.top.ases", "x-fern-sdk-method-name": "prefixes", "x-forge-hidden": true } }, "/radar/bgp/top/prefixes": { "get": { "operationId": "radar-get-bgp-top-prefixes", "summary": "Get top prefixes by BGP updates", "description": "Retrieves the top network prefixes by BGP updates.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "updateType", "in": "query", "description": "Filters results by BGP update type.", "schema": { "description": "Filters results by BGP update type.", "type": "array", "items": { "enum": [ "ANNOUNCEMENT", "WITHDRAWAL" ], "type": "string" }, "example": "ANNOUNCEMENT" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } } }, "required": [ "dateRange" ] }, "top_0": { "type": "array", "items": { "properties": { "prefix": { "type": "string", "example": "2804:77cc:8000::/33" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "prefix", "value" ], "type": "object" } } }, "required": [ "meta", "top_0" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar BGP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bgp.top", "x-fern-sdk-method-name": "prefixes", "x-forge-hidden": true } }, "/radar/bots": { "get": { "operationId": "radar-get-bots", "summary": "List bots", "description": "Retrieves a list of bots.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Skips the specified number of objects before fetching the results.", "schema": { "description": "Skips the specified number of objects before fetching the results.", "type": "integer", "minimum": 0 } }, { "name": "botCategory", "in": "query", "description": "Filters results by bot category.", "schema": { "description": "Filters results by bot category.", "type": "string", "enum": [ "SEARCH_ENGINE_CRAWLER", "SEARCH_ENGINE_OPTIMIZATION", "MONITORING_AND_ANALYTICS", "ADVERTISING_AND_MARKETING", "SOCIAL_MEDIA_MARKETING", "PAGE_PREVIEW", "ACADEMIC_RESEARCH", "SECURITY", "ACCESSIBILITY", "WEBHOOKS", "FEED_FETCHER", "AI_CRAWLER", "AGGREGATOR", "AI_ASSISTANT", "AI_SEARCH", "ARCHIVER" ] } }, { "name": "botOperator", "in": "query", "description": "Filters results by bot operator.", "schema": { "description": "Filters results by bot operator.", "type": "string", "maxLength": 100 } }, { "name": "kind", "in": "query", "description": "Filters results by bot kind. Deprecated: the Verified Bot / Signed Agent distinction is being removed.", "schema": { "description": "Filters results by bot kind. Deprecated: the Verified Bot / Signed Agent distinction is being removed.", "type": "string", "enum": [ "AGENT", "BOT" ] }, "deprecated": true }, { "name": "botVerificationStatus", "in": "query", "description": "Filters results by bot verification status.", "schema": { "description": "Filters results by bot verification status.", "type": "string", "enum": [ "VERIFIED" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "bots": { "type": "array", "items": { "properties": { "category": { "description": "The category of the bot.", "type": "string", "example": "AI_CRAWLER" }, "description": { "description": "A summary for the bot (e.g., purpose).", "type": "string", "example": "OpenAI/ChatGPT's web crawler" }, "kind": { "description": "The kind of the bot.", "type": "string", "example": "AGENT", "deprecated": true }, "name": { "description": "The name of the bot.", "type": "string", "example": "GPTBot" }, "operator": { "description": "The organization that owns and operates the bot.", "type": "string", "example": "OpenAI" }, "slug": { "description": "A kebab-case identifier derived from the bot name.", "type": "string", "example": "gptbot" }, "userAgentPatterns": { "type": "array", "items": { "description": "User agent patterns that identify the bot in web traffic.", "example": "GPTBot", "type": "string" } } }, "required": [ "slug", "name", "description", "kind", "operator", "category", "userAgentPatterns" ], "type": "object" } } }, "required": [ "bots" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Bots" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bots", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/radar/bots/crawlers/summary/{dimension}": { "get": { "operationId": "radar-get-crawlers-summary", "summary": "Get crawler HTTP request distribution by dimension", "description": "Retrieves an aggregated summary of HTTP requests from crawlers, grouped by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "CLIENT_TYPE", "USER_AGENT", "REFERER", "CRAWL_REFER_RATIO", "VERTICAL", "INDUSTRY", "RESPONSE_STATUS", "RESPONSE_STATUS_CATEGORY" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "botOperator", "in": "query", "description": "Filters results by bot operator.", "schema": { "description": "Filters results by bot operator.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "vertical", "in": "query", "description": "Filters results by vertical.", "schema": { "description": "Filters results by vertical.", "type": "array", "items": { "maxLength": 2000, "type": "string" } } }, { "name": "industry", "in": "query", "description": "Filters results by industry.", "schema": { "description": "Filters results by industry.", "type": "array", "items": { "maxLength": 2000, "type": "string" } } }, { "name": "clientType", "in": "query", "description": "Filters results by agent type.", "schema": { "description": "Filters results by agent type.", "type": "array", "items": { "description": "The type of the client.", "enum": [ "HUMAN", "NON_AI_BOT", "AI_BOT", "MIXED_PURPOSE" ], "type": "string" } } }, { "name": "responseStatus", "in": "query", "description": "Filters results by HTTP response status code (e.g. 200, 403, 404). Only [IANA-registered codes](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) are accepted.", "schema": { "description": "Filters results by HTTP response status code (e.g. 200, 403, 404). Only [IANA-registered codes](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) are accepted.", "type": "array", "items": { "pattern": "^\\d{3}$", "type": "string" } } }, { "name": "responseStatusCategory", "in": "query", "description": "Filters results by HTTP response status code category.", "schema": { "description": "Filters results by HTTP response status code category.", "type": "array", "items": { "enum": [ "INFORMATIONAL", "SUCCESS", "REDIRECTION", "CLIENT_ERROR", "SERVER_ERROR" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "Claude": "63.40249", "DuckDuckGo": "10.274394", "Google": "8.381743" }, "additionalProperties": { "description": "A numeric string that can include decimals and infinity values.", "example": "10.5", "pattern": "^-?(?:\\d+(?:\\.\\d+)?|inf)$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Web Crawlers" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bots.web-crawlers", "x-fern-sdk-method-name": "summary", "x-forge-hidden": true } }, "/radar/bots/crawlers/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-crawlers-timeseries-group", "summary": "Get time series of crawler HTTP request distribution by dimension", "description": "Retrieves the distribution of HTTP requests from crawlers, grouped by the specified dimension over time.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "CLIENT_TYPE", "USER_AGENT", "REFERER", "CRAWL_REFER_RATIO", "VERTICAL", "INDUSTRY", "RESPONSE_STATUS", "RESPONSE_STATUS_CATEGORY" ] } }, { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `PERCENTAGE_CHANGE` requires exactly one comparison series (e.g. a `control` date range).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `PERCENTAGE_CHANGE` requires exactly one comparison series (e.g. a `control` date range).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX", "PERCENTAGE_CHANGE" ] } }, { "name": "botOperator", "in": "query", "description": "Filters results by bot operator.", "schema": { "description": "Filters results by bot operator.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "vertical", "in": "query", "description": "Filters results by vertical.", "schema": { "description": "Filters results by vertical.", "type": "array", "items": { "maxLength": 2000, "type": "string" } } }, { "name": "industry", "in": "query", "description": "Filters results by industry.", "schema": { "description": "Filters results by industry.", "type": "array", "items": { "maxLength": 2000, "type": "string" } } }, { "name": "clientType", "in": "query", "description": "Filters results by agent type.", "schema": { "description": "Filters results by agent type.", "type": "array", "items": { "description": "The type of the client.", "enum": [ "HUMAN", "NON_AI_BOT", "AI_BOT", "MIXED_PURPOSE" ], "type": "string" } } }, { "name": "responseStatus", "in": "query", "description": "Filters results by HTTP response status code (e.g. 200, 403, 404). Only [IANA-registered codes](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) are accepted.", "schema": { "description": "Filters results by HTTP response status code (e.g. 200, 403, 404). Only [IANA-registered codes](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) are accepted.", "type": "array", "items": { "pattern": "^\\d{3}$", "type": "string" } } }, { "name": "responseStatusCategory", "in": "query", "description": "Filters results by HTTP response status code category.", "schema": { "description": "Filters results by HTTP response status code category.", "type": "array", "items": { "enum": [ "INFORMATIONAL", "SUCCESS", "REDIRECTION", "CLIENT_ERROR", "SERVER_ERROR" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "Claude": [ "63.40249" ], "DuckDuckGo": [ "10.274394" ], "Google": [ "8.381743" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string that can include decimals and infinity values.", "example": "10.5", "pattern": "^-?(?:\\d+(?:\\.\\d+)?|inf)$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Web Crawlers" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bots.web-crawlers", "x-fern-sdk-method-name": "timeseries-groups", "x-forge-hidden": true } }, "/radar/bots/summary/{dimension}": { "get": { "operationId": "radar-get-bots-summary", "summary": "Get bots HTTP requests distribution by dimension", "description": "Retrieves an aggregated summary of bots HTTP requests grouped by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "BOT", "BOT_KIND", "BOT_OPERATOR", "BOT_CATEGORY" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "bot", "in": "query", "description": "Filters results by bot name.", "schema": { "description": "Filters results by bot name.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "botOperator", "in": "query", "description": "Filters results by bot operator.", "schema": { "description": "Filters results by bot operator.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "botCategory", "in": "query", "description": "Filters results by bot category.", "schema": { "description": "Filters results by bot category.", "type": "array", "items": { "description": "The category of the bot.", "enum": [ "SEARCH_ENGINE_CRAWLER", "SEARCH_ENGINE_OPTIMIZATION", "MONITORING_AND_ANALYTICS", "ADVERTISING_AND_MARKETING", "SOCIAL_MEDIA_MARKETING", "PAGE_PREVIEW", "ACADEMIC_RESEARCH", "SECURITY", "ACCESSIBILITY", "WEBHOOKS", "FEED_FETCHER", "AI_CRAWLER", "AGGREGATOR", "AI_ASSISTANT", "AI_SEARCH", "ARCHIVER" ], "type": "string" } } }, { "name": "botKind", "in": "query", "description": "Filters results by bot kind. Deprecated: the Verified Bot / Signed Agent distinction is being removed.", "schema": { "description": "Filters results by bot kind. Deprecated: the Verified Bot / Signed Agent distinction is being removed.", "type": "array", "items": { "enum": [ "AGENT", "BOT" ], "type": "string" } }, "deprecated": true }, { "name": "botVerificationStatus", "in": "query", "description": "Filters results by bot verification status (Verified vs. Unverified).", "schema": { "description": "Filters results by bot verification status (Verified vs. Unverified).", "type": "array", "items": { "description": "The category of the bot.", "enum": [ "VERIFIED" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "Facebook": "10.274394", "GPTBot": "63.40249", "GoogleBot": "8.381743" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Bots" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bots", "x-fern-sdk-method-name": "summary", "x-forge-hidden": true } }, "/radar/bots/timeseries": { "get": { "operationId": "radar-get-bots-timeseries", "summary": "Get bots HTTP requests time series", "description": "Retrieves bots HTTP request volume over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "bot", "in": "query", "description": "Filters results by bot name.", "schema": { "description": "Filters results by bot name.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "botOperator", "in": "query", "description": "Filters results by bot operator.", "schema": { "description": "Filters results by bot operator.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "botCategory", "in": "query", "description": "Filters results by bot category.", "schema": { "description": "Filters results by bot category.", "type": "array", "items": { "description": "The category of the bot.", "enum": [ "SEARCH_ENGINE_CRAWLER", "SEARCH_ENGINE_OPTIMIZATION", "MONITORING_AND_ANALYTICS", "ADVERTISING_AND_MARKETING", "SOCIAL_MEDIA_MARKETING", "PAGE_PREVIEW", "ACADEMIC_RESEARCH", "SECURITY", "ACCESSIBILITY", "WEBHOOKS", "FEED_FETCHER", "AI_CRAWLER", "AGGREGATOR", "AI_ASSISTANT", "AI_SEARCH", "ARCHIVER" ], "type": "string" } } }, { "name": "botKind", "in": "query", "description": "Filters results by bot kind. Deprecated: the Verified Bot / Signed Agent distinction is being removed.", "schema": { "description": "Filters results by bot kind. Deprecated: the Verified Bot / Signed Agent distinction is being removed.", "type": "array", "items": { "enum": [ "AGENT", "BOT" ], "type": "string" } }, "deprecated": true }, { "name": "botVerificationStatus", "in": "query", "description": "Filters results by bot verification status (Verified vs. Unverified).", "schema": { "description": "Filters results by bot verification status (Verified vs. Unverified).", "type": "array", "items": { "description": "The category of the bot.", "enum": [ "VERIFIED" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "additionalProperties": { "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } }, "values": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "timestamps", "values" ], "type": "object" }, "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] } }, "required": [ "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Bots" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bots", "x-fern-sdk-method-name": "timeseries", "x-forge-hidden": true } }, "/radar/bots/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-bots-timeseries-group", "summary": "Get time series distribution of bots HTTP requests by dimension.", "description": "Retrieves the distribution of HTTP requests from bots, grouped by the specified dimension over time.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "BOT", "BOT_KIND", "BOT_OPERATOR", "BOT_CATEGORY" ] } }, { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "bot", "in": "query", "description": "Filters results by bot name.", "schema": { "description": "Filters results by bot name.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "botOperator", "in": "query", "description": "Filters results by bot operator.", "schema": { "description": "Filters results by bot operator.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "botCategory", "in": "query", "description": "Filters results by bot category.", "schema": { "description": "Filters results by bot category.", "type": "array", "items": { "description": "The category of the bot.", "enum": [ "SEARCH_ENGINE_CRAWLER", "SEARCH_ENGINE_OPTIMIZATION", "MONITORING_AND_ANALYTICS", "ADVERTISING_AND_MARKETING", "SOCIAL_MEDIA_MARKETING", "PAGE_PREVIEW", "ACADEMIC_RESEARCH", "SECURITY", "ACCESSIBILITY", "WEBHOOKS", "FEED_FETCHER", "AI_CRAWLER", "AGGREGATOR", "AI_ASSISTANT", "AI_SEARCH", "ARCHIVER" ], "type": "string" } } }, { "name": "botKind", "in": "query", "description": "Filters results by bot kind. Deprecated: the Verified Bot / Signed Agent distinction is being removed.", "schema": { "description": "Filters results by bot kind. Deprecated: the Verified Bot / Signed Agent distinction is being removed.", "type": "array", "items": { "enum": [ "AGENT", "BOT" ], "type": "string" } }, "deprecated": true }, { "name": "botVerificationStatus", "in": "query", "description": "Filters results by bot verification status (Verified vs. Unverified).", "schema": { "description": "Filters results by bot verification status (Verified vs. Unverified).", "type": "array", "items": { "description": "The category of the bot.", "enum": [ "VERIFIED" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "Facebook": [ "10.274394" ], "GPTBot": [ "63.40249" ], "GoogleBot": [ "8.381743" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Bots" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bots", "x-fern-sdk-method-name": "timeseries-groups", "x-forge-hidden": true } }, "/radar/bots/{bot_slug}": { "get": { "operationId": "radar-get-bot-details", "summary": "Get bot details", "description": "Retrieves the requested bot information.", "parameters": [ { "name": "bot_slug", "in": "path", "description": "Bot slug.", "required": true, "schema": { "description": "Bot slug.", "type": "string", "example": "gptbot", "maxLength": 100 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "bot": { "type": "object", "properties": { "category": { "description": "The category of the bot.", "type": "string", "example": "AI_CRAWLER" }, "description": { "description": "A summary for the bot (e.g., purpose).", "type": "string", "example": "OpenAI/ChatGPT's web crawler" }, "kind": { "description": "The kind of the bot.", "type": "string", "example": "AGENT", "deprecated": true }, "name": { "description": "The name of the bot.", "type": "string", "example": "GPTBot" }, "operator": { "description": "The organization that owns and operates the bot.", "type": "string", "example": "OpenAI" }, "operatorUrl": { "description": "The link to the bot documentation.", "type": "string", "example": "https://platform.openai.com/docs/bots" }, "signatureAgentUrl": { "description": "The URL of the agent's [Web Bot Auth](https://blog.cloudflare.com/web-bot-auth/) resource. Null for bots not verified via request signature.", "type": "string", "example": "https://example.com/signature-agent", "nullable": true }, "slug": { "description": "A kebab-case identifier derived from the bot name.", "type": "string", "example": "gptbot" }, "userAgentPatterns": { "type": "array", "items": { "description": "User agent patterns that identify the bot in web traffic.", "example": "GPTBot", "type": "string" } }, "userAgents": { "type": "array", "items": { "description": "User agent strings used by this bot in HTTP requests.", "example": "GPTBot", "type": "string" } } }, "required": [ "slug", "name", "description", "kind", "operator", "operatorUrl", "category", "userAgents", "userAgentPatterns" ] } }, "required": [ "bot" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Bots" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.bots", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/ct/authorities": { "get": { "operationId": "radar-get-certificate-authorities", "summary": "List certificate authorities", "description": "Retrieves a list of certificate authorities.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Skips the specified number of objects before fetching the results.", "schema": { "description": "Skips the specified number of objects before fetching the results.", "type": "integer", "minimum": 0 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "certificateAuthorities": { "type": "array", "items": { "properties": { "certificateRecordType": { "description": "Specifies the type of certificate in the trust chain.", "type": "string", "enum": [ "ROOT_CERTIFICATE", "INTERMEDIATE_CERTIFICATE" ] }, "country": { "description": "The two-letter ISO country code where the CA organization is based.", "type": "string", "example": "PT" }, "countryName": { "description": "The full country name corresponding to the country code.", "type": "string", "example": "Portugal" }, "name": { "description": "The full name of the certificate authority (CA).", "type": "string", "example": "MULTICERT Advanced Certification Authority 005" }, "owner": { "description": "The organization that owns and operates the CA.", "type": "string", "example": "MULTICERT" }, "parentName": { "description": "The name of the parent/root certificate authority that issued this intermediate certificate.", "type": "string", "example": "MULTICERT Root Certification Authority 01" }, "parentSha256Fingerprint": { "description": "The SHA-256 fingerprint of the parent certificate.", "type": "string", "example": "24EDD4E503A8D3FDB5FFB4AF66C887359901CBE687A5A0760D10A08EED99A7C3" }, "revocationStatus": { "description": "The current revocation status of a Certificate Authority (CA) certificate.", "type": "string", "enum": [ "NOT_REVOKED", "REVOKED", "PARENT_CERT_REVOKED" ] }, "sha256Fingerprint": { "description": "The SHA-256 fingerprint of the intermediate certificate.", "type": "string", "example": "24EDD4E503A8D3FDB5FFB4AF66C887359901CBE687A5A0760D10A08EED99A7C3" } }, "required": [ "sha256Fingerprint", "name", "owner", "parentName", "parentSha256Fingerprint", "certificateRecordType", "country", "countryName", "revocationStatus" ], "type": "object" } } }, "required": [ "certificateAuthorities" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Certificate Transparency" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ct.authorities", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/radar/ct/authorities/{ca_slug}": { "get": { "operationId": "radar-get-certificate-authority-details", "summary": "Get certificate authority details", "description": "Retrieves the requested CA information.", "parameters": [ { "name": "ca_slug", "in": "path", "description": "Certificate authority SHA256 fingerprint.", "required": true, "schema": { "description": "Certificate authority SHA256 fingerprint.", "type": "string", "example": "24EDD4E503A8D3FDB5FFB4AF66C887359901CBE687A5A0760D10A08EED99A7C3", "pattern": "^[A-F0-9]{64}$" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "certificateAuthority": { "type": "object", "properties": { "appleStatus": { "description": "The inclusion status of a Certificate Authority (CA) in the trust store.", "type": "string", "enum": [ "INCLUDED", "NOT_YET_INCLUDED", "NOT_INCLUDED", "NOT_BEFORE", "REMOVED", "DISABLED", "BLOCKED" ] }, "authorityKeyIdentifier": { "description": "The authorityKeyIdentifier value extracted from the certificate PEM.", "type": "string", "example": "1TkcnFtvBKqilUzvIN0pdKTFRXE" }, "certificateRecordType": { "description": "Specifies the type of certificate in the trust chain.", "type": "string", "enum": [ "ROOT_CERTIFICATE", "INTERMEDIATE_CERTIFICATE" ] }, "chromeStatus": { "description": "The inclusion status of a Certificate Authority (CA) in the trust store.", "type": "string", "enum": [ "INCLUDED", "NOT_YET_INCLUDED", "NOT_INCLUDED", "NOT_BEFORE", "REMOVED", "DISABLED", "BLOCKED" ] }, "country": { "description": "The two-letter ISO country code where the CA organization is based.", "type": "string", "example": "PT" }, "countryName": { "description": "The full country name corresponding to the country code.", "type": "string", "example": "Portugal" }, "microsoftStatus": { "description": "The inclusion status of a Certificate Authority (CA) in the trust store.", "type": "string", "enum": [ "INCLUDED", "NOT_YET_INCLUDED", "NOT_INCLUDED", "NOT_BEFORE", "REMOVED", "DISABLED", "BLOCKED" ] }, "mozillaStatus": { "description": "The inclusion status of a Certificate Authority (CA) in the trust store.", "type": "string", "enum": [ "INCLUDED", "NOT_YET_INCLUDED", "NOT_INCLUDED", "NOT_BEFORE", "REMOVED", "DISABLED", "BLOCKED" ] }, "name": { "description": "The full name of the certificate authority (CA).", "type": "string", "example": "MULTICERT Advanced Certification Authority 005" }, "owner": { "description": "The organization that owns and operates the CA.", "type": "string", "example": "MULTICERT" }, "parentName": { "description": "The name of the parent/root certificate authority that issued this intermediate certificate.", "type": "string", "example": "MULTICERT Root Certification Authority 01" }, "parentSha256Fingerprint": { "description": "The SHA-256 fingerprint of the parent certificate.", "type": "string", "example": "604D32D036895AED3BFEFAEB727C009EC0F2B3CDFA42A1C71730E6A72C3BE9D4" }, "related": { "description": "CAs from the same owner.", "type": "array", "items": { "properties": { "certificateRecordType": { "description": "Specifies the type of certificate in the trust chain.", "type": "string", "enum": [ "ROOT_CERTIFICATE", "INTERMEDIATE_CERTIFICATE" ] }, "name": { "description": "The full name of the certificate authority (CA).", "type": "string", "example": "MULTICERT Advanced Certification Authority 005" }, "revocationStatus": { "description": "The current revocation status of a Certificate Authority (CA) certificate.", "type": "string", "enum": [ "NOT_REVOKED", "REVOKED", "PARENT_CERT_REVOKED" ] }, "sha256Fingerprint": { "description": "The SHA-256 fingerprint of the intermediate certificate.", "type": "string", "example": "24EDD4E503A8D3FDB5FFB4AF66C887359901CBE687A5A0760D10A08EED99A7C3" } }, "required": [ "sha256Fingerprint", "name", "revocationStatus", "certificateRecordType" ], "type": "object" } }, "revocationStatus": { "description": "The current revocation status of a Certificate Authority (CA) certificate.", "type": "string", "enum": [ "NOT_REVOKED", "REVOKED", "PARENT_CERT_REVOKED" ] }, "sha256Fingerprint": { "description": "The SHA-256 fingerprint of the intermediate certificate.", "type": "string", "example": "24EDD4E503A8D3FDB5FFB4AF66C887359901CBE687A5A0760D10A08EED99A7C3" }, "subjectKeyIdentifier": { "description": "The subjectKeyIdentifier value extracted from the certificate PEM.", "type": "string", "example": "VbqXmCURhMmiMtD7nFY6iCr4z" }, "validFrom": { "description": "The start date of the certificate’s validity period (ISO format).", "type": "string", "example": "2019-12-09T00:00:00Z" }, "validTo": { "description": "The end date of the certificate’s validity period (ISO format).", "type": "string", "example": "2032-06-08T00:00:00Z" } }, "required": [ "sha256Fingerprint", "name", "owner", "parentName", "parentSha256Fingerprint", "certificateRecordType", "country", "countryName", "chromeStatus", "appleStatus", "microsoftStatus", "mozillaStatus", "revocationStatus", "validFrom", "validTo", "authorityKeyIdentifier", "subjectKeyIdentifier", "related" ] } }, "required": [ "certificateAuthority" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Certificate Transparency" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ct.authorities", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/ct/logs": { "get": { "operationId": "radar-get-certificate-logs", "summary": "List certificate logs", "description": "Retrieves a list of certificate logs.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Skips the specified number of objects before fetching the results.", "schema": { "description": "Skips the specified number of objects before fetching the results.", "type": "integer", "minimum": 0 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "certificateLogs": { "type": "array", "items": { "properties": { "api": { "description": "The API standard that the certificate log follows.", "type": "string", "enum": [ "RFC6962", "STATIC" ] }, "description": { "description": "A brief description of the certificate log.", "type": "string", "example": "Google 'Argon2024' log" }, "endExclusive": { "description": "The end date and time for when the log will stop accepting certificates.", "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z" }, "operator": { "description": "The organization responsible for operating the certificate log.", "type": "string", "example": "Google" }, "slug": { "description": "A URL-friendly, kebab-case identifier for the certificate log.", "type": "string", "example": "argon2024" }, "startInclusive": { "description": "The start date and time for when the log starts accepting certificates.", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "state": { "description": "The current state of the certificate log. More details about log states can be found here: https://googlechrome.github.io/CertificateTransparency/log_states.html", "type": "string", "enum": [ "USABLE", "PENDING", "QUALIFIED", "READ_ONLY", "RETIRED", "REJECTED" ] }, "stateTimestamp": { "description": "Timestamp of when the log state was last updated.", "type": "string", "format": "date-time", "example": "2025-02-01T08:53:20Z" }, "url": { "description": "The URL for the certificate log.", "type": "string", "example": "https://ct.googleapis.com/logs/us1/argon2024/" } }, "required": [ "slug", "description", "operator", "api", "state", "stateTimestamp", "startInclusive", "endExclusive", "url" ], "type": "object" } } }, "required": [ "certificateLogs" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Certificate Transparency" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ct.logs", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/radar/ct/logs/{log_slug}": { "get": { "operationId": "radar-get-certificate-log-details", "summary": "Get certificate log details", "description": "Retrieves the requested certificate log information.", "parameters": [ { "name": "log_slug", "in": "path", "description": "Certificate log slug.", "required": true, "schema": { "description": "Certificate log slug.", "type": "string", "example": "argon2024", "maxLength": 100 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "certificateLog": { "type": "object", "properties": { "api": { "description": "The API standard that the certificate log follows.", "type": "string", "enum": [ "RFC6962", "STATIC" ] }, "avgThroughput": { "description": "The average throughput of the CT log, measured in certificates per hour (certs/hour).", "type": "number" }, "description": { "description": "A brief description of the certificate log.", "type": "string", "example": "Google 'Argon2024' log" }, "endExclusive": { "description": "The end date and time for when the log will stop accepting certificates.", "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z" }, "lastUpdate": { "description": "Timestamp of the most recent update to the CT log.", "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z" }, "operator": { "description": "The organization responsible for operating the certificate log.", "type": "string", "example": "Google" }, "performance": { "description": "Log performance metrics, including averages and per-endpoint details.", "type": "object", "nullable": true, "properties": { "endpoints": { "type": "array", "items": { "properties": { "endpoint": { "description": "The certificate log endpoint names used in performance metrics.", "type": "string", "enum": [ "add-chain (new)", "add-chain (old)", "add-pre-chain (new)", "add-pre-chain (old)", "get-entries", "get-roots", "get-sth" ] }, "responseTime": { "type": "number" }, "uptime": { "type": "number" } }, "required": [ "endpoint", "responseTime", "uptime" ], "type": "object" } }, "responseTime": { "type": "number" }, "uptime": { "type": "number" } }, "required": [ "responseTime", "uptime", "endpoints" ] }, "related": { "description": "Logs from the same operator.", "type": "array", "items": { "properties": { "description": { "description": "A brief description of the certificate log.", "type": "string", "example": "Google 'Argon2024' log" }, "endExclusive": { "description": "The end date and time for when the log will stop accepting certificates.", "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z" }, "slug": { "description": "A URL-friendly, kebab-case identifier for the certificate log.", "type": "string", "example": "argon2024" }, "startInclusive": { "description": "The start date and time for when the log starts accepting certificates.", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "state": { "description": "The current state of the certificate log. More details about log states can be found here: https://googlechrome.github.io/CertificateTransparency/log_states.html", "type": "string", "enum": [ "USABLE", "PENDING", "QUALIFIED", "READ_ONLY", "RETIRED", "REJECTED" ] } }, "required": [ "slug", "description", "state", "startInclusive", "endExclusive" ], "type": "object" } }, "slug": { "description": "A URL-friendly, kebab-case identifier for the certificate log.", "type": "string", "example": "argon2024" }, "startInclusive": { "description": "The start date and time for when the log starts accepting certificates.", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "state": { "description": "The current state of the certificate log. More details about log states can be found here: https://googlechrome.github.io/CertificateTransparency/log_states.html", "type": "string", "enum": [ "USABLE", "PENDING", "QUALIFIED", "READ_ONLY", "RETIRED", "REJECTED" ] }, "stateTimestamp": { "description": "Timestamp of when the log state was last updated.", "type": "string", "format": "date-time", "example": "2025-02-01T08:53:20Z" }, "submittableCertCount": { "description": "Number of certificates that are eligible for inclusion to this log but have not been included yet. Based on certificates signed by trusted root CAs within the log's accepted date range.", "type": "string", "example": "10", "nullable": true, "pattern": "^-?\\d+(\\.\\d+)?$" }, "submittedCertCount": { "description": "Number of certificates already included in this CT log.", "type": "string", "example": "10", "nullable": true, "pattern": "^-?\\d+(\\.\\d+)?$" }, "url": { "description": "The URL for the certificate log.", "type": "string", "example": "https://ct.googleapis.com/logs/us1/argon2024/" } }, "required": [ "slug", "description", "operator", "api", "state", "stateTimestamp", "startInclusive", "endExclusive", "url", "performance", "avgThroughput", "submittedCertCount", "submittableCertCount", "lastUpdate", "related" ] } }, "required": [ "certificateLog" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Certificate Transparency" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ct.logs", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/ct/summary/{dimension}": { "get": { "operationId": "radar-get-ct-summary", "summary": "Get certificate distribution by dimension", "description": "Retrieves an aggregated summary of certificates grouped by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the certificate attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the certificate attribute by which to group the results.", "type": "string", "enum": [ "CA", "CA_OWNER", "DURATION", "ENTRY_TYPE", "EXPIRATION_STATUS", "HAS_IPS", "HAS_WILDCARDS", "LOG", "LOG_API", "LOG_OPERATOR", "PUBLIC_KEY_ALGORITHM", "SIGNATURE_ALGORITHM", "TLD", "VALIDATION_LEVEL" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "ca", "in": "query", "description": "Filters results by certificate authority.", "schema": { "description": "Filters results by certificate authority.", "type": "array", "items": { "type": "string" } } }, { "name": "caOwner", "in": "query", "description": "Filters results by certificate authority owner.", "schema": { "description": "Filters results by certificate authority owner.", "type": "array", "items": { "type": "string" } } }, { "name": "duration", "in": "query", "description": "Filters results by certificate duration.", "schema": { "description": "Filters results by certificate duration.", "type": "array", "items": { "enum": [ "LTE_3D", "GT_3D_LTE_7D", "GT_7D_LTE_10D", "GT_10D_LTE_47D", "GT_47D_LTE_100D", "GT_100D_LTE_200D", "GT_200D" ], "type": "string" } } }, { "name": "entryType", "in": "query", "description": "Filters results by entry type (certificate vs. pre-certificate). Incompatible with the `tld` filter/dimension.", "schema": { "description": "Filters results by entry type (certificate vs. pre-certificate). Incompatible with the `tld` filter/dimension.", "type": "array", "items": { "enum": [ "PRECERTIFICATE", "CERTIFICATE" ], "type": "string" } } }, { "name": "expirationStatus", "in": "query", "description": "Filters results by expiration status (expired vs. valid).", "schema": { "description": "Filters results by expiration status (expired vs. valid).", "type": "array", "items": { "enum": [ "EXPIRED", "VALID" ], "type": "string" } } }, { "name": "hasIps", "in": "query", "description": "Filters results based on whether the certificates are bound to specific IP addresses.", "schema": { "description": "Filters results based on whether the certificates are bound to specific IP addresses.", "type": "array", "items": { "type": "boolean" } } }, { "name": "hasWildcards", "in": "query", "description": "Filters results based on whether the certificates contain wildcard domains.", "schema": { "description": "Filters results based on whether the certificates contain wildcard domains.", "type": "array", "items": { "type": "boolean" } } }, { "name": "log", "in": "query", "description": "Filters results by certificate log. Incompatible with the `tld` filter/dimension.", "schema": { "description": "Filters results by certificate log. Incompatible with the `tld` filter/dimension.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "logApi", "in": "query", "description": "Filters results by certificate log API (RFC6962 vs. static). Incompatible with the `tld` filter/dimension.", "schema": { "description": "Filters results by certificate log API (RFC6962 vs. static). Incompatible with the `tld` filter/dimension.", "type": "array", "items": { "enum": [ "RFC6962", "STATIC" ], "type": "string" } } }, { "name": "logOperator", "in": "query", "description": "Filters results by certificate log operator. Incompatible with the `tld` filter/dimension.", "schema": { "description": "Filters results by certificate log operator. Incompatible with the `tld` filter/dimension.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "publicKeyAlgorithm", "in": "query", "description": "Filters results by public key algorithm.", "schema": { "description": "Filters results by public key algorithm.", "type": "array", "items": { "enum": [ "DSA", "ECDSA", "RSA" ], "type": "string" } } }, { "name": "signatureAlgorithm", "in": "query", "description": "Filters results by signature algorithm.", "schema": { "description": "Filters results by signature algorithm.", "type": "array", "items": { "enum": [ "DSA_SHA_1", "DSA_SHA_256", "ECDSA_SHA_1", "ECDSA_SHA_256", "ECDSA_SHA_384", "ECDSA_SHA_512", "PSS_SHA_256", "PSS_SHA_384", "PSS_SHA_512", "RSA_MD2", "RSA_MD5", "RSA_SHA_1", "RSA_SHA_256", "RSA_SHA_384", "RSA_SHA_512" ], "type": "string" } } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `log`, `logApi`, `logOperator`, and `entryType` filters/dimensions.", "schema": { "description": "Filters results by top-level domain. Incompatible with the `log`, `logApi`, `logOperator`, and `entryType` filters/dimensions.", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "validationLevel", "in": "query", "description": "Filters results by validation level.", "schema": { "description": "Filters results by validation level.", "type": "array", "items": { "enum": [ "DOMAIN", "ORGANIZATION", "EXTENDED" ], "type": "string" } } }, { "name": "uniqueEntries", "in": "query", "description": "Specifies whether to filter out duplicate certificates and pre-certificates. Set to true for unique entries only.", "schema": { "description": "Specifies whether to filter out duplicate certificates and pre-certificates. Set to true for unique entries only.", "type": "array", "items": { "enum": [ "true", "false" ], "type": "string" } } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "RAW_VALUES", "default": "RAW_VALUES", "enum": [ "RAW_VALUES", "PERCENTAGE" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "anyOf": [ { "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "example": { "DigiCert": "10.274394", "GoDaddy": "8.381743", "Internet Security Research Group": "63.40249" }, "type": "object" }, { "properties": { "rfc6962": { "type": "string" }, "static": { "type": "string" } }, "required": [ "rfc6962", "static" ], "type": "object" }, { "properties": { "gt_121d": { "type": "string" }, "gt_16d_lte_31d": { "type": "string" }, "gt_31d_lte_91d": { "type": "string" }, "gt_3d_lte_16d": { "type": "string" }, "gt_91d_lte_121d": { "type": "string" }, "lte_3d": { "type": "string" } }, "required": [ "gt_31d_lte_91d", "gt_121d", "lte_3d", "gt_91d_lte_121d", "gt_16d_lte_31d", "gt_3d_lte_16d" ], "type": "object" }, { "properties": { "CERTIFICATE": { "type": "string" }, "PRECERTIFICATE": { "type": "string" } }, "required": [ "CERTIFICATE", "PRECERTIFICATE" ], "type": "object" }, { "properties": { "EXPIRED": { "type": "string" }, "VALID": { "type": "string" } }, "required": [ "VALID", "EXPIRED" ], "type": "object" }, { "properties": { "NEGATIVE": { "type": "string" }, "POSITIVE": { "type": "string" } }, "required": [ "POSITIVE", "NEGATIVE" ], "type": "object" }, { "properties": { "DSA": { "type": "string" }, "ECDSA": { "type": "string" }, "RSA": { "type": "string" } }, "required": [ "RSA", "ECDSA", "DSA" ], "type": "object" }, { "properties": { "domain": { "type": "string" }, "extended": { "type": "string" }, "organization": { "type": "string" }, "unknown": { "type": "string" } }, "required": [ "domain", "organization", "unknown", "extended" ], "type": "object" } ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Certificate Transparency" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ct", "x-fern-sdk-method-name": "summary", "x-forge-hidden": true } }, "/radar/ct/timeseries": { "get": { "operationId": "radar-get-ct-timeseries", "summary": "Get certificates time series", "description": "Retrieves certificate volume over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "ca", "in": "query", "description": "Filters results by certificate authority.", "schema": { "description": "Filters results by certificate authority.", "type": "array", "items": { "type": "string" } } }, { "name": "caOwner", "in": "query", "description": "Filters results by certificate authority owner.", "schema": { "description": "Filters results by certificate authority owner.", "type": "array", "items": { "type": "string" } } }, { "name": "duration", "in": "query", "description": "Filters results by certificate duration.", "schema": { "description": "Filters results by certificate duration.", "type": "array", "items": { "enum": [ "LTE_3D", "GT_3D_LTE_7D", "GT_7D_LTE_10D", "GT_10D_LTE_47D", "GT_47D_LTE_100D", "GT_100D_LTE_200D", "GT_200D" ], "type": "string" } } }, { "name": "entryType", "in": "query", "description": "Filters results by entry type (certificate vs. pre-certificate). Incompatible with the `tld` filter/dimension.", "schema": { "description": "Filters results by entry type (certificate vs. pre-certificate). Incompatible with the `tld` filter/dimension.", "type": "array", "items": { "enum": [ "PRECERTIFICATE", "CERTIFICATE" ], "type": "string" } } }, { "name": "expirationStatus", "in": "query", "description": "Filters results by expiration status (expired vs. valid).", "schema": { "description": "Filters results by expiration status (expired vs. valid).", "type": "array", "items": { "enum": [ "EXPIRED", "VALID" ], "type": "string" } } }, { "name": "hasIps", "in": "query", "description": "Filters results based on whether the certificates are bound to specific IP addresses.", "schema": { "description": "Filters results based on whether the certificates are bound to specific IP addresses.", "type": "array", "items": { "type": "boolean" } } }, { "name": "hasWildcards", "in": "query", "description": "Filters results based on whether the certificates contain wildcard domains.", "schema": { "description": "Filters results based on whether the certificates contain wildcard domains.", "type": "array", "items": { "type": "boolean" } } }, { "name": "log", "in": "query", "description": "Filters results by certificate log. Incompatible with the `tld` filter/dimension.", "schema": { "description": "Filters results by certificate log. Incompatible with the `tld` filter/dimension.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "logApi", "in": "query", "description": "Filters results by certificate log API (RFC6962 vs. static). Incompatible with the `tld` filter/dimension.", "schema": { "description": "Filters results by certificate log API (RFC6962 vs. static). Incompatible with the `tld` filter/dimension.", "type": "array", "items": { "enum": [ "RFC6962", "STATIC" ], "type": "string" } } }, { "name": "logOperator", "in": "query", "description": "Filters results by certificate log operator. Incompatible with the `tld` filter/dimension.", "schema": { "description": "Filters results by certificate log operator. Incompatible with the `tld` filter/dimension.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "publicKeyAlgorithm", "in": "query", "description": "Filters results by public key algorithm.", "schema": { "description": "Filters results by public key algorithm.", "type": "array", "items": { "enum": [ "DSA", "ECDSA", "RSA" ], "type": "string" } } }, { "name": "signatureAlgorithm", "in": "query", "description": "Filters results by signature algorithm.", "schema": { "description": "Filters results by signature algorithm.", "type": "array", "items": { "enum": [ "DSA_SHA_1", "DSA_SHA_256", "ECDSA_SHA_1", "ECDSA_SHA_256", "ECDSA_SHA_384", "ECDSA_SHA_512", "PSS_SHA_256", "PSS_SHA_384", "PSS_SHA_512", "RSA_MD2", "RSA_MD5", "RSA_SHA_1", "RSA_SHA_256", "RSA_SHA_384", "RSA_SHA_512" ], "type": "string" } } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `log`, `logApi`, `logOperator`, and `entryType` filters/dimensions.", "schema": { "description": "Filters results by top-level domain. Incompatible with the `log`, `logApi`, `logOperator`, and `entryType` filters/dimensions.", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "validationLevel", "in": "query", "description": "Filters results by validation level.", "schema": { "description": "Filters results by validation level.", "type": "array", "items": { "enum": [ "DOMAIN", "ORGANIZATION", "EXTENDED" ], "type": "string" } } }, { "name": "uniqueEntries", "in": "query", "description": "Specifies whether to filter out duplicate certificates and pre-certificates. Set to true for unique entries only.", "schema": { "description": "Specifies whether to filter out duplicate certificates and pre-certificates. Set to true for unique entries only.", "type": "array", "items": { "enum": [ "true", "false" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "additionalProperties": { "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } }, "values": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "timestamps", "values" ], "type": "object" }, "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] } }, "required": [ "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Certificate Transparency" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ct", "x-fern-sdk-method-name": "timeseries", "x-forge-hidden": true } }, "/radar/ct/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-ct-timeseries-group", "summary": "Get time series of certificate distribution by dimension", "description": "Retrieves the distribution of certificates grouped by the specified dimension over time.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the certificate attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the certificate attribute by which to group the results.", "type": "string", "enum": [ "CA", "CA_OWNER", "DURATION", "ENTRY_TYPE", "EXPIRATION_STATUS", "HAS_IPS", "HAS_WILDCARDS", "LOG", "LOG_API", "LOG_OPERATOR", "PUBLIC_KEY_ALGORITHM", "SIGNATURE_ALGORITHM", "TLD", "VALIDATION_LEVEL" ] } }, { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "ca", "in": "query", "description": "Filters results by certificate authority.", "schema": { "description": "Filters results by certificate authority.", "type": "array", "items": { "type": "string" } } }, { "name": "caOwner", "in": "query", "description": "Filters results by certificate authority owner.", "schema": { "description": "Filters results by certificate authority owner.", "type": "array", "items": { "type": "string" } } }, { "name": "duration", "in": "query", "description": "Filters results by certificate duration.", "schema": { "description": "Filters results by certificate duration.", "type": "array", "items": { "enum": [ "LTE_3D", "GT_3D_LTE_7D", "GT_7D_LTE_10D", "GT_10D_LTE_47D", "GT_47D_LTE_100D", "GT_100D_LTE_200D", "GT_200D" ], "type": "string" } } }, { "name": "entryType", "in": "query", "description": "Filters results by entry type (certificate vs. pre-certificate). Incompatible with the `tld` filter/dimension.", "schema": { "description": "Filters results by entry type (certificate vs. pre-certificate). Incompatible with the `tld` filter/dimension.", "type": "array", "items": { "enum": [ "PRECERTIFICATE", "CERTIFICATE" ], "type": "string" } } }, { "name": "expirationStatus", "in": "query", "description": "Filters results by expiration status (expired vs. valid).", "schema": { "description": "Filters results by expiration status (expired vs. valid).", "type": "array", "items": { "enum": [ "EXPIRED", "VALID" ], "type": "string" } } }, { "name": "hasIps", "in": "query", "description": "Filters results based on whether the certificates are bound to specific IP addresses.", "schema": { "description": "Filters results based on whether the certificates are bound to specific IP addresses.", "type": "array", "items": { "type": "boolean" } } }, { "name": "hasWildcards", "in": "query", "description": "Filters results based on whether the certificates contain wildcard domains.", "schema": { "description": "Filters results based on whether the certificates contain wildcard domains.", "type": "array", "items": { "type": "boolean" } } }, { "name": "log", "in": "query", "description": "Filters results by certificate log. Incompatible with the `tld` filter/dimension.", "schema": { "description": "Filters results by certificate log. Incompatible with the `tld` filter/dimension.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "logApi", "in": "query", "description": "Filters results by certificate log API (RFC6962 vs. static). Incompatible with the `tld` filter/dimension.", "schema": { "description": "Filters results by certificate log API (RFC6962 vs. static). Incompatible with the `tld` filter/dimension.", "type": "array", "items": { "enum": [ "RFC6962", "STATIC" ], "type": "string" } } }, { "name": "logOperator", "in": "query", "description": "Filters results by certificate log operator. Incompatible with the `tld` filter/dimension.", "schema": { "description": "Filters results by certificate log operator. Incompatible with the `tld` filter/dimension.", "type": "array", "items": { "maxLength": 100, "type": "string" } } }, { "name": "publicKeyAlgorithm", "in": "query", "description": "Filters results by public key algorithm.", "schema": { "description": "Filters results by public key algorithm.", "type": "array", "items": { "enum": [ "DSA", "ECDSA", "RSA" ], "type": "string" } } }, { "name": "signatureAlgorithm", "in": "query", "description": "Filters results by signature algorithm.", "schema": { "description": "Filters results by signature algorithm.", "type": "array", "items": { "enum": [ "DSA_SHA_1", "DSA_SHA_256", "ECDSA_SHA_1", "ECDSA_SHA_256", "ECDSA_SHA_384", "ECDSA_SHA_512", "PSS_SHA_256", "PSS_SHA_384", "PSS_SHA_512", "RSA_MD2", "RSA_MD5", "RSA_SHA_1", "RSA_SHA_256", "RSA_SHA_384", "RSA_SHA_512" ], "type": "string" } } }, { "name": "validationLevel", "in": "query", "description": "Filters results by validation level.", "schema": { "description": "Filters results by validation level.", "type": "array", "items": { "enum": [ "DOMAIN", "ORGANIZATION", "EXTENDED" ], "type": "string" } } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `log`, `logApi`, `logOperator`, and `entryType` filters/dimensions.", "schema": { "description": "Filters results by top-level domain. Incompatible with the `log`, `logApi`, `logOperator`, and `entryType` filters/dimensions.", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "RAW_VALUES", "default": "RAW_VALUES", "enum": [ "RAW_VALUES", "PERCENTAGE" ] } }, { "name": "uniqueEntries", "in": "query", "description": "Specifies whether to filter out duplicate certificates and pre-certificates. Set to true for unique entries only.", "schema": { "description": "Specifies whether to filter out duplicate certificates and pre-certificates. Set to true for unique entries only.", "type": "array", "items": { "enum": [ "true", "false" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "anyOf": [ { "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "example": { "DigiCert": [ "10.274394" ], "GoDaddy": [ "8.381743" ], "Internet Security Research Group": [ "63.40249" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ], "type": "object" }, { "properties": { "rfc6962": { "type": "array", "items": { "type": "string" } }, "static": { "type": "array", "items": { "type": "string" } } }, "required": [ "rfc6962", "static" ], "type": "object" }, { "properties": { "gt_121d": { "type": "array", "items": { "type": "string" } }, "gt_16d_lte_31d": { "type": "array", "items": { "type": "string" } }, "gt_31d_lte_91d": { "type": "array", "items": { "type": "string" } }, "gt_3d_lte_16d": { "type": "array", "items": { "type": "string" } }, "gt_91d_lte_121d": { "type": "array", "items": { "type": "string" } }, "lte_3d": { "type": "array", "items": { "type": "string" } } }, "required": [ "gt_31d_lte_91d", "gt_121d", "lte_3d", "gt_91d_lte_121d", "gt_16d_lte_31d", "gt_3d_lte_16d" ], "type": "object" }, { "properties": { "CERTIFICATE": { "type": "array", "items": { "type": "string" } }, "PRECERTIFICATE": { "type": "array", "items": { "type": "string" } } }, "required": [ "CERTIFICATE", "PRECERTIFICATE" ], "type": "object" }, { "properties": { "EXPIRED": { "type": "array", "items": { "type": "string" } }, "VALID": { "type": "array", "items": { "type": "string" } } }, "required": [ "VALID", "EXPIRED" ], "type": "object" }, { "properties": { "NEGATIVE": { "type": "array", "items": { "type": "string" } }, "POSITIVE": { "type": "array", "items": { "type": "string" } } }, "required": [ "POSITIVE", "NEGATIVE" ], "type": "object" }, { "properties": { "DSA": { "type": "array", "items": { "type": "string" } }, "ECDSA": { "type": "array", "items": { "type": "string" } }, "RSA": { "type": "array", "items": { "type": "string" } } }, "required": [ "RSA", "ECDSA", "DSA" ], "type": "object" }, { "properties": { "domain": { "type": "array", "items": { "type": "string" } }, "extended": { "type": "array", "items": { "type": "string" } }, "organization": { "type": "array", "items": { "type": "string" } }, "unknown": { "type": "array", "items": { "type": "string" } } }, "required": [ "domain", "organization", "unknown", "extended" ], "type": "object" } ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Certificate Transparency" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ct", "x-fern-sdk-method-name": "timeseries-groups", "x-forge-hidden": true } }, "/radar/datasets": { "get": { "operationId": "radar-get-reports-datasets", "summary": "List datasets", "description": "Retrieves a list of datasets.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Skips the specified number of objects before fetching the results.", "schema": { "description": "Skips the specified number of objects before fetching the results.", "type": "integer", "minimum": 0 } }, { "name": "datasetType", "in": "query", "description": "Filters results by dataset type.", "schema": { "description": "Filters results by dataset type.", "type": "string", "example": "RANKING_BUCKET", "default": "RANKING_BUCKET", "enum": [ "RANKING_BUCKET", "REPORT" ] } }, { "name": "date", "in": "query", "description": "Filters results by the specified date.", "schema": { "description": "Filters results by the specified date.", "type": "string", "format": "date", "example": "2024-09-19" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "datasets": { "type": "array", "items": { "properties": { "description": { "type": "string", "example": "This dataset contains a list of the op 20000 domains globally" }, "id": { "type": "integer", "example": 3 }, "meta": { "type": "object" }, "tags": { "type": "array", "items": { "example": "global", "type": "string" } }, "title": { "type": "string", "example": "Top bucket 20000 domains" }, "type": { "type": "string", "example": "RANKING_BUCKET" } }, "required": [ "id", "title", "description", "type", "tags", "meta" ], "type": "object" } } }, "required": [ "datasets" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Datasets" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.datasets", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/radar/datasets/download": { "post": { "operationId": "radar-post-reports-dataset-download-url", "summary": "Get dataset download URL", "description": "Retrieves an URL to download a single dataset.", "parameters": [ { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "datasetId": { "type": "integer", "example": 3, "x-auditable": true } }, "required": [ "datasetId" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "dataset": { "type": "object", "properties": { "url": { "type": "string", "example": "https://example.com/download" } }, "required": [ "url" ] } }, "required": [ "dataset" ] } }, "required": [ "result" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Datasets" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.datasets", "x-fern-sdk-method-name": "download", "x-forge-hidden": true } }, "/radar/datasets/{alias}": { "get": { "operationId": "radar-get-reports-dataset-download", "summary": "Get dataset CSV stream", "description": "Retrieves the CSV content of a given dataset by alias or ID. When getting the content by alias the latest dataset is returned, optionally filtered by the latest available at a given date.", "parameters": [ { "name": "alias", "in": "path", "description": "Dataset alias or ID.", "required": true, "schema": { "description": "Dataset alias or ID.", "type": "string", "example": "ranking_top_1000" } } ], "responses": { "200": { "description": "Successful response.", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Datasets" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.datasets", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/dns/summary/cache_hit": { "get": { "operationId": "radar-get-dns-summary-by-cache-hit-status", "summary": "Get DNS queries by cache status summary", "description": "Retrieves the distribution of DNS queries by cache status.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "NEGATIVE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "POSITIVE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "POSITIVE", "NEGATIVE" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.summary", "x-fern-sdk-method-name": "cache-hit", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/summary_v2/) instead." } }, "/radar/dns/summary/dnssec": { "get": { "operationId": "radar-get-dns-summary-by-dnssec", "summary": "Get DNS queries by DNSSEC support summary", "description": "Retrieves the distribution of DNS responses by DNSSEC (DNS Security Extensions) support.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "INSECURE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "INVALID": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "OTHER": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "SECURE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "INSECURE", "SECURE", "INVALID", "OTHER" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.summary", "x-fern-sdk-method-name": "dnssec", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/summary_v2/) instead." } }, "/radar/dns/summary/dnssec_aware": { "get": { "operationId": "radar-get-dns-summary-by-dnssec-awareness", "summary": "Get DNS queries by DNSSEC awareness summary", "description": "Retrieves the distribution of DNS queries by DNSSEC (DNS Security Extensions) client awareness.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "NOT_SUPPORTED": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "SUPPORTED": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "NOT_SUPPORTED", "SUPPORTED" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.summary", "x-fern-sdk-method-name": "dnssec-aware", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/summary_v2/) instead." } }, "/radar/dns/summary/dnssec_e2e": { "get": { "operationId": "radar-get-dns-summary-by-dnssec-e2e-version", "summary": "Get DNS queries by DNSSEC end-to-end summary", "description": "Retrieves the distribution of DNSSEC-validated answers by end-to-end security status.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "NEGATIVE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "POSITIVE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "NEGATIVE", "POSITIVE" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.summary", "x-fern-sdk-method-name": "dnssec-e2e", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/summary_v2/) instead." } }, "/radar/dns/summary/ip_version": { "get": { "operationId": "radar-get-dns-summary-by-ip-version", "summary": "Get DNS queries by IP version summary", "description": "Retrieves the distribution of DNS queries by IP version.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "IPv4": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "IPv6": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "IPv4", "IPv6" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.summary", "x-fern-sdk-method-name": "ip-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/summary_v2/) instead." } }, "/radar/dns/summary/matching_answer": { "get": { "operationId": "radar-get-dns-summary-by-matching-answer-status", "summary": "Get DNS queries by matching answer summary", "description": "Retrieves the distribution of DNS queries by matching answers.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "NEGATIVE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "POSITIVE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "POSITIVE", "NEGATIVE" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.summary", "x-fern-sdk-method-name": "matching-answer", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/summary_v2/) instead." } }, "/radar/dns/summary/protocol": { "get": { "operationId": "radar-get-dns-summary-by-protocol", "summary": "Get DNS queries by protocol summary", "description": "Retrieves the distribution of DNS queries by DNS transport protocol.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "HTTPS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "TCP": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "TLS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "UDP": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "UDP", "TLS", "HTTPS", "TCP" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.summary", "x-fern-sdk-method-name": "protocol", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/summary_v2/) instead." } }, "/radar/dns/summary/query_type": { "get": { "operationId": "radar-get-dns-summary-by-query-type", "summary": "Get DNS queries by type summary", "description": "Retrieves the distribution of DNS queries by type.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "A": "20", "AAAA": "20", "HTTPS": "20", "NS": "20", "PTR": "20" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.summary", "x-fern-sdk-method-name": "query-type", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/summary_v2/) instead." } }, "/radar/dns/summary/response_code": { "get": { "operationId": "radar-get-dns-summary-by-response-code", "summary": "Get DNS queries by response code summary", "description": "Retrieves the distribution of DNS queries by response code.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "NOERROR": "70", "NOTIMP": "5", "NXDOMAIN": "10", "REFUSED": "5", "SERVFAIL": "5" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.summary", "x-fern-sdk-method-name": "response-code", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/summary_v2/) instead." } }, "/radar/dns/summary/response_ttl": { "get": { "operationId": "radar-get-dns-summary-by-response-ttl", "summary": "Get DNS queries by response TTL summary", "description": "Retrieves the distribution of DNS queries by minimum response TTL.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "gt_15m_lte_1h": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "gt_1d_lte_1w": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "gt_1h_lte_1d": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "gt_1m_lte_5m": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "gt_1w": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "gt_5m_lte_15m": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "lte_1m": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "lte_1m", "gt_1m_lte_5m", "gt_5m_lte_15m", "gt_15m_lte_1h", "gt_1h_lte_1d", "gt_1d_lte_1w", "gt_1w" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.summary", "x-fern-sdk-method-name": "response-ttl", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/summary_v2/) instead." } }, "/radar/dns/summary/{dimension}": { "get": { "operationId": "radar-get-dns-summary", "summary": "Get DNS summary by dimension", "description": "Retrieves the distribution of DNS queries by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results. Grouping by `TLD_DNS_MAGNITUDE` does not support sub-daily aggregation intervals; `15m` and `1h` are raised to `1d`.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results. Grouping by `TLD_DNS_MAGNITUDE` does not support sub-daily aggregation intervals; `15m` and `1h` are raised to `1d`.", "type": "string", "enum": [ "AS", "CACHE_HIT", "DNSSEC", "DNSSEC_AWARE", "DNSSEC_E2E", "IP_VERSION", "LOCATION", "MATCHING_ANSWER", "PROTOCOL", "QUERY_TYPE", "RESPONSE_CODE", "RESPONSE_TTL", "TLD", "TLD_DNS_MAGNITUDE" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "cacheHit", "in": "query", "description": "Filters results based on cache status.", "schema": { "description": "Filters results based on cache status.", "type": "array", "items": { "type": "boolean" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "responseTtl", "in": "query", "description": "Filters results by DNS response TTL.", "schema": { "description": "Filters results by DNS response TTL.", "type": "array", "items": { "enum": [ "LTE_1M", "GT_1M_LTE_5M", "GT_5M_LTE_15M", "GT_15M_LTE_1H", "GT_1H_LTE_1D", "GT_1D_LTE_1W", "GT_1W" ], "type": "string" } } }, { "name": "dnssec", "in": "query", "description": "Filters results based on DNSSEC (DNS Security Extensions) support.", "schema": { "description": "Filters results based on DNSSEC (DNS Security Extensions) support.", "type": "array", "items": { "enum": [ "INVALID", "INSECURE", "SECURE", "OTHER" ], "type": "string" } } }, { "name": "dnssecAware", "in": "query", "description": "Filters results based on DNSSEC (DNS Security Extensions) client awareness.", "schema": { "description": "Filters results based on DNSSEC (DNS Security Extensions) client awareness.", "type": "array", "items": { "enum": [ "SUPPORTED", "NOT_SUPPORTED" ], "type": "string" } } }, { "name": "dnssecE2e", "in": "query", "description": "Filters results based on DNSSEC-validated answers by end-to-end security status.", "schema": { "description": "Filters results based on DNSSEC-validated answers by end-to-end security status.", "type": "array", "items": { "type": "boolean" } } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "matchingAnswer", "in": "query", "description": "Filters results based on whether the queries have a matching answer.", "schema": { "description": "Filters results based on whether the queries have a matching answer.", "type": "array", "items": { "type": "boolean" } } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "IPv4": "50.168733", "IPv6": "25.084366" }, "additionalProperties": { "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.dns", "x-fern-sdk-method-name": "summary-v2", "x-forge-hidden": true } }, "/radar/dns/timeseries": { "get": { "operationId": "radar-get-dns-timeseries", "summary": "Get DNS queries time series", "description": "Retrieves normalized query volume to the 1.1.1.1 DNS resolver over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "cacheHit", "in": "query", "description": "Filters results based on cache status.", "schema": { "description": "Filters results based on cache status.", "type": "array", "items": { "type": "boolean" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "responseTtl", "in": "query", "description": "Filters results by DNS response TTL.", "schema": { "description": "Filters results by DNS response TTL.", "type": "array", "items": { "enum": [ "LTE_1M", "GT_1M_LTE_5M", "GT_5M_LTE_15M", "GT_15M_LTE_1H", "GT_1H_LTE_1D", "GT_1D_LTE_1W", "GT_1W" ], "type": "string" } } }, { "name": "dnssec", "in": "query", "description": "Filters results based on DNSSEC (DNS Security Extensions) support.", "schema": { "description": "Filters results based on DNSSEC (DNS Security Extensions) support.", "type": "array", "items": { "enum": [ "INVALID", "INSECURE", "SECURE", "OTHER" ], "type": "string" } } }, { "name": "dnssecAware", "in": "query", "description": "Filters results based on DNSSEC (DNS Security Extensions) client awareness.", "schema": { "description": "Filters results based on DNSSEC (DNS Security Extensions) client awareness.", "type": "array", "items": { "enum": [ "SUPPORTED", "NOT_SUPPORTED" ], "type": "string" } } }, { "name": "dnssecE2e", "in": "query", "description": "Filters results based on DNSSEC-validated answers by end-to-end security status.", "schema": { "description": "Filters results based on DNSSEC-validated answers by end-to-end security status.", "type": "array", "items": { "type": "boolean" } } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "matchingAnswer", "in": "query", "description": "Filters results based on whether the queries have a matching answer.", "schema": { "description": "Filters results based on whether the queries have a matching answer.", "type": "array", "items": { "type": "boolean" } } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "additionalProperties": { "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } }, "values": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "timestamps", "values" ], "type": "object" }, "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] } }, "required": [ "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.dns", "x-fern-sdk-method-name": "timeseries", "x-forge-hidden": true } }, "/radar/dns/timeseries_groups/cache_hit": { "get": { "operationId": "radar-get-dns-timeseries-group-by-cache-hit-status", "summary": "Get DNS queries by cache status time series", "description": "Retrieves the distribution of DNS queries by cache status over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "NEGATIVE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "POSITIVE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "POSITIVE", "NEGATIVE" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.timeseries-groups", "x-fern-sdk-method-name": "cache-hit", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/timeseries_groups_v2/) instead." } }, "/radar/dns/timeseries_groups/dnssec": { "get": { "operationId": "radar-get-dns-timeseries-group-by-dnssec", "summary": "Get DNS queries by DNSSEC support time series", "description": "Retrieves the distribution of DNS responses by DNSSEC (DNS Security Extensions) support over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "INSECURE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "INVALID": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "OTHER": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "SECURE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "INSECURE", "SECURE", "INVALID", "OTHER" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.timeseries-groups", "x-fern-sdk-method-name": "dnssec", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/timeseries_groups_v2/) instead." } }, "/radar/dns/timeseries_groups/dnssec_aware": { "get": { "operationId": "radar-get-dns-timeseries-group-by-dnssec-awareness", "summary": "Get DNS queries by DNSSEC awareness time series", "description": "Retrieves the distribution of DNS queries by DNSSEC (DNS Security Extensions) client awareness over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "NOT_SUPPORTED": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "SUPPORTED": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "NOT_SUPPORTED", "SUPPORTED" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.timeseries-groups", "x-fern-sdk-method-name": "dnssec-aware", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/timeseries_groups_v2/) instead." } }, "/radar/dns/timeseries_groups/dnssec_e2e": { "get": { "operationId": "radar-get-dns-timeseries-group-by-dnssec-e2e-version", "summary": "Get DNS queries by DNSSEC end-to-end time series", "description": "Retrieves the distribution of DNSSEC-validated answers by end-to-end security status over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "NEGATIVE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "POSITIVE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "NEGATIVE", "POSITIVE" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.timeseries-groups", "x-fern-sdk-method-name": "dnssec-e2e", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/timeseries_groups_v2/) instead." } }, "/radar/dns/timeseries_groups/ip_version": { "get": { "operationId": "radar-get-dns-timeseries-group-by-ip-version", "summary": "Get DNS queries by IP version time series", "description": "Retrieves the distribution of DNS queries by IP version over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "IPv4": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "IPv6": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "IPv4", "IPv6" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.timeseries-groups", "x-fern-sdk-method-name": "ip-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/timeseries_groups_v2/) instead." } }, "/radar/dns/timeseries_groups/matching_answer": { "get": { "operationId": "radar-get-dns-timeseries-group-by-matching-answer-status", "summary": "Get DNS queries by matching answer time series", "description": "Retrieves the distribution of DNS queries by matching answers over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "NEGATIVE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "POSITIVE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "POSITIVE", "NEGATIVE" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.timeseries-groups", "x-fern-sdk-method-name": "matching-answer", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/timeseries_groups_v2/) instead." } }, "/radar/dns/timeseries_groups/protocol": { "get": { "operationId": "radar-get-dns-timeseries-group-by-protocol", "summary": "Get DNS queries by protocol time series", "description": "Retrieves the distribution of DNS queries by DNS transport protocol over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "HTTPS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "TCP": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "TLS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "UDP": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "UDP", "TLS", "HTTPS", "TCP" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.timeseries-groups", "x-fern-sdk-method-name": "protocol", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/timeseries_groups_v2/) instead." } }, "/radar/dns/timeseries_groups/query_type": { "get": { "operationId": "radar-get-dns-timeseries-group-by-query-type", "summary": "Get DNS queries by type time series", "description": "Retrieves the distribution of DNS queries by type over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "A": [ "20" ], "AAAA": [ "20" ], "HTTPS": [ "20" ], "NS": [ "20" ], "PTR": [ "20" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.timeseries-groups", "x-fern-sdk-method-name": "query-type", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/timeseries_groups_v2/) instead." } }, "/radar/dns/timeseries_groups/response_code": { "get": { "operationId": "radar-get-dns-timeseries-group-by-response-code", "summary": "Get DNS queries by response code time series", "description": "Retrieves the distribution of DNS queries by response code over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "NOERROR": [ "70" ], "NOTIMP": [ "5" ], "NXDOMAIN": [ "10" ], "REFUSED": [ "5" ], "SERVFAIL": [ "5" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.timeseries-groups", "x-fern-sdk-method-name": "response-code", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/timeseries_groups_v2/) instead." } }, "/radar/dns/timeseries_groups/response_ttl": { "get": { "operationId": "radar-get-dns-timeseries-group-by-response-ttl", "summary": "Get DNS queries by response TTL time series", "description": "Retrieves the distribution of DNS queries by minimum answer TTL over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "gt_15m_lte_1h": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "gt_1d_lte_1w": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "gt_1h_lte_1d": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "gt_1m_lte_5m": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "gt_1w": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "gt_5m_lte_15m": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "lte_1m": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "lte_1m", "gt_1m_lte_5m", "gt_5m_lte_15m", "gt_15m_lte_1h", "gt_1h_lte_1d", "gt_1d_lte_1w", "gt_1w" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.dns.timeseries-groups", "x-fern-sdk-method-name": "response-ttl", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar DNS Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/dns/methods/timeseries_groups_v2/) instead." } }, "/radar/dns/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-dns-timeseries-group", "summary": "Get DNS time series grouped by dimension", "description": "Retrieves the distribution of DNS queries grouped by dimension over time.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results. Grouping by `TLD_DNS_MAGNITUDE` does not support sub-daily aggregation intervals; `15m` and `1h` are raised to `1d`.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results. Grouping by `TLD_DNS_MAGNITUDE` does not support sub-daily aggregation intervals; `15m` and `1h` are raised to `1d`.", "type": "string", "enum": [ "AS", "CACHE_HIT", "DNSSEC", "DNSSEC_AWARE", "DNSSEC_E2E", "IP_VERSION", "LOCATION", "MATCHING_ANSWER", "PROTOCOL", "QUERY_TYPE", "RESPONSE_CODE", "RESPONSE_TTL", "TLD", "TLD_DNS_MAGNITUDE" ] } }, { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "cacheHit", "in": "query", "description": "Filters results based on cache status.", "schema": { "description": "Filters results based on cache status.", "type": "array", "items": { "type": "boolean" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "responseTtl", "in": "query", "description": "Filters results by DNS response TTL.", "schema": { "description": "Filters results by DNS response TTL.", "type": "array", "items": { "enum": [ "LTE_1M", "GT_1M_LTE_5M", "GT_5M_LTE_15M", "GT_15M_LTE_1H", "GT_1H_LTE_1D", "GT_1D_LTE_1W", "GT_1W" ], "type": "string" } } }, { "name": "dnssec", "in": "query", "description": "Filters results based on DNSSEC (DNS Security Extensions) support.", "schema": { "description": "Filters results based on DNSSEC (DNS Security Extensions) support.", "type": "array", "items": { "enum": [ "INVALID", "INSECURE", "SECURE", "OTHER" ], "type": "string" } } }, { "name": "dnssecAware", "in": "query", "description": "Filters results based on DNSSEC (DNS Security Extensions) client awareness.", "schema": { "description": "Filters results based on DNSSEC (DNS Security Extensions) client awareness.", "type": "array", "items": { "enum": [ "SUPPORTED", "NOT_SUPPORTED" ], "type": "string" } } }, { "name": "dnssecE2e", "in": "query", "description": "Filters results based on DNSSEC-validated answers by end-to-end security status.", "schema": { "description": "Filters results based on DNSSEC-validated answers by end-to-end security status.", "type": "array", "items": { "type": "boolean" } } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "matchingAnswer", "in": "query", "description": "Filters results based on whether the queries have a matching answer.", "schema": { "description": "Filters results based on whether the queries have a matching answer.", "type": "array", "items": { "type": "boolean" } } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `RANK` is only meaningful with the `TLD_DNS_MAGNITUDE` dimension, where it ranks TLDs by DNS query magnitude at each timestamp; for other dimensions it has no effect.", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `RANK` is only meaningful with the `TLD_DNS_MAGNITUDE` dimension, where it ranks TLDs by DNS query magnitude at each timestamp; for other dimensions it has no effect.", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX", "RANK" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "IPv4": [ "50.168733" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.dns", "x-fern-sdk-method-name": "timeseries-groups-v2", "x-forge-hidden": true } }, "/radar/dns/top/ases": { "get": { "operationId": "radar-get-dns-top-ases", "summary": "Get top ASes by DNS queries", "description": "Retrieves the top autonomous systems by DNS queries made to 1.1.1.1 DNS resolver.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "domain", "in": "query", "description": "Filters results by domain name. When set, no other DNS filter may be used — only date filtering (`dateRange`, or `dateStart`/`dateEnd`) is allowed — and the date range cannot exceed 31 days.", "schema": { "description": "Filters results by domain name. When set, no other DNS filter may be used — only date filtering (`dateRange`, or `dateStart`/`dateEnd`) is allowed — and the date range cannot exceed 31 days.", "type": "array", "items": { "example": "google.com", "maxLength": 253, "minLength": 1, "pattern": "^(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)\\.)+(?:[A-Za-z]{2,63})$", "type": "string" }, "example": "google.com" } }, { "name": "cacheHit", "in": "query", "description": "Filters results based on cache status.", "schema": { "description": "Filters results based on cache status.", "type": "array", "items": { "type": "boolean" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "responseTtl", "in": "query", "description": "Filters results by DNS response TTL.", "schema": { "description": "Filters results by DNS response TTL.", "type": "array", "items": { "enum": [ "LTE_1M", "GT_1M_LTE_5M", "GT_5M_LTE_15M", "GT_15M_LTE_1H", "GT_1H_LTE_1D", "GT_1D_LTE_1W", "GT_1W" ], "type": "string" } } }, { "name": "dnssec", "in": "query", "description": "Filters results based on DNSSEC (DNS Security Extensions) support.", "schema": { "description": "Filters results based on DNSSEC (DNS Security Extensions) support.", "type": "array", "items": { "enum": [ "INVALID", "INSECURE", "SECURE", "OTHER" ], "type": "string" } } }, { "name": "dnssecAware", "in": "query", "description": "Filters results based on DNSSEC (DNS Security Extensions) client awareness.", "schema": { "description": "Filters results based on DNSSEC (DNS Security Extensions) client awareness.", "type": "array", "items": { "enum": [ "SUPPORTED", "NOT_SUPPORTED" ], "type": "string" } } }, { "name": "dnssecE2e", "in": "query", "description": "Filters results based on DNSSEC-validated answers by end-to-end security status.", "schema": { "description": "Filters results based on DNSSEC-validated answers by end-to-end security status.", "type": "array", "items": { "type": "boolean" } } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "matchingAnswer", "in": "query", "description": "Filters results based on whether the queries have a matching answer.", "schema": { "description": "Filters results based on whether the queries have a matching answer.", "type": "array", "items": { "type": "boolean" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientASN": { "type": "integer", "example": 174 }, "clientASName": { "type": "string", "example": "Cogent-174" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientASN", "clientASName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.dns.top", "x-fern-sdk-method-name": "ases", "x-forge-hidden": true } }, "/radar/dns/top/locations": { "get": { "operationId": "radar-get-dns-top-locations", "summary": "Get top locations by DNS queries", "description": "Retrieves the top locations by DNS queries made to 1.1.1.1 DNS resolver.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "domain", "in": "query", "description": "Filters results by domain name. When set, no other DNS filter may be used — only date filtering (`dateRange`, or `dateStart`/`dateEnd`) is allowed — and the date range cannot exceed 31 days.", "schema": { "description": "Filters results by domain name. When set, no other DNS filter may be used — only date filtering (`dateRange`, or `dateStart`/`dateEnd`) is allowed — and the date range cannot exceed 31 days.", "type": "array", "items": { "example": "google.com", "maxLength": 253, "minLength": 1, "pattern": "^(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)\\.)+(?:[A-Za-z]{2,63})$", "type": "string" }, "example": "google.com" } }, { "name": "cacheHit", "in": "query", "description": "Filters results based on cache status.", "schema": { "description": "Filters results based on cache status.", "type": "array", "items": { "type": "boolean" } } }, { "name": "nodata", "in": "query", "description": "Specifies whether the response includes empty DNS responses (NODATA).", "schema": { "description": "Specifies whether the response includes empty DNS responses (NODATA).", "type": "array", "items": { "type": "boolean" }, "default": [ "true" ] } }, { "name": "protocol", "in": "query", "description": "Filters results by DNS transport protocol.", "schema": { "description": "Filters results by DNS transport protocol.", "type": "array", "items": { "enum": [ "UDP", "TCP", "HTTPS", "TLS" ], "type": "string" } } }, { "name": "queryType", "in": "query", "description": "Filters results by DNS query type.", "schema": { "description": "Filters results by DNS query type.", "type": "array", "items": { "enum": [ "A", "AAAA", "A6", "AFSDB", "ANY", "APL", "ATMA", "AXFR", "CAA", "CDNSKEY", "CDS", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GPOS", "GID", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LOC", "LP", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NB", "NBSTAT", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSEC", "NSEC3", "NSEC3PARAM", "NULL", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SRV", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UINFO", "UID", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "nullable": true, "type": "string" } } }, { "name": "responseCode", "in": "query", "description": "Filters results by DNS response code.", "schema": { "description": "Filters results by DNS response code.", "type": "array", "items": { "enum": [ "NOERROR", "FORMERR", "SERVFAIL", "NXDOMAIN", "NOTIMP", "REFUSED", "YXDOMAIN", "YXRRSET", "NXRRSET", "NOTAUTH", "NOTZONE", "BADSIG", "BADKEY", "BADTIME", "BADMODE", "BADNAME", "BADALG", "BADTRUNC", "BADCOOKIE" ], "type": "string" } } }, { "name": "responseTtl", "in": "query", "description": "Filters results by DNS response TTL.", "schema": { "description": "Filters results by DNS response TTL.", "type": "array", "items": { "enum": [ "LTE_1M", "GT_1M_LTE_5M", "GT_5M_LTE_15M", "GT_15M_LTE_1H", "GT_1H_LTE_1D", "GT_1D_LTE_1W", "GT_1W" ], "type": "string" } } }, { "name": "dnssec", "in": "query", "description": "Filters results based on DNSSEC (DNS Security Extensions) support.", "schema": { "description": "Filters results based on DNSSEC (DNS Security Extensions) support.", "type": "array", "items": { "enum": [ "INVALID", "INSECURE", "SECURE", "OTHER" ], "type": "string" } } }, { "name": "dnssecAware", "in": "query", "description": "Filters results based on DNSSEC (DNS Security Extensions) client awareness.", "schema": { "description": "Filters results based on DNSSEC (DNS Security Extensions) client awareness.", "type": "array", "items": { "enum": [ "SUPPORTED", "NOT_SUPPORTED" ], "type": "string" } } }, { "name": "dnssecE2e", "in": "query", "description": "Filters results based on DNSSEC-validated answers by end-to-end security status.", "schema": { "description": "Filters results based on DNSSEC-validated answers by end-to-end security status.", "type": "array", "items": { "type": "boolean" } } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "matchingAnswer", "in": "query", "description": "Filters results based on whether the queries have a matching answer.", "schema": { "description": "Filters results based on whether the queries have a matching answer.", "type": "array", "items": { "type": "boolean" } } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "schema": { "description": "Filters results by top-level domain. Incompatible with the `ipVersion`, `protocol`, `dnssecE2e`, `dnssecAware`, `responseTtl`, and `cacheHit` filters/dimensions; this restriction does not apply to country-code TLDs (2-letter, e.g. `uk`).", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "PT" }, "clientCountryName": { "type": "string", "example": "Portugal" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryAlpha2", "clientCountryName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar DNS" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.dns.top", "x-fern-sdk-method-name": "locations", "x-forge-hidden": true } }, "/radar/email/routing/summary/arc": { "get": { "operationId": "radar-get-email-routing-summary-by-arc", "summary": "Get email ARC validation summary", "description": "Retrieves the distribution of emails by ARC (Authenticated Received Chain) validation.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "encrypted", "in": "query", "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "schema": { "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "type": "array", "items": { "enum": [ "ENCRYPTED", "NOT_ENCRYPTED" ], "type": "string" }, "example": "ENCRYPTED" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "FAIL": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "NONE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "PASS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "NONE", "PASS", "FAIL" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Routing" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.routing.summary", "x-fern-sdk-method-name": "arc", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Routing Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/routing/methods/summary_v2/) instead." } }, "/radar/email/routing/summary/dkim": { "get": { "operationId": "radar-get-email-routing-summary-by-dkim", "summary": "Get email DKIM validation summary", "description": "Retrieves the distribution of emails by DKIM (DomainKeys Identified Mail) validation.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "encrypted", "in": "query", "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "schema": { "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "type": "array", "items": { "enum": [ "ENCRYPTED", "NOT_ENCRYPTED" ], "type": "string" }, "example": "ENCRYPTED" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "FAIL": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "NONE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "PASS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "NONE", "PASS", "FAIL" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Routing" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.routing.summary", "x-fern-sdk-method-name": "dkim", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Routing Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/routing/methods/summary_v2/) instead." } }, "/radar/email/routing/summary/dmarc": { "get": { "operationId": "radar-get-email-routing-summary-by-dmarc", "summary": "Get email DMARC validation summary", "description": "Retrieves the distribution of emails by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "encrypted", "in": "query", "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "schema": { "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "type": "array", "items": { "enum": [ "ENCRYPTED", "NOT_ENCRYPTED" ], "type": "string" }, "example": "ENCRYPTED" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "FAIL": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "NONE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "PASS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "NONE", "PASS", "FAIL" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Routing" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.routing.summary", "x-fern-sdk-method-name": "dmarc", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Routing Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/routing/methods/summary_v2/) instead." } }, "/radar/email/routing/summary/encrypted": { "get": { "operationId": "radar-get-email-routing-summary-by-encrypted", "summary": "Get email encryption status summary", "description": "Retrieves the distribution of emails by encryption status (encrypted vs. not-encrypted).", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "ENCRYPTED": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "NOT_ENCRYPTED": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "ENCRYPTED", "NOT_ENCRYPTED" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Routing" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.routing.summary", "x-fern-sdk-method-name": "encrypted", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Routing Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/routing/methods/summary_v2/) instead." } }, "/radar/email/routing/summary/ip_version": { "get": { "operationId": "radar-get-email-routing-summary-by-ip-version", "summary": "Get email IP version summary", "description": "Retrieves the distribution of emails by IP version.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "encrypted", "in": "query", "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "schema": { "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "type": "array", "items": { "enum": [ "ENCRYPTED", "NOT_ENCRYPTED" ], "type": "string" }, "example": "ENCRYPTED" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "IPv4": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "IPv6": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "IPv4", "IPv6" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Routing" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.routing.summary", "x-fern-sdk-method-name": "ip-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Routing Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/routing/methods/summary_v2/) instead." } }, "/radar/email/routing/summary/spf": { "get": { "operationId": "radar-get-email-routing-summary-by-spf", "summary": "Get email SPF validation summary", "description": "Retrieves the distribution of emails by SPF (Sender Policy Framework) validation.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "encrypted", "in": "query", "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "schema": { "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "type": "array", "items": { "enum": [ "ENCRYPTED", "NOT_ENCRYPTED" ], "type": "string" }, "example": "ENCRYPTED" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "FAIL": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "NONE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "PASS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "NONE", "PASS", "FAIL" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Routing" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.routing.summary", "x-fern-sdk-method-name": "spf", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Routing Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/routing/methods/summary_v2/) instead." } }, "/radar/email/routing/summary/{dimension}": { "get": { "operationId": "radar-get-email-routing-summary", "summary": "Get email routing summary by dimension", "description": "Retrieves the distribution of email routing metrics by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "IP_VERSION", "ENCRYPTED", "ARC", "DKIM", "DMARC", "SPF" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "encrypted", "in": "query", "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "schema": { "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "type": "array", "items": { "enum": [ "ENCRYPTED", "NOT_ENCRYPTED" ], "type": "string" }, "example": "ENCRYPTED" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "FAIL": "25.084366", "PASS": "50.168733" }, "additionalProperties": { "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Routing" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.email.routing", "x-fern-sdk-method-name": "summary-v2", "x-forge-hidden": true } }, "/radar/email/routing/timeseries_groups/arc": { "get": { "operationId": "radar-get-email-routing-timeseries-group-by-arc", "summary": "Get email ARC validation time series", "description": "Retrieves the distribution of emails by ARC (Authenticated Received Chain) validation over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "encrypted", "in": "query", "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "schema": { "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "type": "array", "items": { "enum": [ "ENCRYPTED", "NOT_ENCRYPTED" ], "type": "string" }, "example": "ENCRYPTED" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "FAIL": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "NONE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "PASS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "NONE", "PASS", "FAIL" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Routing" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.routing.timeseries-groups", "x-fern-sdk-method-name": "arc", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Routing Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/routing/methods/timeseries_groups_v2/) instead." } }, "/radar/email/routing/timeseries_groups/dkim": { "get": { "operationId": "radar-get-email-routing-timeseries-group-by-dkim", "summary": "Get email DKIM validation time series", "description": "Retrieves the distribution of emails by DKIM (DomainKeys Identified Mail) validation over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "encrypted", "in": "query", "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "schema": { "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "type": "array", "items": { "enum": [ "ENCRYPTED", "NOT_ENCRYPTED" ], "type": "string" }, "example": "ENCRYPTED" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "FAIL": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "NONE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "PASS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "NONE", "PASS", "FAIL" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Routing" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.routing.timeseries-groups", "x-fern-sdk-method-name": "dkim", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Routing Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/routing/methods/timeseries_groups_v2/) instead." } }, "/radar/email/routing/timeseries_groups/dmarc": { "get": { "operationId": "radar-get-email-routing-timeseries-group-by-dmarc", "summary": "Get email DMARC validation time series", "description": "Retrieves the distribution of emails by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "encrypted", "in": "query", "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "schema": { "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "type": "array", "items": { "enum": [ "ENCRYPTED", "NOT_ENCRYPTED" ], "type": "string" }, "example": "ENCRYPTED" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "FAIL": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "NONE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "PASS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "NONE", "PASS", "FAIL" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Routing" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.routing.timeseries-groups", "x-fern-sdk-method-name": "dmarc", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Routing Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/routing/methods/timeseries_groups_v2/) instead." } }, "/radar/email/routing/timeseries_groups/encrypted": { "get": { "operationId": "radar-get-email-routing-timeseries-group-by-encrypted", "summary": "Get email encryption status time series", "description": "Retrieves the distribution of emails by encryption status (encrypted vs. not-encrypted) over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "ENCRYPTED": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "NOT_ENCRYPTED": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "ENCRYPTED", "NOT_ENCRYPTED" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Routing" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.routing.timeseries-groups", "x-fern-sdk-method-name": "encrypted", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Routing Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/routing/methods/timeseries_groups_v2/) instead." } }, "/radar/email/routing/timeseries_groups/ip_version": { "get": { "operationId": "radar-get-email-routing-timeseries-group-by-ip-version", "summary": "Get email IP version time series", "description": "Retrieves the distribution of emails by IP version over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "encrypted", "in": "query", "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "schema": { "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "type": "array", "items": { "enum": [ "ENCRYPTED", "NOT_ENCRYPTED" ], "type": "string" }, "example": "ENCRYPTED" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "IPv4": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "IPv6": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "IPv4", "IPv6" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Routing" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.routing.timeseries-groups", "x-fern-sdk-method-name": "ip-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Routing Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/routing/methods/timeseries_groups_v2/) instead." } }, "/radar/email/routing/timeseries_groups/spf": { "get": { "operationId": "radar-get-email-routing-timeseries-group-by-spf", "summary": "Get email SPF validation time series", "description": "Retrieves the distribution of emails by SPF (Sender Policy Framework) validation over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "encrypted", "in": "query", "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "schema": { "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "type": "array", "items": { "enum": [ "ENCRYPTED", "NOT_ENCRYPTED" ], "type": "string" }, "example": "ENCRYPTED" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "FAIL": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "NONE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "PASS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "NONE", "PASS", "FAIL" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Routing" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.routing.timeseries-groups", "x-fern-sdk-method-name": "spf", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Routing Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/routing/methods/timeseries_groups_v2/) instead." } }, "/radar/email/routing/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-email-routing-timeseries-group", "summary": "Get email routing time series grouped by dimension", "description": "Retrieves the distribution of email routing metrics grouped by dimension over time.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "IP_VERSION", "ENCRYPTED", "ARC", "DKIM", "DMARC", "SPF" ] } }, { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "encrypted", "in": "query", "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "schema": { "description": "Filters results by encryption status (encrypted vs. not-encrypted).", "type": "array", "items": { "enum": [ "ENCRYPTED", "NOT_ENCRYPTED" ], "type": "string" }, "example": "ENCRYPTED" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "PASS": [ "50.168733" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Routing" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.email.routing", "x-fern-sdk-method-name": "timeseries-groups-v2", "x-forge-hidden": true } }, "/radar/email/security/summary/arc": { "get": { "operationId": "radar-get-email-security-summary-by-arc", "summary": "Get email ARC validation summary", "description": "Retrieves the distribution of emails by ARC (Authenticated Received Chain) validation.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "FAIL": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "NONE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "PASS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "NONE", "PASS", "FAIL" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.summary", "x-fern-sdk-method-name": "arc", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/summary_v2/) instead." } }, "/radar/email/security/summary/dkim": { "get": { "operationId": "radar-get-email-security-summary-by-dkim", "summary": "Get email DKIM validation summary", "description": "Retrieves the distribution of emails by DKIM (DomainKeys Identified Mail) validation.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "FAIL": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "NONE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "PASS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "NONE", "PASS", "FAIL" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.summary", "x-fern-sdk-method-name": "dkim", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/summary_v2/) instead." } }, "/radar/email/security/summary/dmarc": { "get": { "operationId": "radar-get-email-security-summary-by-dmarc", "summary": "Get email DMARC validation summary", "description": "Retrieves the distribution of emails by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "FAIL": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "NONE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "PASS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "NONE", "PASS", "FAIL" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.summary", "x-fern-sdk-method-name": "dmarc", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/summary_v2/) instead." } }, "/radar/email/security/summary/malicious": { "get": { "operationId": "radar-get-email-security-summary-by-malicious", "summary": "Get email malicious classification summary", "description": "Retrieves the distribution of emails by malicious classification.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "MALICIOUS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "NOT_MALICIOUS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "MALICIOUS", "NOT_MALICIOUS" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.summary", "x-fern-sdk-method-name": "malicious", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/summary_v2/) instead." } }, "/radar/email/security/summary/spam": { "get": { "operationId": "radar-get-email-security-summary-by-spam", "summary": "Get email spam classification summary", "description": "Retrieves the proportion of emails by spam classification (spam vs. non-spam).", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "NOT_SPAM": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "SPAM": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "SPAM", "NOT_SPAM" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.summary", "x-fern-sdk-method-name": "spam", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/summary_v2/) instead." } }, "/radar/email/security/summary/spf": { "get": { "operationId": "radar-get-email-security-summary-by-spf", "summary": "Get email SPF validation summary", "description": "Retrieves the distribution of emails by SPF (Sender Policy Framework) validation.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "FAIL": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "NONE": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "PASS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "NONE", "PASS", "FAIL" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.summary", "x-fern-sdk-method-name": "spf", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/summary_v2/) instead." } }, "/radar/email/security/summary/spoof": { "get": { "operationId": "radar-get-email-security-summary-by-spoof", "summary": "Get email spoof classification summary", "description": "Retrieves the proportion of emails by spoof classification (spoof vs. non-spoof).", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "NOT_SPOOF": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "SPOOF": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "SPOOF", "NOT_SPOOF" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.summary", "x-fern-sdk-method-name": "spoof", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/summary_v2/) instead." } }, "/radar/email/security/summary/threat_category": { "get": { "operationId": "radar-get-email-security-summary-by-threat-category", "summary": "Get email threat category summary", "description": "Retrieves the distribution of emails by threat categories.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "BrandImpersonation": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "CredentialHarvester": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "IdentityDeception": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "Link": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "IdentityDeception", "Link", "BrandImpersonation", "CredentialHarvester" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.summary", "x-fern-sdk-method-name": "threat-category", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/summary_v2/) instead." } }, "/radar/email/security/summary/tls_version": { "get": { "operationId": "radar-get-email-security-summary-by-tls-version", "summary": "Get email TLS version summary", "description": "Retrieves the distribution of emails by TLS version.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "TLS 1.0": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "TLS 1.1": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "TLS 1.2": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "TLS 1.3": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "TLS 1.0", "TLS 1.1", "TLS 1.2", "TLS 1.3" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.summary", "x-fern-sdk-method-name": "tls-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/summary_v2/) instead." } }, "/radar/email/security/summary/{dimension}": { "get": { "operationId": "radar-get-email-security-summary", "summary": "Get email security summary by dimension", "description": "Retrieves the distribution of email security metrics by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "SPAM", "MALICIOUS", "SPOOF", "THREAT_CATEGORY", "ARC", "DKIM", "DMARC", "SPF", "TLS_VERSION" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "FAIL": "25.084366", "PASS": "50.168733" }, "additionalProperties": { "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.email.security", "x-fern-sdk-method-name": "summary-v2", "x-forge-hidden": true } }, "/radar/email/security/timeseries_groups/arc": { "get": { "operationId": "radar-get-email-security-timeseries-group-by-arc", "summary": "Get email ARC validation time series", "description": "Retrieves the distribution of emails by ARC (Authenticated Received Chain) validation over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "FAIL": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "NONE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "PASS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "NONE", "PASS", "FAIL" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.timeseries-groups", "x-fern-sdk-method-name": "arc", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/timeseries_groups_v2/) instead." } }, "/radar/email/security/timeseries_groups/dkim": { "get": { "operationId": "radar-get-email-security-timeseries-group-by-dkim", "summary": "Get email DKIM validation time series", "description": "Retrieves the distribution of emails by DKIM (DomainKeys Identified Mail) validation over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "FAIL": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "NONE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "PASS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "NONE", "PASS", "FAIL" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.timeseries-groups", "x-fern-sdk-method-name": "dkim", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/timeseries_groups_v2/) instead." } }, "/radar/email/security/timeseries_groups/dmarc": { "get": { "operationId": "radar-get-email-security-timeseries-group-by-dmarc", "summary": "Get email DMARC validation time series", "description": "Retrieves the distribution of emails by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "FAIL": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "NONE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "PASS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "NONE", "PASS", "FAIL" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.timeseries-groups", "x-fern-sdk-method-name": "dmarc", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/timeseries_groups_v2/) instead." } }, "/radar/email/security/timeseries_groups/malicious": { "get": { "operationId": "radar-get-email-security-timeseries-group-by-malicious", "summary": "Get email malicious classification time series", "description": "Retrieves the distribution of emails by malicious classification over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "MALICIOUS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "NOT_MALICIOUS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "MALICIOUS", "NOT_MALICIOUS" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.timeseries-groups", "x-fern-sdk-method-name": "malicious", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/timeseries_groups_v2/) instead." } }, "/radar/email/security/timeseries_groups/spam": { "get": { "operationId": "radar-get-email-security-timeseries-group-by-spam", "summary": "Get email spam classification time series", "description": "Retrieves the distribution of emails by spam classification (spam vs. non-spam) over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "NOT_SPAM": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "SPAM": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "SPAM", "NOT_SPAM" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.timeseries-groups", "x-fern-sdk-method-name": "spam", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/timeseries_groups_v2/) instead." } }, "/radar/email/security/timeseries_groups/spf": { "get": { "operationId": "radar-get-email-security-timeseries-group-by-spf", "summary": "Get email SPF validation time series", "description": "Retrieves the distribution of emails by SPF (Sender Policy Framework) validation over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "FAIL": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "NONE": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "PASS": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "NONE", "PASS", "FAIL" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.timeseries-groups", "x-fern-sdk-method-name": "spf", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/timeseries_groups_v2/) instead." } }, "/radar/email/security/timeseries_groups/spoof": { "get": { "operationId": "radar-get-email-security-timeseries-group-by-spoof", "summary": "Get email spoof classification time series", "description": "Retrieves the distribution of emails by spoof classification (spoof vs. non-spoof) over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "NOT_SPOOF": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "SPOOF": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "SPOOF", "NOT_SPOOF" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.timeseries-groups", "x-fern-sdk-method-name": "spoof", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/timeseries_groups_v2/) instead." } }, "/radar/email/security/timeseries_groups/threat_category": { "get": { "operationId": "radar-get-email-security-timeseries-group-by-threat-category", "summary": "Get email threat category time series", "description": "Retrieves the distribution of emails by threat category over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "BrandImpersonation": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "CredentialHarvester": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "IdentityDeception": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "Link": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "IdentityDeception", "Link", "BrandImpersonation", "CredentialHarvester" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.timeseries-groups", "x-fern-sdk-method-name": "threat-category", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/timeseries_groups_v2/) instead." } }, "/radar/email/security/timeseries_groups/tls_version": { "get": { "operationId": "radar-get-email-security-timeseries-group-by-tls-version", "summary": "Get email TLS version time series", "description": "Retrieves the distribution of emails by TLS version over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "TLS 1.0": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "TLS 1.1": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "TLS 1.2": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "TLS 1.3": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "TLS 1.0", "TLS 1.1", "TLS 1.2", "TLS 1.3" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.email.security.timeseries-groups", "x-fern-sdk-method-name": "tls-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Email Security Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/email/subresources/security/methods/timeseries_groups_v2/) instead." } }, "/radar/email/security/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-email-security-timeseries-group", "summary": "Get email security time series grouped by dimension", "description": "Retrieves the distribution of email security metrics grouped by dimension over time.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "SPAM", "MALICIOUS", "SPOOF", "THREAT_CATEGORY", "ARC", "DKIM", "DMARC", "SPF", "TLS_VERSION" ] } }, { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "PASS": [ "50.168733" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.email.security", "x-fern-sdk-method-name": "timeseries-groups-v2", "x-forge-hidden": true } }, "/radar/email/security/top/tlds": { "get": { "operationId": "radar-get-email-security-top-tlds-by-messages", "summary": "Get top TLDs by email message volume", "description": "Retrieves the top TLDs by number of email messages.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "tldCategory", "in": "query", "description": "Filters results by TLD category.", "schema": { "description": "Filters results by TLD category.", "type": "string", "example": "CLASSIC", "enum": [ "CLASSIC", "COUNTRY" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "com." }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.email.security.top.tlds", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/email/security/top/tlds/malicious/{malicious}": { "get": { "operationId": "radar-get-email-security-top-tlds-by-malicious", "summary": "Get top TLDs by email malicious classification", "description": "Retrieves the top TLDs by emails classified as malicious or not.", "parameters": [ { "name": "malicious", "in": "path", "description": "Malicious classification.", "required": true, "schema": { "description": "Malicious classification.", "type": "string", "example": "MALICIOUS", "enum": [ "MALICIOUS", "NOT_MALICIOUS" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "tldCategory", "in": "query", "description": "Filters results by TLD category.", "schema": { "description": "Filters results by TLD category.", "type": "string", "example": "CLASSIC", "enum": [ "CLASSIC", "COUNTRY" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "com." }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.email.security.top.tlds.malicious", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/email/security/top/tlds/spam/{spam}": { "get": { "operationId": "radar-get-email-security-top-tlds-by-spam", "summary": "Get top TLDs by email spam classification", "description": "Retrieves the top TLDs by emails classified as spam or not.", "parameters": [ { "name": "spam", "in": "path", "description": "Spam classification.", "required": true, "schema": { "description": "Spam classification.", "type": "string", "example": "SPAM", "enum": [ "SPAM", "NOT_SPAM" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "tldCategory", "in": "query", "description": "Filters results by TLD category.", "schema": { "description": "Filters results by TLD category.", "type": "string", "example": "CLASSIC", "enum": [ "CLASSIC", "COUNTRY" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "com." }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.email.security.top.tlds.spam", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/email/security/top/tlds/spoof/{spoof}": { "get": { "operationId": "radar-get-email-security-top-tlds-by-spoof", "summary": "Get top TLDs by email spoof classification", "description": "Retrieves the top TLDs by emails classified as spoof or not.", "parameters": [ { "name": "spoof", "in": "path", "description": "Spoof classification.", "required": true, "schema": { "description": "Spoof classification.", "type": "string", "example": "SPOOF", "enum": [ "SPOOF", "NOT_SPOOF" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "arc", "in": "query", "description": "Filters results by ARC (Authenticated Received Chain) validation.", "schema": { "description": "Filters results by ARC (Authenticated Received Chain) validation.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dkim", "in": "query", "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "schema": { "description": "Filters results by DKIM (DomainKeys Identified Mail) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "dmarc", "in": "query", "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "schema": { "description": "Filters results by DMARC (Domain-based Message Authentication, Reporting and Conformance) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "spf", "in": "query", "description": "Filters results by SPF (Sender Policy Framework) validation status.", "schema": { "description": "Filters results by SPF (Sender Policy Framework) validation status.", "type": "array", "items": { "enum": [ "PASS", "NONE", "FAIL" ], "type": "string" }, "example": "PASS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "tldCategory", "in": "query", "description": "Filters results by TLD category.", "schema": { "description": "Filters results by TLD category.", "type": "string", "example": "CLASSIC", "enum": [ "CLASSIC", "COUNTRY" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "com." }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Email Security" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.email.security.top.tlds.spoof", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/entities/asns": { "get": { "operationId": "radar-get-entities-asn-list", "summary": "List autonomous systems", "description": "Retrieves a list of autonomous systems.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Skips the specified number of objects before fetching the results.", "schema": { "description": "Skips the specified number of objects before fetching the results.", "type": "integer", "minimum": 0 } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list.", "type": "string", "example": "174,7922" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify an alpha-2 location code.", "schema": { "description": "Filters results by location. Specify an alpha-2 location code.", "type": "string", "example": "US", "maxLength": 2, "minLength": 2 } }, { "name": "orderBy", "in": "query", "description": "Specifies the metric to order the ASNs by.", "schema": { "description": "Specifies the metric to order the ASNs by.", "type": "string", "default": "ASN", "enum": [ "ASN", "POPULATION" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "asns": { "type": "array", "items": { "properties": { "aka": { "type": "string" }, "asn": { "type": "integer", "example": 714 }, "country": { "type": "string", "example": "GB" }, "countryName": { "type": "string", "example": "United Kingdom" }, "estimatedUsers": { "type": "object", "properties": { "estimatedUsers": { "description": "Total estimated users.", "type": "integer", "example": 86099 } } }, "name": { "type": "string", "example": "Apple Inc." }, "orgName": { "type": "string" }, "website": { "type": "string", "example": "https://www.apple.com/support/systemstatus/" } }, "required": [ "name", "asn", "country", "countryName", "estimatedUsers" ], "type": "object" } } }, "required": [ "asns" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Autonomous Systems" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.entities.asns", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/radar/entities/asns/botnet_threat_feed": { "get": { "operationId": "radar-get-as-botnet-threat-feed", "summary": "Get AS rankings by botnet threat feed activity", "description": "Retrieves a ranked list of Autonomous Systems based on their presence in the Cloudflare Botnet Threat Feed. Rankings can be sorted by offense count or number of bad IPs. Optionally compare to a previous date to see rank changes.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Skips the specified number of objects before fetching the results.", "schema": { "description": "Skips the specified number of objects before fetching the results.", "type": "integer", "minimum": 0 } }, { "name": "metric", "in": "query", "description": "Metric to rank ASNs by.", "schema": { "description": "Metric to rank ASNs by.", "type": "string", "default": "NUMBER_OF_OFFENDING_IPS", "enum": [ "OFFENSE_COUNT", "NUMBER_OF_OFFENDING_IPS" ] } }, { "name": "date", "in": "query", "description": "The date to retrieve (YYYY-MM-DD format). If not specified, returns the most recent available data. Note: This is the date the report was generated. The report is generated from information collected from the previous day (e.g., the 2026-02-23 entry contains data from 2026-02-22).", "schema": { "description": "The date to retrieve (YYYY-MM-DD format). If not specified, returns the most recent available data. Note: This is the date the report was generated. The report is generated from information collected from the previous day (e.g., the 2026-02-23 entry contains data from 2026-02-22).", "type": "string", "format": "date", "example": "2026-02-04" } }, { "name": "compareDateRange", "in": "query", "description": "Relative date range for rank change comparison (e.g., \"1d\", \"7d\", \"30d\").", "schema": { "description": "Relative date range for rank change comparison (e.g., \"1d\", \"7d\", \"30d\").", "type": "string", "example": "7d", "pattern": "^([1-9][0-9]?|[1-9][0-9]{1,2}|3[0-5][0-9]|36[0-4])d|([1-9]|[1-4][0-9]|5[0-2])w$" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify an alpha-2 location code.", "schema": { "description": "Filters results by location. Specify an alpha-2 location code.", "type": "string", "example": "US", "maxLength": 2, "minLength": 2 } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "sortOrder", "in": "query", "description": "Sort order.", "schema": { "description": "Sort order.", "type": "string", "example": "desc", "enum": [ "ASC", "DESC" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "ases": { "type": "array", "items": { "properties": { "asn": { "type": "integer", "example": 4134 }, "country": { "type": "string", "example": "CN" }, "name": { "type": "string", "example": "CHINANET-BACKBONE" }, "rank": { "type": "integer", "example": 1 }, "rankChange": { "type": "integer", "example": -2 } }, "required": [ "asn", "name", "country", "rank" ], "type": "object" } }, "meta": { "type": "object", "properties": { "compareDate": { "type": "string", "example": "2026-01-28T00:00:00Z" }, "date": { "type": "string", "example": "2026-02-04T00:00:00Z" }, "total": { "type": "integer", "example": 50 } }, "required": [ "date", "total" ] } }, "required": [ "ases", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Autonomous Systems" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.entities.asns", "x-fern-sdk-method-name": "botnet-threat-feed", "x-forge-hidden": true } }, "/radar/entities/asns/ip": { "get": { "operationId": "radar-get-entities-asn-by-ip", "summary": "Get AS details by IP address", "description": "Retrieves the requested autonomous system information based on IP address. Population estimates come from APNIC (refer to https://labs.apnic.net/?p=526).", "parameters": [ { "name": "ip", "in": "query", "description": "IP address.", "required": true, "schema": { "description": "IP address.", "type": "string", "format": "ip", "example": "8.8.8.8" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "asn": { "type": "object", "properties": { "aka": { "type": "string" }, "asn": { "type": "integer", "example": 714 }, "country": { "type": "string", "example": "GB" }, "countryName": { "type": "string", "example": "United Kingdom" }, "estimatedUsers": { "type": "object", "properties": { "estimatedUsers": { "description": "Total estimated users.", "type": "integer", "example": 86099 }, "locations": { "type": "array", "items": { "properties": { "estimatedUsers": { "description": "Estimated users per location.", "type": "integer", "example": 16710 }, "locationAlpha2": { "type": "string", "example": "US" }, "locationName": { "type": "string", "example": "United States" } }, "required": [ "locationName", "locationAlpha2" ], "type": "object" } } }, "required": [ "locations" ] }, "name": { "type": "string", "example": "Apple Inc." }, "orgName": { "type": "string" }, "related": { "type": "array", "items": { "properties": { "aka": { "type": "string" }, "asn": { "type": "integer" }, "estimatedUsers": { "description": "Total estimated users.", "type": "integer", "example": 65345 }, "name": { "type": "string" } }, "required": [ "name", "asn" ], "type": "object" } }, "source": { "description": "Regional Internet Registry.", "type": "string", "example": "RIPE" }, "website": { "type": "string", "example": "https://www.apple.com/support/systemstatus/" } }, "required": [ "name", "country", "countryName", "related", "asn", "website", "orgName", "source", "estimatedUsers" ] } }, "required": [ "asn" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Autonomous Systems" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.entities.asns", "x-fern-sdk-method-name": "ip", "x-forge-hidden": true } }, "/radar/entities/asns/{asn}": { "get": { "operationId": "radar-get-entities-asn-by-id", "summary": "Get AS details by ASN", "description": "Retrieves the requested autonomous system information. (A confidence level below `5` indicates a low level of confidence in the traffic data - normally this happens because Cloudflare has a small amount of traffic from/to this AS). Population estimates come from APNIC (refer to https://labs.apnic.net/?p=526).", "parameters": [ { "name": "asn", "in": "path", "description": "Single Autonomous System Number (ASN) as integer.", "required": true, "schema": { "description": "Single Autonomous System Number (ASN) as integer.", "type": "integer", "example": 174 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "asn": { "type": "object", "properties": { "aka": { "type": "string" }, "asn": { "type": "integer", "example": 714 }, "confidenceLevel": { "type": "integer", "example": 5 }, "country": { "type": "string", "example": "GB" }, "countryName": { "type": "string", "example": "United Kingdom" }, "estimatedUsers": { "type": "object", "properties": { "estimatedUsers": { "description": "Total estimated users.", "type": "integer", "example": 86099 }, "locations": { "type": "array", "items": { "properties": { "estimatedUsers": { "description": "Estimated users per location.", "type": "integer", "example": 16710 }, "locationAlpha2": { "type": "string", "example": "US" }, "locationName": { "type": "string", "example": "United States" } }, "required": [ "locationName", "locationAlpha2" ], "type": "object" } } }, "required": [ "locations" ] }, "name": { "type": "string", "example": "Apple Inc." }, "orgName": { "type": "string" }, "related": { "type": "array", "items": { "properties": { "aka": { "type": "string" }, "asn": { "type": "integer", "example": 174 }, "estimatedUsers": { "description": "Total estimated users.", "type": "integer", "example": 65345 }, "name": { "type": "string", "example": "Cogent-174" } }, "required": [ "name", "asn" ], "type": "object" } }, "source": { "description": "Regional Internet Registry.", "type": "string", "example": "RIPE" }, "website": { "type": "string", "example": "https://www.apple.com/support/systemstatus/" } }, "required": [ "name", "country", "countryName", "confidenceLevel", "related", "source", "asn", "website", "orgName", "estimatedUsers" ] } }, "required": [ "asn" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Autonomous Systems" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.entities.asns", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/entities/asns/{asn}/as_set": { "get": { "operationId": "radar-get-asns-as-set", "summary": "Get IRR AS-SETs that an AS is a member of", "description": "Retrieves Internet Routing Registry AS-SETs that an AS is a member of.", "parameters": [ { "name": "asn", "in": "path", "description": "Retrieves all AS-SETs that the given AS is a member of.", "required": true, "schema": { "description": "Retrieves all AS-SETs that the given AS is a member of.", "type": "integer", "example": 3 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "as_sets": { "type": "array", "items": { "properties": { "as_members_count": { "description": "The number of AS members in the AS-SET", "type": "integer" }, "as_set_members_count": { "description": "The number of AS-SET members in the AS-SET", "type": "integer" }, "as_set_upstreams_count": { "description": "The number of recursive upstream AS-SETs", "type": "integer" }, "asn_cone_size": { "description": "The number of unique ASNs in the AS-SETs recursive downstream", "type": "integer" }, "hierarchical_asn": { "description": "The AS number following hierarchical AS-SET name", "type": "integer" }, "inferred_asn": { "description": "The inferred AS number of the AS-SET", "type": "integer" }, "irr_sources": { "description": "The IRR sources of the AS-SET", "type": "array", "items": { "type": "string" } }, "name": { "description": "The name of the AS-SET", "type": "string" }, "peeringdb_asn": { "description": "The AS number matching PeeringDB record", "type": "integer" } }, "required": [ "name", "as_members_count", "as_set_members_count", "irr_sources", "asn_cone_size", "as_set_upstreams_count" ], "type": "object" } }, "paths": { "description": "Paths from the AS-SET that include the given AS to its upstreams recursively", "type": "array", "items": { "items": { "type": "string" }, "type": "array" } } }, "required": [ "as_sets", "paths" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Autonomous Systems" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.entities.asns", "x-fern-sdk-method-name": "as-set", "x-forge-hidden": true } }, "/radar/entities/asns/{asn}/rel": { "get": { "operationId": "radar-get-asns-rel", "summary": "Get AS-level relationships by ASN", "description": "Retrieves AS-level relationship for given networks.", "parameters": [ { "name": "asn", "in": "path", "description": "Retrieves all ASNs with provider-customer or peering relationships with the given ASN.", "required": true, "schema": { "description": "Retrieves all ASNs with provider-customer or peering relationships with the given ASN.", "type": "integer", "example": 3 } }, { "name": "asn2", "in": "query", "description": "Retrieves the AS relationship of ASN2 with respect to the given ASN.", "schema": { "description": "Retrieves the AS relationship of ASN2 with respect to the given ASN.", "type": "integer" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "data_time": { "type": "string" }, "query_time": { "type": "string" }, "total_peers": { "type": "integer" } }, "required": [ "data_time", "query_time", "total_peers" ] }, "rels": { "type": "array", "items": { "properties": { "asn1": { "type": "integer" }, "asn1_country": { "type": "string" }, "asn1_name": { "type": "string" }, "asn2": { "type": "integer" }, "asn2_country": { "type": "string" }, "asn2_name": { "type": "string" }, "rel": { "type": "string" } }, "required": [ "asn1", "asn1_country", "asn1_name", "asn2", "asn2_country", "asn2_name", "rel" ], "type": "object" } } }, "required": [ "rels", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Autonomous Systems" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.entities.asns", "x-fern-sdk-method-name": "rel", "x-forge-hidden": true } }, "/radar/entities/ip": { "get": { "operationId": "radar-get-entities-ip", "summary": "Get IP address details", "description": "Retrieves IP address information.", "parameters": [ { "name": "ip", "in": "query", "description": "IP address.", "required": true, "schema": { "description": "IP address.", "type": "string", "format": "ip", "example": "8.8.8.8" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "ip": { "type": "object", "properties": { "asn": { "type": "string", "example": "15169" }, "asnLocation": { "type": "string", "example": "US" }, "asnName": { "type": "string", "example": "GOOGLE" }, "asnOrgName": { "type": "string", "example": "Google LLC" }, "ip": { "type": "string", "example": "8.8.8.8" }, "ipVersion": { "type": "string", "example": "IPv4" }, "location": { "type": "string", "example": "GB" }, "locationName": { "type": "string", "example": "United Kingdom" } }, "required": [ "ip", "ipVersion", "location", "locationName", "asn", "asnName", "asnLocation", "asnOrgName" ] } }, "required": [ "ip" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar IP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.entities", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/entities/locations": { "get": { "operationId": "radar-get-entities-locations", "summary": "List locations", "description": "Retrieves a list of locations.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Skips the specified number of objects before fetching the results.", "schema": { "description": "Skips the specified number of objects before fetching the results.", "type": "integer", "minimum": 0 } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 location codes.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 location codes.", "type": "string", "example": "US,CA" } }, { "name": "region", "in": "query", "description": "Filters results by region.", "schema": { "description": "Filters results by region.", "type": "string", "example": "Middle East", "maxLength": 100 } }, { "name": "subregion", "in": "query", "description": "Filters results by subregion.", "schema": { "description": "Filters results by subregion.", "type": "string", "example": "Southern Europe", "maxLength": 100 } }, { "name": "continent", "in": "query", "description": "Filters results by continent code.", "schema": { "description": "Filters results by continent code.", "type": "string", "example": "EU", "enum": [ "AF", "AS", "EU", "NA", "OC", "SA" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "locations": { "type": "array", "items": { "properties": { "alpha2": { "type": "string", "example": "AF" }, "continent": { "type": "string", "example": "AS" }, "latitude": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "longitude": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "name": { "type": "string", "example": "Afghanistan" }, "region": { "type": "string", "example": "Middle East" }, "subregion": { "type": "string", "example": "Southern Asia" } }, "required": [ "name", "region", "subregion", "continent", "latitude", "longitude", "alpha2" ], "type": "object" } } }, "required": [ "locations" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Locations" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.entities.locations", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/radar/entities/locations/{location}": { "get": { "operationId": "radar-get-entities-location-by-alpha2", "summary": "Get location details", "description": "Retrieves the requested location information. (A confidence level below `5` indicates a low level of confidence in the traffic data - normally this happens because Cloudflare has a small amount of traffic from/to this location).", "parameters": [ { "name": "location", "in": "path", "description": "Location alpha-2 code.", "required": true, "schema": { "description": "Location alpha-2 code.", "type": "string", "example": "US", "maxLength": 2, "minLength": 2 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "location": { "type": "object", "properties": { "alpha2": { "type": "string", "example": "AF" }, "confidenceLevel": { "type": "integer", "example": 5 }, "continent": { "type": "string", "example": "AS" }, "latitude": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "longitude": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "name": { "type": "string", "example": "Afghanistan" }, "region": { "type": "string", "example": "Middle East" }, "subregion": { "type": "string", "example": "Southern Asia" } }, "required": [ "name", "region", "subregion", "continent", "latitude", "longitude", "alpha2", "confidenceLevel" ] } }, "required": [ "location" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Locations" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.entities.locations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/geolocations": { "get": { "operationId": "radar-get-geolocations", "summary": "List Geolocations", "description": "Retrieves a list of geolocations. Geolocation names can be localized by sending an `Accept-Language` HTTP header with a BCP 47 language tag (e.g., `Accept-Language: pt-PT`). The full quality-value chain is supported (e.g., `pt-PT,pt;q=0.9,en;q=0.8`).", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Skips the specified number of objects before fetching the results.", "schema": { "description": "Skips the specified number of objects before fetching the results.", "type": "integer", "minimum": 0 } }, { "name": "geoId", "in": "query", "description": "Filters results by geolocation. Specify a comma-separated list of GeoNames IDs.", "schema": { "description": "Filters results by geolocation. Specify a comma-separated list of GeoNames IDs.", "type": "string", "example": "3190509,360689" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 location codes.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 location codes.", "type": "string", "example": "US,CA" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "geolocations": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "PT-11" }, "geoId": { "type": "string", "example": "2267056" }, "latitude": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "locale": { "description": "BCP 47 locale code used for the geolocation name translation", "type": "string", "example": "pt-PT" }, "longitude": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "name": { "type": "string", "example": "Lisbon" }, "parent": { "type": "object", "properties": { "code": { "type": "string", "example": "PT-11" }, "geoId": { "type": "string", "example": "2267056" }, "latitude": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "locale": { "description": "BCP 47 locale code used for the geolocation name translation", "type": "string", "example": "pt-PT" }, "longitude": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "name": { "type": "string", "example": "Lisbon" }, "parent": { "type": "object", "properties": { "code": { "type": "string", "example": "PT-11" }, "geoId": { "type": "string", "example": "2267056" }, "latitude": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "locale": { "description": "BCP 47 locale code used for the geolocation name translation", "type": "string", "example": "pt-PT" }, "longitude": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "name": { "type": "string", "example": "Lisbon" }, "type": { "description": "The type of the geolocation.", "type": "string", "enum": [ "CONTINENT", "COUNTRY", "ADM1" ] } }, "required": [ "geoId", "name", "type", "latitude", "longitude" ] }, "type": { "description": "The type of the geolocation.", "type": "string", "enum": [ "CONTINENT", "COUNTRY", "ADM1" ] } }, "required": [ "geoId", "name", "type", "latitude", "longitude", "parent" ] }, "type": { "description": "The type of the geolocation.", "type": "string", "enum": [ "CONTINENT", "COUNTRY", "ADM1" ] } }, "required": [ "geoId", "name", "type", "latitude", "longitude", "parent" ], "type": "object" } } }, "required": [ "geolocations" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Geolocations" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.geolocations", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/radar/geolocations/{geo_id}": { "get": { "operationId": "radar-get-geolocation-details", "summary": "Get Geolocation details", "description": "Retrieves the requested Geolocation information. Geolocation names can be localized by sending an `Accept-Language` HTTP header with a BCP 47 language tag (e.g., `Accept-Language: pt-PT`). The full quality-value chain is supported (e.g., `pt-PT,pt;q=0.9,en;q=0.8`).", "parameters": [ { "name": "geo_id", "in": "path", "description": "Geolocation ID. Refer to [GeoNames](https://download.geonames.org/export/dump/readme.txt)", "required": true, "schema": { "description": "Geolocation ID. Refer to [GeoNames](https://download.geonames.org/export/dump/readme.txt)", "type": "string", "example": "3190509", "maxLength": 100 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "geolocation": { "type": "object", "properties": { "code": { "type": "string", "example": "PT-11" }, "geoId": { "type": "string", "example": "2267056" }, "latitude": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "locale": { "description": "BCP 47 locale code used for the geolocation name translation", "type": "string", "example": "pt-PT" }, "longitude": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "name": { "type": "string", "example": "Lisbon" }, "parent": { "type": "object", "properties": { "code": { "type": "string", "example": "PT-11" }, "geoId": { "type": "string", "example": "2267056" }, "latitude": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "locale": { "description": "BCP 47 locale code used for the geolocation name translation", "type": "string", "example": "pt-PT" }, "longitude": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "name": { "type": "string", "example": "Lisbon" }, "parent": { "type": "object", "properties": { "code": { "type": "string", "example": "PT-11" }, "geoId": { "type": "string", "example": "2267056" }, "latitude": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "locale": { "description": "BCP 47 locale code used for the geolocation name translation", "type": "string", "example": "pt-PT" }, "longitude": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "name": { "type": "string", "example": "Lisbon" }, "type": { "description": "The type of the geolocation.", "type": "string", "enum": [ "CONTINENT", "COUNTRY", "ADM1" ] } }, "required": [ "geoId", "name", "type", "latitude", "longitude" ] }, "type": { "description": "The type of the geolocation.", "type": "string", "enum": [ "CONTINENT", "COUNTRY", "ADM1" ] } }, "required": [ "geoId", "name", "type", "latitude", "longitude", "parent" ] }, "type": { "description": "The type of the geolocation.", "type": "string", "enum": [ "CONTINENT", "COUNTRY", "ADM1" ] } }, "required": [ "geoId", "name", "type", "latitude", "longitude", "parent" ] } }, "required": [ "geolocation" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Geolocations" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.geolocations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/summary/bot_class": { "get": { "operationId": "radar-get-http-summary-by-bot-class", "summary": "Get HTTP requests by bot class summary", "description": "Retrieves the distribution of bot-generated HTTP requests to genuine human traffic, as classified by Cloudflare. Visit https://developers.cloudflare.com/radar/concepts/bot-classes/ for more information.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "bot": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "human": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "human", "bot" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.summary", "x-fern-sdk-method-name": "bot-class", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/summary_v2/) instead." } }, "/radar/http/summary/device_type": { "get": { "operationId": "radar-get-http-summary-by-device-type", "summary": "Get HTTP requests by device type summary", "description": "Retrieves the distribution of HTTP requests generated by mobile, desktop, and other types of devices.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "desktop": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "mobile": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "other": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "desktop", "mobile", "other" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.summary", "x-fern-sdk-method-name": "device-type", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/summary_v2/) instead." } }, "/radar/http/summary/http_protocol": { "get": { "operationId": "radar-get-http-summary-by-http-protocol", "summary": "Get HTTP requests by HTTP/HTTPS summary", "description": "Retrieves the distribution of HTTP requests by HTTP protocol (HTTP vs. HTTPS).", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "http": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "https": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "http", "https" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.summary", "x-fern-sdk-method-name": "http-protocol", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/summary_v2/) instead." } }, "/radar/http/summary/http_version": { "get": { "operationId": "radar-get-http-summary-by-http-version", "summary": "Get HTTP requests by HTTP version summary", "description": "Retrieves the distribution of HTTP requests by HTTP version.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "HTTP/1.x": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "HTTP/2": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "HTTP/3": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "HTTP/1.x", "HTTP/2", "HTTP/3" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.summary", "x-fern-sdk-method-name": "http-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/summary_v2/) instead." } }, "/radar/http/summary/ip_version": { "get": { "operationId": "radar-get-http-summary-by-ip-version", "summary": "Get HTTP requests by IP version summary", "description": "Retrieves the distribution of HTTP requests by IP version.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "IPv4": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "IPv6": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "IPv4", "IPv6" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.summary", "x-fern-sdk-method-name": "ip-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/summary_v2/) instead." } }, "/radar/http/summary/os": { "get": { "operationId": "radar-get-http-summary-by-operating-system", "summary": "Get HTTP requests by OS summary", "description": "Retrieves the distribution of HTTP requests by operating system (Windows, macOS, Android, iOS, and others).", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "ANDROID": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "IOS": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "ANDROID", "IOS" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.summary", "x-fern-sdk-method-name": "os", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/summary_v2/) instead." } }, "/radar/http/summary/post_quantum": { "get": { "operationId": "radar-get-http-summary-by-post-quantum", "summary": "Get HTTP requests by post-quantum support summary", "description": "Retrieves the distribution of HTTP requests by post-quantum support.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "NOT_SUPPORTED": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "SUPPORTED": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "SUPPORTED", "NOT_SUPPORTED" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.summary", "x-fern-sdk-method-name": "post-quantum", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/summary_v2/) instead." } }, "/radar/http/summary/tls_version": { "get": { "operationId": "radar-get-http-summary-by-tls-version", "summary": "Get HTTP requests by TLS version summary", "description": "Retrieves the distribution of HTTP requests by TLS version.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "TLS 1.0": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "TLS 1.1": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "TLS 1.2": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "TLS 1.3": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "TLS QUIC": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "TLS 1.0", "TLS 1.1", "TLS 1.2", "TLS 1.3", "TLS QUIC" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.summary", "x-fern-sdk-method-name": "tls-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/summary_v2/) instead." } }, "/radar/http/summary/{dimension}": { "get": { "operationId": "radar-get-http-summary", "summary": "Get HTTP requests summary by dimension", "description": "Retrieves the distribution of HTTP requests by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the HTTP attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the HTTP attribute by which to group the results.", "type": "string", "enum": [ "ADM1", "API_TRAFFIC", "AS", "BOT_CLASS", "BROWSER", "BROWSER_FAMILY", "CONTENT_TYPE", "DEVICE_TYPE", "HTTP_PROTOCOL", "HTTP_VERSION", "IP_VERSION", "LOCATION", "OS", "POST_QUANTUM", "TLS_VERSION" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "apiTraffic", "in": "query", "description": "Filters results by API traffic classification. API traffic is identified by JSON or XML response content types on dynamic (non-cacheable) HTTP requests. Incompatible with the `browserFamily`, `deviceType`, `httpProtocol`, `httpVersion`, `ipVersion`, `os`, and `tlsVersion` filters/dimensions. When set, results can only be further filtered by location, continent, or Autonomous System.", "schema": { "description": "Filters results by API traffic classification. API traffic is identified by JSON or XML response content types on dynamic (non-cacheable) HTTP requests. Incompatible with the `browserFamily`, `deviceType`, `httpProtocol`, `httpVersion`, `ipVersion`, `os`, and `tlsVersion` filters/dimensions. When set, results can only be further filtered by location, continent, or Autonomous System.", "type": "array", "items": { "enum": [ "API", "NON_API" ], "type": "string" }, "example": "API" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "contentType", "in": "query", "description": "Filters results by content type category. When set, results can only be further filtered by location, continent, or Autonomous System.", "schema": { "description": "Filters results by content type category. When set, results can only be further filtered by location, continent, or Autonomous System.", "type": "array", "items": { "enum": [ "HTML", "IMAGES", "JSON", "JAVASCRIPT", "CSS", "PLAIN_TEXT", "FONTS", "XML", "YAML", "VIDEO", "AUDIO", "MARKDOWN", "DOCUMENTS", "BINARY", "SERIALIZATION", "OTHER" ], "type": "string" } } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "Chrome": "50.168733", "Firefox": "25.084366" }, "additionalProperties": { "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http", "x-fern-sdk-method-name": "summary-v2", "x-forge-hidden": true } }, "/radar/http/timeseries": { "get": { "operationId": "radar-get-http-timeseries", "summary": "Get HTTP requests time series", "description": "Retrieves the HTTP requests over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `PERCENTAGE_CHANGE` requires exactly one comparison series (e.g. a `control` date range).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `PERCENTAGE_CHANGE` requires exactly one comparison series (e.g. a `control` date range).", "type": "string", "example": "MIN0_MAX", "enum": [ "PERCENTAGE_CHANGE", "MIN0_MAX" ] } }, { "name": "apiTraffic", "in": "query", "description": "Filters results by API traffic classification. API traffic is identified by JSON or XML response content types on dynamic (non-cacheable) HTTP requests. Incompatible with the `browserFamily`, `deviceType`, `httpProtocol`, `httpVersion`, `ipVersion`, `os`, and `tlsVersion` filters/dimensions. When set, results can only be further filtered by location, continent, or Autonomous System.", "schema": { "description": "Filters results by API traffic classification. API traffic is identified by JSON or XML response content types on dynamic (non-cacheable) HTTP requests. Incompatible with the `browserFamily`, `deviceType`, `httpProtocol`, `httpVersion`, `ipVersion`, `os`, and `tlsVersion` filters/dimensions. When set, results can only be further filtered by location, continent, or Autonomous System.", "type": "array", "items": { "enum": [ "API", "NON_API" ], "type": "string" }, "example": "API" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "contentType", "in": "query", "description": "Filters results by content type category. When set, results can only be further filtered by location, continent, or Autonomous System.", "schema": { "description": "Filters results by content type category. When set, results can only be further filtered by location, continent, or Autonomous System.", "type": "array", "items": { "enum": [ "HTML", "IMAGES", "JSON", "JAVASCRIPT", "CSS", "PLAIN_TEXT", "FONTS", "XML", "YAML", "VIDEO", "AUDIO", "MARKDOWN", "DOCUMENTS", "BINARY", "SERIALIZATION", "OTHER" ], "type": "string" } } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "additionalProperties": { "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } }, "values": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "timestamps", "values" ], "type": "object" }, "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] } }, "required": [ "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http", "x-fern-sdk-method-name": "timeseries", "x-forge-hidden": true } }, "/radar/http/timeseries_groups/bot_class": { "get": { "operationId": "radar-get-http-timeseries-group-by-bot-class", "summary": "Get HTTP requests by bot class time series", "description": "Retrieves the distribution of HTTP requests classified as automated or human over time. Visit https://developers.cloudflare.com/radar/concepts/bot-classes/ for more information.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "bot": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "human": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "human", "bot" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.timeseries-groups", "x-fern-sdk-method-name": "bot-class", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/timeseries_groups_v2/) instead." } }, "/radar/http/timeseries_groups/browser": { "get": { "operationId": "radar-get-http-timeseries-group-by-browsers", "summary": "Get HTTP requests by user agent time series", "description": "Retrieves the distribution of HTTP requests by user agent over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "Chrome": [ "50.168733" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.timeseries-groups", "x-fern-sdk-method-name": "browser", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/timeseries_groups_v2/) instead." } }, "/radar/http/timeseries_groups/browser_family": { "get": { "operationId": "radar-get-http-timeseries-group-by-browser-families", "summary": "Get HTTP requests by user agent family time series", "description": "Retrieves the distribution of HTTP requests by user agent family over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "Chrome": [ "50.168733" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.timeseries-groups", "x-fern-sdk-method-name": "browser-family", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/timeseries_groups_v2/) instead." } }, "/radar/http/timeseries_groups/device_type": { "get": { "operationId": "radar-get-http-timeseries-group-by-device-type", "summary": "Get HTTP requests by device type time series", "description": "Retrieves the distribution of HTTP requests by device type over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "desktop": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "mobile": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "other": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "desktop", "mobile", "other" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.timeseries-groups", "x-fern-sdk-method-name": "device-type", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/timeseries_groups_v2/) instead." } }, "/radar/http/timeseries_groups/http_protocol": { "get": { "operationId": "radar-get-http-timeseries-group-by-http-protocol", "summary": "Get HTTP requests by HTTP/HTTPS time series", "description": "Retrieves the distribution of HTTP requests by HTTP protocol (HTTP vs. HTTPS) over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "http": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "https": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "http", "https" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.timeseries-groups", "x-fern-sdk-method-name": "http-protocol", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/timeseries_groups_v2/) instead." } }, "/radar/http/timeseries_groups/http_version": { "get": { "operationId": "radar-get-http-timeseries-group-by-http-version", "summary": "Get HTTP requests by HTTP version time series", "description": "Retrieves the distribution of HTTP requests by HTTP version over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "HTTP/1.x": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "HTTP/2": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "HTTP/3": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "HTTP/1.x", "HTTP/2", "HTTP/3" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.timeseries-groups", "x-fern-sdk-method-name": "http-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/timeseries_groups_v2/) instead." } }, "/radar/http/timeseries_groups/ip_version": { "get": { "operationId": "radar-get-http-timeseries-group-by-ip-version", "summary": "Get HTTP requests by IP version time series", "description": "Retrieves the distribution of HTTP requests by IP version over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "IPv4": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "IPv6": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "IPv4", "IPv6" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.timeseries-groups", "x-fern-sdk-method-name": "ip-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/timeseries_groups_v2/) instead." } }, "/radar/http/timeseries_groups/os": { "get": { "operationId": "radar-get-http-timeseries-group-by-operating-system", "summary": "Get HTTP requests by OS time series", "description": "Retrieves the distribution of HTTP requests by operating system over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "ANDROID": [ "97.28898" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.timeseries-groups", "x-fern-sdk-method-name": "os", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/timeseries_groups_v2/) instead." } }, "/radar/http/timeseries_groups/post_quantum": { "get": { "operationId": "radar-get-http-timeseries-group-by-post-quantum", "summary": "Get HTTP requests by post-quantum support time series", "description": "Retrieves the distribution of HTTP requests by post-quantum support over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "NOT_SUPPORTED": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "SUPPORTED": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "SUPPORTED", "NOT_SUPPORTED" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.timeseries-groups", "x-fern-sdk-method-name": "post-quantum", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/timeseries_groups_v2/) instead." } }, "/radar/http/timeseries_groups/tls_version": { "get": { "operationId": "radar-get-http-timeseries-group-by-tls-version", "summary": "Get HTTP requests by TLS version time series", "description": "Retrieves the distribution of HTTP requests by TLS version over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "TLS 1.0": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "TLS 1.1": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "TLS 1.2": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "TLS 1.3": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "TLS QUIC": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "TLS 1.0", "TLS 1.1", "TLS 1.2", "TLS 1.3", "TLS QUIC" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.timeseries-groups", "x-fern-sdk-method-name": "tls-version", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/timeseries_groups_v2/) instead." } }, "/radar/http/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-http-timeseries-group", "summary": "Get HTTP requests time series grouped by dimension", "description": "Retrieves the distribution of HTTP requests grouped by dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the HTTP attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the HTTP attribute by which to group the results.", "type": "string", "enum": [ "ADM1", "API_TRAFFIC", "AS", "BOT_CLASS", "BROWSER", "BROWSER_FAMILY", "CONTENT_TYPE", "DEVICE_TYPE", "HTTP_PROTOCOL", "HTTP_VERSION", "IP_VERSION", "LOCATION", "OS", "POST_QUANTUM", "TLS_VERSION" ] } }, { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "apiTraffic", "in": "query", "description": "Filters results by API traffic classification. API traffic is identified by JSON or XML response content types on dynamic (non-cacheable) HTTP requests. Incompatible with the `browserFamily`, `deviceType`, `httpProtocol`, `httpVersion`, `ipVersion`, `os`, and `tlsVersion` filters/dimensions. When set, results can only be further filtered by location, continent, or Autonomous System.", "schema": { "description": "Filters results by API traffic classification. API traffic is identified by JSON or XML response content types on dynamic (non-cacheable) HTTP requests. Incompatible with the `browserFamily`, `deviceType`, `httpProtocol`, `httpVersion`, `ipVersion`, `os`, and `tlsVersion` filters/dimensions. When set, results can only be further filtered by location, continent, or Autonomous System.", "type": "array", "items": { "enum": [ "API", "NON_API" ], "type": "string" }, "example": "API" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "contentType", "in": "query", "description": "Filters results by content type category. When set, results can only be further filtered by location, continent, or Autonomous System.", "schema": { "description": "Filters results by content type category. When set, results can only be further filtered by location, continent, or Autonomous System.", "type": "array", "items": { "enum": [ "HTML", "IMAGES", "JSON", "JAVASCRIPT", "CSS", "PLAIN_TEXT", "FONTS", "XML", "YAML", "VIDEO", "AUDIO", "MARKDOWN", "DOCUMENTS", "BINARY", "SERIALIZATION", "OTHER" ], "type": "string" } } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "Chrome": [ "50.168733" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http", "x-fern-sdk-method-name": "timeseries-groups-v2", "x-forge-hidden": true } }, "/radar/http/top/ases": { "get": { "operationId": "radar-get-http-top-ases-by-http-requests", "summary": "Get top ASes by HTTP requests", "description": "Retrieves the top autonomous systems by HTTP requests.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientASN": { "type": "integer", "example": 3243 }, "clientASName": { "type": "string", "example": "MEO" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientASN", "clientASName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.ases", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/ases/bot_class/{bot_class}": { "get": { "operationId": "radar-get-http-top-ases-by-bot-class", "summary": "Get top ASes by HTTP requests for a bot class", "description": "Retrieves the top autonomous systems, by HTTP requests, of the requested bot class.", "parameters": [ { "name": "bot_class", "in": "path", "description": "Bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "required": true, "schema": { "description": "Bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "string", "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientASN": { "type": "integer", "example": 3243 }, "clientASName": { "type": "string", "example": "MEO" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientASN", "clientASName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.ases.bot-class", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/ases/browser_family/{browser_family}": { "get": { "operationId": "radar-get-http-top-ases-by-browser-family", "summary": "Get top ASes by HTTP requests for a browser family", "description": "Retrieves the top autonomous systems, by HTTP requests, of the requested browser family.", "parameters": [ { "name": "browser_family", "in": "path", "description": "Browser family.", "required": true, "schema": { "description": "Browser family.", "type": "string", "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientASN": { "type": "integer", "example": 3243 }, "clientASName": { "type": "string", "example": "MEO" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientASN", "clientASName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.ases.browser-family", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/ases/device_type/{device_type}": { "get": { "operationId": "radar-get-http-top-ases-by-device-type", "summary": "Get top ASes by HTTP requests for a device type", "description": "Retrieves the top autonomous systems, by HTTP requests, of the requested device type.", "parameters": [ { "name": "device_type", "in": "path", "description": "Device type.", "required": true, "schema": { "description": "Device type.", "type": "string", "enum": [ "DESKTOP", "MOBILE", "OTHER" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientASN": { "type": "integer", "example": 3243 }, "clientASName": { "type": "string", "example": "MEO" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientASN", "clientASName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.ases.device-type", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/ases/http_protocol/{http_protocol}": { "get": { "operationId": "radar-get-http-top-ases-by-http-protocol", "summary": "Get top ASes by HTTP requests for an HTTP protocol", "description": "Retrieves the top autonomous systems, by HTTP requests, of the requested HTTP protocol.", "parameters": [ { "name": "http_protocol", "in": "path", "description": "HTTP protocol (HTTP vs. HTTPS).", "required": true, "schema": { "description": "HTTP protocol (HTTP vs. HTTPS).", "type": "string", "enum": [ "HTTP", "HTTPS" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientASN": { "type": "integer", "example": 3243 }, "clientASName": { "type": "string", "example": "MEO" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientASN", "clientASName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.ases.http-protocol", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/ases/http_version/{http_version}": { "get": { "operationId": "radar-get-http-top-ases-by-http-version", "summary": "Get top ASes by HTTP requests for an HTTP version", "description": "Retrieves the top autonomous systems, by HTTP requests, of the requested HTTP version.", "parameters": [ { "name": "http_version", "in": "path", "description": "HTTP version.", "required": true, "schema": { "description": "HTTP version.", "type": "string", "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientASN": { "type": "integer", "example": 3243 }, "clientASName": { "type": "string", "example": "MEO" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientASN", "clientASName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.ases.http-method", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/ases/ip_version/{ip_version}": { "get": { "operationId": "radar-get-http-top-ases-by-ip-version", "summary": "Get top ASes by HTTP requests for an IP version", "description": "Retrieves the top autonomous systems, by HTTP requests, of the requested IP version.", "parameters": [ { "name": "ip_version", "in": "path", "description": "IP version.", "required": true, "schema": { "description": "IP version.", "type": "string", "enum": [ "IPv4", "IPv6" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientASN": { "type": "integer", "example": 3243 }, "clientASName": { "type": "string", "example": "MEO" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientASN", "clientASName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.ases.ip-version", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/ases/os/{os}": { "get": { "operationId": "radar-get-http-top-ases-by-operating-system", "summary": "Get top ASes by HTTP requests for an OS", "description": "Retrieves the top autonomous systems, by HTTP requests, of the requested operating system.", "parameters": [ { "name": "os", "in": "path", "description": "Operating system.", "required": true, "schema": { "description": "Operating system.", "type": "string", "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientASN": { "type": "integer", "example": 3243 }, "clientASName": { "type": "string", "example": "MEO" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientASN", "clientASName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.ases.os", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/ases/tls_version/{tls_version}": { "get": { "operationId": "radar-get-http-top-ases-by-tls-version", "summary": "Get top ASes by HTTP requests for a TLS version", "description": "Retrieves the top autonomous systems, by HTTP requests, of the requested TLS protocol version.", "parameters": [ { "name": "tls_version", "in": "path", "description": "TLS version.", "required": true, "schema": { "description": "TLS version.", "type": "string", "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientASN": { "type": "integer", "example": 3243 }, "clientASName": { "type": "string", "example": "MEO" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientASN", "clientASName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.ases.tls-version", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/browser": { "get": { "operationId": "radar-get-http-top-browsers", "summary": "Get top user agents by HTTP requests", "description": "Retrieves the top user agents by HTTP requests.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "chrome" }, "value": { "type": "string" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.top", "x-fern-sdk-method-name": "browser", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/summary_v2/) instead." } }, "/radar/http/top/browser_family": { "get": { "operationId": "radar-get-http-top-browser-families", "summary": "Get top user agent families by HTTP requests", "description": "Retrieves the top user agents, aggregated in families, by HTTP requests.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "chrome" }, "value": { "type": "string" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.http.top", "x-fern-sdk-method-name": "browser-family", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar HTTP Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/http/methods/summary_v2/) instead." } }, "/radar/http/top/locations": { "get": { "operationId": "radar-get-http-top-locations-by-http-requests", "summary": "Get top locations by HTTP requests", "description": "Retrieves the top locations by HTTP requests.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "US" }, "clientCountryName": { "type": "string", "example": "United States" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryAlpha2", "clientCountryName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.locations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/locations/bot_class/{bot_class}": { "get": { "operationId": "radar-get-http-top-locations-by-bot-class", "summary": "Get top locations by HTTP requests for a bot class", "description": "Retrieves the top locations, by HTTP requests, of the requested bot class.", "parameters": [ { "name": "bot_class", "in": "path", "description": "Bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "required": true, "schema": { "description": "Bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "string", "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "US" }, "clientCountryName": { "type": "string", "example": "United States" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryAlpha2", "clientCountryName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.locations.bot-class", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/locations/browser_family/{browser_family}": { "get": { "operationId": "radar-get-http-top-locations-by-browser-family", "summary": "Get top locations by HTTP requests for a browser family", "description": "Retrieves the top locations, by HTTP requests, of the requested browser family.", "parameters": [ { "name": "browser_family", "in": "path", "description": "Browser family.", "required": true, "schema": { "description": "Browser family.", "type": "string", "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "US" }, "clientCountryName": { "type": "string", "example": "United States" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryAlpha2", "clientCountryName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.locations.browser-family", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/locations/device_type/{device_type}": { "get": { "operationId": "radar-get-http-top-locations-by-device-type", "summary": "Get top locations by HTTP requests for a device type", "description": "Retrieves the top locations, by HTTP requests, of the requested device type.", "parameters": [ { "name": "device_type", "in": "path", "description": "Device type.", "required": true, "schema": { "description": "Device type.", "type": "string", "enum": [ "DESKTOP", "MOBILE", "OTHER" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "US" }, "clientCountryName": { "type": "string", "example": "United States" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryAlpha2", "clientCountryName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.locations.device-type", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/locations/http_protocol/{http_protocol}": { "get": { "operationId": "radar-get-http-top-locations-by-http-protocol", "summary": "Get top locations by HTTP requests for an HTTP protocol", "description": "Retrieves the top locations, by HTTP requests, of the requested HTTP protocol.", "parameters": [ { "name": "http_protocol", "in": "path", "description": "HTTP protocol (HTTP vs. HTTPS).", "required": true, "schema": { "description": "HTTP protocol (HTTP vs. HTTPS).", "type": "string", "enum": [ "HTTP", "HTTPS" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "US" }, "clientCountryName": { "type": "string", "example": "United States" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryAlpha2", "clientCountryName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.locations.http-protocol", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/locations/http_version/{http_version}": { "get": { "operationId": "radar-get-http-top-locations-by-http-version", "summary": "Get top locations by HTTP requests for an HTTP version", "description": "Retrieves the top locations, by HTTP requests, of the requested HTTP version.", "parameters": [ { "name": "http_version", "in": "path", "description": "HTTP version.", "required": true, "schema": { "description": "HTTP version.", "type": "string", "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "US" }, "clientCountryName": { "type": "string", "example": "United States" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryAlpha2", "clientCountryName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.locations.http-method", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/locations/ip_version/{ip_version}": { "get": { "operationId": "radar-get-http-top-locations-by-ip-version", "summary": "Get top locations by HTTP requests for an IP version", "description": "Retrieves the top locations, by HTTP requests, of the requested IP version.", "parameters": [ { "name": "ip_version", "in": "path", "description": "IP version.", "required": true, "schema": { "description": "IP version.", "type": "string", "enum": [ "IPv4", "IPv6" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "US" }, "clientCountryName": { "type": "string", "example": "United States" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryAlpha2", "clientCountryName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.locations.ip-version", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/locations/os/{os}": { "get": { "operationId": "radar-get-http-top-locations-by-operating-system", "summary": "Get top locations by HTTP requests for an OS", "description": "Retrieves the top locations, by HTTP requests, of the requested operating system.", "parameters": [ { "name": "os", "in": "path", "description": "Operating system.", "required": true, "schema": { "description": "Operating system.", "type": "string", "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "tlsVersion", "in": "query", "description": "Filters results by TLS version.", "schema": { "description": "Filters results by TLS version.", "type": "array", "items": { "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ], "type": "string" }, "example": "TLSv1_2" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "US" }, "clientCountryName": { "type": "string", "example": "United States" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryAlpha2", "clientCountryName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.locations.os", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/http/top/locations/tls_version/{tls_version}": { "get": { "operationId": "radar-get-http-top-locations-by-tls-version", "summary": "Get top locations by HTTP requests for a TLS version", "description": "Retrieves the top locations, by HTTP requests, of the requested TLS protocol version.", "parameters": [ { "name": "tls_version", "in": "path", "description": "TLS version.", "required": true, "schema": { "description": "TLS version.", "type": "string", "enum": [ "TLSv1_0", "TLSv1_1", "TLSv1_2", "TLSv1_3", "TLSvQUIC" ] } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "deviceType", "in": "query", "description": "Filters results by device type.", "schema": { "description": "Filters results by device type.", "type": "array", "items": { "enum": [ "DESKTOP", "MOBILE", "OTHER" ], "type": "string" }, "example": "DESKTOP" } }, { "name": "httpProtocol", "in": "query", "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "schema": { "description": "Filters results by HTTP protocol (HTTP vs. HTTPS).", "type": "array", "items": { "enum": [ "HTTP", "HTTPS" ], "type": "string" }, "example": "HTTPS" } }, { "name": "httpVersion", "in": "query", "description": "Filters results by HTTP version.", "schema": { "description": "Filters results by HTTP version.", "type": "array", "items": { "enum": [ "HTTPv1", "HTTPv2", "HTTPv3" ], "type": "string" }, "example": "HTTPv1" } }, { "name": "ipVersion", "in": "query", "description": "Filters results by IP version (Ipv4 vs. IPv6).", "schema": { "description": "Filters results by IP version (Ipv4 vs. IPv6).", "type": "array", "items": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "example": "IPv4" } }, { "name": "os", "in": "query", "description": "Filters results by operating system.", "schema": { "description": "Filters results by operating system.", "type": "array", "items": { "enum": [ "WINDOWS", "MACOSX", "IOS", "ANDROID", "CHROMEOS", "LINUX", "SMART_TV" ], "type": "string" }, "example": "WINDOWS" } }, { "name": "browserFamily", "in": "query", "description": "Filters results by browser family.", "schema": { "description": "Filters results by browser family.", "type": "array", "items": { "enum": [ "CHROME", "EDGE", "FIREFOX", "SAFARI" ], "type": "string" }, "example": "CHROME" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "US" }, "clientCountryName": { "type": "string", "example": "United States" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryAlpha2", "clientCountryName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar HTTP" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.http.locations.tls-version", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/leaked_credential_checks/summary/bot_class": { "get": { "operationId": "radar-get-leaked-credential-checks-summary-by-bot-class", "summary": "Get HTTP authentication requests by bot class summary", "description": "Retrieves the distribution of HTTP authentication requests by bot class.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "compromised", "in": "query", "description": "Filters results by compromised credential status (clean vs. compromised).", "schema": { "description": "Filters results by compromised credential status (clean vs. compromised).", "type": "array", "items": { "enum": [ "CLEAN", "COMPROMISED" ], "type": "string" }, "example": "COMPROMISED" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "bot": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "human": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "human", "bot" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Leaked Credential Checks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.leaked-credentials.summary", "x-fern-sdk-method-name": "bot-class", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Leaked Credentials Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/leaked_credentials/methods/summary_v2/) instead." } }, "/radar/leaked_credential_checks/summary/compromised": { "get": { "operationId": "radar-get-leaked-credential-checks-summary-by-compromised", "summary": "Get HTTP authentication requests by compromised credential status summary", "description": "Retrieves the distribution of HTTP authentication requests by compromised credential status.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "CLEAN": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "COMPROMISED": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "COMPROMISED", "CLEAN" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Leaked Credential Checks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.leaked-credentials.summary", "x-fern-sdk-method-name": "compromised", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Leaked Credentials Summary By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/leaked_credentials/methods/summary_v2/) instead." } }, "/radar/leaked_credential_checks/summary/{dimension}": { "get": { "operationId": "radar-get-leaked-credential-checks-summary", "summary": "Get HTTP authentication requests distribution by dimension", "description": "Retrieves an aggregated summary of HTTP authentication requests grouped by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "COMPROMISED", "BOT_CLASS" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "compromised", "in": "query", "description": "Filters results by compromised credential status (clean vs. compromised).", "schema": { "description": "Filters results by compromised credential status (clean vs. compromised).", "type": "array", "items": { "enum": [ "CLEAN", "COMPROMISED" ], "type": "string" }, "example": "COMPROMISED" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "CLEAN": "85.123456", "COMPROMISED": "14.876544" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Leaked Credential Checks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.leaked-credentials", "x-fern-sdk-method-name": "summary-v2", "x-forge-hidden": true } }, "/radar/leaked_credential_checks/timeseries_groups/bot_class": { "get": { "operationId": "radar-get-leaked-credential-checks-timeseries-group-by-bot-class", "summary": "Get HTTP authentication requests by bot class time series", "description": "Retrieves the distribution of HTTP authentication requests by bot class over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "compromised", "in": "query", "description": "Filters results by compromised credential status (clean vs. compromised).", "schema": { "description": "Filters results by compromised credential status (clean vs. compromised).", "type": "array", "items": { "enum": [ "CLEAN", "COMPROMISED" ], "type": "string" }, "example": "COMPROMISED" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "bot": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "human": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "human", "bot" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Leaked Credential Checks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.leaked-credentials.timeseries-groups", "x-fern-sdk-method-name": "bot-class", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Leaked Credentials Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/leaked_credentials/methods/timeseries_groups_v2/) instead." } }, "/radar/leaked_credential_checks/timeseries_groups/compromised": { "get": { "operationId": "radar-get-leaked-credential-checks-timeseries-group-by-compromised", "summary": "Get HTTP authentication requests by compromised credential status time series", "description": "Retrieves the distribution of HTTP authentication requests by compromised credential status over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "CLEAN": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "COMPROMISED": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "CLEAN", "COMPROMISED" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Leaked Credential Checks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.leaked-credentials.timeseries-groups", "x-fern-sdk-method-name": "compromised", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Leaked Credentials Timeseries Groups By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/leaked_credentials/methods/timeseries_groups_v2/) instead." } }, "/radar/leaked_credential_checks/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-leaked-credential-checks-timeseries-group", "summary": "Get time series distribution of HTTP authentication requests by dimension.", "description": "Retrieves the distribution of HTTP authentication requests, grouped by the specified dimension over time.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the attribute by which to group the results.", "type": "string", "enum": [ "COMPROMISED", "BOT_CLASS" ] } }, { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "botClass", "in": "query", "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "schema": { "description": "Filters results by bot class. Refer to [Bot classes](https://developers.cloudflare.com/radar/concepts/bot-classes/).", "type": "array", "items": { "enum": [ "LIKELY_AUTOMATED", "LIKELY_HUMAN" ], "type": "string" }, "example": "LIKELY_AUTOMATED" } }, { "name": "compromised", "in": "query", "description": "Filters results by compromised credential status (clean vs. compromised).", "schema": { "description": "Filters results by compromised credential status (clean vs. compromised).", "type": "array", "items": { "enum": [ "CLEAN", "COMPROMISED" ], "type": "string" }, "example": "COMPROMISED" } }, { "name": "checkResult", "in": "query", "description": "Filters results by leaked credential check result.", "schema": { "description": "Filters results by leaked credential check result.", "type": "array", "items": { "enum": [ "CLEAN", "USERNAME_LEAKED", "USERNAME_PASSWORD_SIMILAR", "USERNAME_AND_PASSWORD_LEAKED", "PASSWORD_LEAKED" ], "type": "string" }, "example": "PASSWORD_LEAKED" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `PERCENTAGE_CHANGE` requires exactly one comparison series (e.g. a `control` date range).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `PERCENTAGE_CHANGE` requires exactly one comparison series (e.g. a `control` date range).", "type": "string", "example": "MIN0_MAX", "enum": [ "PERCENTAGE_CHANGE", "MIN0_MAX" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "CLEAN": [ "85.123456" ], "COMPROMISED": [ "14.876544" ], "timestamps": [ "2024-07-30T03:00:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Leaked Credential Checks" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.leaked-credentials", "x-fern-sdk-method-name": "timeseries-groups-v2", "x-forge-hidden": true } }, "/radar/netflows/summary": { "get": { "operationId": "radar-get-netflows-summary-deprecated", "summary": "Get network traffic summary", "description": "Retrieves the distribution of network traffic (NetFlows) by HTTP vs other protocols.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "HTTP": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" }, "OTHER": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "HTTP", "OTHER" ] } }, "required": [ "meta", "summary_0" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar NetFlows" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.netflows", "x-fern-sdk-method-name": "summary", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Get Network Traffic Distribution By Dimension](https://developers.cloudflare.com/api/resources/radar/subresources/netflows/methods/summary_v2/) instead." } }, "/radar/netflows/summary/{dimension}": { "get": { "operationId": "radar-get-netflows-summary", "summary": "Get network traffic distribution by dimension", "description": "Retrieves the distribution of network traffic (NetFlows) by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the NetFlows attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the NetFlows attribute by which to group the results.", "type": "string", "enum": [ "ADM1", "AS", "LOCATION", "PRODUCT" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "product", "in": "query", "description": "Filters the results by network traffic product types.", "schema": { "description": "Filters the results by network traffic product types.", "type": "array", "items": { "enum": [ "HTTP", "ALL" ], "type": "string" }, "example": "ALL" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "Germany": "25.084366", "United States": "50.168733" }, "additionalProperties": { "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar NetFlows" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.netflows", "x-fern-sdk-method-name": "summary-v2", "x-forge-hidden": true } }, "/radar/netflows/timeseries": { "get": { "operationId": "radar-get-netflows-timeseries", "summary": "Get network traffic time series", "description": "Retrieves network traffic (NetFlows) over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "product", "in": "query", "description": "Filters the results by network traffic product types.", "schema": { "description": "Filters the results by network traffic product types.", "type": "array", "items": { "enum": [ "HTTP", "ALL" ], "type": "string" }, "example": "ALL" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `PERCENTAGE_CHANGE` requires exactly one comparison series (e.g. a `control` date range).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `PERCENTAGE_CHANGE` requires exactly one comparison series (e.g. a `control` date range).", "type": "string", "example": "MIN0_MAX", "enum": [ "PERCENTAGE_CHANGE", "MIN0_MAX" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } }, "values": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "timestamps", "values" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar NetFlows" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.netflows", "x-fern-sdk-method-name": "timeseries", "x-forge-hidden": true } }, "/radar/netflows/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-netflows-timeseries-group", "summary": "Get time series distribution of network traffic by dimension", "description": "Retrieves the distribution of NetFlows traffic, grouped by the specified dimension over time.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the NetFlows attribute by which to group the results.", "required": true, "schema": { "description": "Specifies the NetFlows attribute by which to group the results.", "type": "string", "enum": [ "ADM1", "AS", "LOCATION", "PRODUCT" ] } }, { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `PERCENTAGE_CHANGE` requires exactly one comparison series (e.g. a `control` date range).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/). `PERCENTAGE_CHANGE` requires exactly one comparison series (e.g. a `control` date range).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX", "PERCENTAGE_CHANGE" ] } }, { "name": "product", "in": "query", "description": "Filters the results by network traffic product types.", "schema": { "description": "Filters the results by network traffic product types.", "type": "array", "items": { "enum": [ "HTTP", "ALL" ], "type": "string" }, "example": "ALL" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "Germany": [ "25.084366" ], "United States": [ "50.168733" ], "timestamps": [ "2023-08-08T10:15:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar NetFlows" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.netflows", "x-fern-sdk-method-name": "timeseries-groups", "x-forge-hidden": true } }, "/radar/netflows/top/ases": { "get": { "operationId": "radar-get-netflows-top-ases", "summary": "Get top ASes by network traffic", "description": "Retrieves the top autonomous systems by network traffic (NetFlows).", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientASN": { "type": "number", "example": 16509 }, "clientASName": { "type": "string", "example": "AMAZON-02" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientASN", "clientASName", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar NetFlows" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.netflows.top", "x-fern-sdk-method-name": "ases", "x-forge-hidden": true } }, "/radar/netflows/top/locations": { "get": { "operationId": "radar-get-netflows-top-locations", "summary": "Get top locations by network traffic", "description": "Retrieves the top locations by network traffic (NetFlows).", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "geoId", "in": "query", "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "schema": { "description": "Filters results by Geolocation. Specify a comma-separated list of GeoNames IDs. Prefix with `-` to exclude geoIds from results. For example, `-2267056,360689` excludes results from the 2267056 (Lisbon), but includes results from 5128638 (New York).", "type": "array", "items": { "type": "string" }, "example": "2267056,360689" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "US" }, "clientCountryName": { "type": "string", "example": "United States" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryName", "clientCountryAlpha2", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar NetFlows" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.netflows.top", "x-fern-sdk-method-name": "locations", "x-forge-hidden": true } }, "/radar/origins": { "get": { "operationId": "radar-get-origins", "summary": "List Origins", "description": "Retrieves a list of origins with their regions.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Skips the specified number of objects before fetching the results.", "schema": { "description": "Skips the specified number of objects before fetching the results.", "type": "integer", "minimum": 0 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "origins": { "type": "array", "items": { "properties": { "regions": { "type": "array", "items": { "properties": { "region": { "description": "The region code.", "type": "string", "example": "us-east-1" } }, "required": [ "region" ], "type": "object" } }, "slug": { "description": "The origin slug.", "type": "string", "example": "amazon" } }, "required": [ "slug", "regions" ], "type": "object" } } }, "required": [ "origins" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Origins" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.origins", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/radar/origins/summary/{dimension}": { "get": { "operationId": "radar-get-origins-summary", "summary": "Get origin metrics distribution by dimension", "description": "Retrieves an aggregated summary of origin metrics grouped by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the origin attribute by which to group the results. `ORIGIN` groups across all providers and does not accept an `origin` or `region`. `REGION` requires an `origin`. `SUCCESS_RATE` and `PERCENTILE` require both an `origin` and a `region` and constrain the `metric` (`SUCCESS_RATE` supports only `REQUESTS`; `PERCENTILE` supports any metric except `REQUESTS`). `limitPerGroup` is only supported on the `REGION` dimension.", "required": true, "schema": { "description": "Specifies the origin attribute by which to group the results. `ORIGIN` groups across all providers and does not accept an `origin` or `region`. `REGION` requires an `origin`. `SUCCESS_RATE` and `PERCENTILE` require both an `origin` and a `region` and constrain the `metric` (`SUCCESS_RATE` supports only `REQUESTS`; `PERCENTILE` supports any metric except `REQUESTS`). `limitPerGroup` is only supported on the `REGION` dimension.", "type": "string", "enum": [ "ORIGIN", "REGION", "SUCCESS_RATE", "PERCENTILE" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "origin", "in": "query", "description": "Filters results by origin. Required for every dimension except `ORIGIN`; must not be set on the `ORIGIN` dimension, which groups across all providers.", "schema": { "description": "Filters results by origin. Required for every dimension except `ORIGIN`; must not be set on the `ORIGIN` dimension, which groups across all providers.", "type": "array", "items": { "description": "Origins.", "enum": [ "AMAZON", "GOOGLE", "MICROSOFT", "ORACLE" ], "type": "string" }, "example": [ "AMAZON" ] } }, { "name": "metric", "in": "query", "description": "Specifies the metric to retrieve. Allowed metrics depend on the selected dimension (see the `dimension` path parameter).", "required": true, "schema": { "description": "Specifies the metric to retrieve. Allowed metrics depend on the selected dimension (see the `dimension` path parameter).", "type": "string", "example": "REQUESTS", "enum": [ "CONNECTION_FAILURES", "REQUESTS", "RESPONSE_HEADER_RECEIVE_DURATION", "TCP_HANDSHAKE_DURATION", "TCP_RTT", "TLS_HANDSHAKE_DURATION" ] } }, { "name": "region", "in": "query", "description": "Filters results by origin region. Requires `origin` to be set and is validated against it.", "schema": { "description": "Filters results by origin region. Requires `origin` to be set and is validated against it.", "type": "array", "items": { "maxLength": 100, "type": "string" }, "example": [ "us-east-1" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "eu-west-1": "52.14", "us-east-1": "45.23", "us-west-2": "38.67" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Origins" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.origins", "x-fern-sdk-method-name": "summary", "x-forge-hidden": true } }, "/radar/origins/timeseries": { "get": { "operationId": "radar-get-origins-timeseries", "summary": "Get origin metrics time series", "description": "Retrieves the time series of origin metrics for the specified origin.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "origin", "in": "query", "description": "Filters results by origin.", "required": true, "schema": { "description": "Filters results by origin.", "type": "array", "items": { "description": "Origins.", "enum": [ "AMAZON", "GOOGLE", "MICROSOFT", "ORACLE" ], "type": "string" }, "example": [ "AMAZON" ] } }, { "name": "metric", "in": "query", "description": "Specifies the metric to retrieve. Without a `region`, only `REQUESTS` or `CONNECTION_FAILURES` are available; specify a `region` to use the latency metrics.", "required": true, "schema": { "description": "Specifies the metric to retrieve. Without a `region`, only `REQUESTS` or `CONNECTION_FAILURES` are available; specify a `region` to use the latency metrics.", "type": "string", "example": "REQUESTS", "enum": [ "CONNECTION_FAILURES", "REQUESTS", "RESPONSE_HEADER_RECEIVE_DURATION", "TCP_HANDSHAKE_DURATION", "TCP_RTT", "TLS_HANDSHAKE_DURATION" ] } }, { "name": "region", "in": "query", "description": "Filters results by origin region. Requires `origin` to be set and is validated against it.", "schema": { "description": "Filters results by origin region. Requires `origin` to be set and is validated against it.", "type": "array", "items": { "maxLength": 100, "type": "string" }, "example": [ "us-east-1" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "additionalProperties": { "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } }, "values": { "type": "array", "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "timestamps", "values" ], "type": "object" }, "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] } }, "required": [ "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Origins" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.origins", "x-fern-sdk-method-name": "timeseries", "x-forge-hidden": true } }, "/radar/origins/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-origins-timeseries-group", "summary": "Get origin metrics time series grouped by dimension", "description": "Retrieves the distribution of origin metrics grouped by the specified dimension over time.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the origin attribute by which to group the results. `ORIGIN` groups across all providers and does not accept an `origin` or `region`. `REGION` requires an `origin`. `SUCCESS_RATE` and `PERCENTILE` require both an `origin` and a `region` and constrain the `metric` (`SUCCESS_RATE` supports only `REQUESTS`; `PERCENTILE` supports any metric except `REQUESTS`). `limitPerGroup` is only supported on the `REGION` dimension.", "required": true, "schema": { "description": "Specifies the origin attribute by which to group the results. `ORIGIN` groups across all providers and does not accept an `origin` or `region`. `REGION` requires an `origin`. `SUCCESS_RATE` and `PERCENTILE` require both an `origin` and a `region` and constrain the `metric` (`SUCCESS_RATE` supports only `REQUESTS`; `PERCENTILE` supports any metric except `REQUESTS`). `limitPerGroup` is only supported on the `REGION` dimension.", "type": "string", "enum": [ "ORIGIN", "REGION", "SUCCESS_RATE", "PERCENTILE" ] } }, { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "origin", "in": "query", "description": "Filters results by origin. Required for every dimension except `ORIGIN`; must not be set on the `ORIGIN` dimension, which groups across all providers.", "schema": { "description": "Filters results by origin. Required for every dimension except `ORIGIN`; must not be set on the `ORIGIN` dimension, which groups across all providers.", "type": "array", "items": { "description": "Origins.", "enum": [ "AMAZON", "GOOGLE", "MICROSOFT", "ORACLE" ], "type": "string" }, "example": [ "AMAZON" ] } }, { "name": "metric", "in": "query", "description": "Specifies the metric to retrieve. Allowed metrics depend on the selected dimension (see the `dimension` path parameter).", "required": true, "schema": { "description": "Specifies the metric to retrieve. Allowed metrics depend on the selected dimension (see the `dimension` path parameter).", "type": "string", "example": "REQUESTS", "enum": [ "CONNECTION_FAILURES", "REQUESTS", "RESPONSE_HEADER_RECEIVE_DURATION", "TCP_HANDSHAKE_DURATION", "TCP_RTT", "TLS_HANDSHAKE_DURATION" ] } }, { "name": "region", "in": "query", "description": "Filters results by origin region. Requires `origin` to be set and is validated against it.", "schema": { "description": "Filters results by origin region. Requires `origin` to be set and is validated against it.", "type": "array", "items": { "maxLength": 100, "type": "string" }, "example": [ "us-east-1" ] } }, { "name": "normalization", "in": "query", "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "schema": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "example": "PERCENTAGE", "default": "PERCENTAGE", "enum": [ "PERCENTAGE", "MIN0_MAX" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "eu-west-1": [ "52.14" ], "timestamps": [ "2023-08-08T10:15:00Z" ], "us-east-1": [ "45.23" ], "us-west-2": [ "38.67" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "nullable": true, "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Origins" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.origins", "x-fern-sdk-method-name": "timeseries-groups", "x-forge-hidden": true } }, "/radar/origins/{slug}": { "get": { "operationId": "radar-get-origin-details", "summary": "Get Origin details", "description": "Retrieves the requested origin information with its regions.", "parameters": [ { "name": "slug", "in": "path", "description": "Origin slug.", "required": true, "schema": { "description": "Origin slug.", "type": "string", "example": "amazon", "enum": [ "AMAZON", "GOOGLE", "MICROSOFT", "ORACLE" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "origin": { "type": "object", "properties": { "regions": { "type": "array", "items": { "properties": { "region": { "description": "The region code.", "type": "string", "example": "us-east-1" } }, "required": [ "region" ], "type": "object" } }, "slug": { "description": "The origin slug.", "type": "string", "example": "amazon" } }, "required": [ "slug", "regions" ] } }, "required": [ "origin" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Origins" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.origins", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/post_quantum/origin/summary/{dimension}": { "get": { "operationId": "radar-get-origin-post-quantum-summary", "summary": "Get Origin Post-Quantum Data Summary", "description": "Returns a summary of origin post-quantum data grouped by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the origin post-quantum data dimension by which to group the results.", "required": true, "schema": { "description": "Specifies the origin post-quantum data dimension by which to group the results.", "type": "string", "enum": [ "KEY_AGREEMENT" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "CurveP256": "99.1234", "CurveP384": "85.5678", "CurveP521": "45.9012", "X25519": "98.3456", "X25519MLKEM768": "12.7890" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Post-Quantum" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.post-quantum.origin", "x-fern-sdk-method-name": "summary", "x-forge-hidden": true } }, "/radar/post_quantum/origin/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-origin-post-quantum-timeseries-groups", "summary": "Get Origin Post-Quantum Data Over Time", "description": "Returns a timeseries of origin post-quantum data grouped by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Specifies the origin post-quantum data dimension by which to group the results.", "required": true, "schema": { "description": "Specifies the origin post-quantum data dimension by which to group the results.", "type": "string", "enum": [ "KEY_AGREEMENT" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "CurveP256": [ "99.1234", "99.2345" ], "CurveP384": [ "85.5678", "85.6789" ], "CurveP521": [ "45.9012", "46.0123" ], "X25519": [ "98.3456", "98.4567" ], "X25519MLKEM768": [ "12.7890", "13.8901" ], "timestamps": [ "2025-01-01T00:00:00Z", "2025-01-02T00:00:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Post-Quantum" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.post-quantum.origin", "x-fern-sdk-method-name": "timeseries-groups", "x-forge-hidden": true } }, "/radar/post_quantum/tls/support": { "get": { "operationId": "radar-get-post-quantum-tls-support", "summary": "Check Post-Quantum TLS support", "description": "Tests whether a hostname or IP address supports Post-Quantum (PQ) TLS key exchange. Returns information about the negotiated key exchange algorithm, whether it uses PQ cryptography, and any detected TLS implementation bugs (Split ClientHello, HRR failure, etc.).", "parameters": [ { "name": "host", "in": "query", "description": "Hostname or IP address to test for Post-Quantum TLS support, optionally with port (defaults to 443).", "required": true, "schema": { "description": "Hostname or IP address to test for Post-Quantum TLS support, optionally with port (defaults to 443).", "type": "string", "example": "cloudflare.com", "minLength": 1 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "bugs": { "type": "object", "properties": { "hrrFailure": { "description": "Server sends a HelloRetryRequest but fails to complete the handshake after the client sends the second ClientHello. Often caused by non-compliant TLS 1.3 implementations on shared hosting providers.", "type": "boolean" }, "splitClientHello": { "description": "Server rejects fragmented ClientHello caused by large PQ keyshare, but accepts classical (non-PQ) handshakes. Typically caused by middleboxes or firewalls that cannot reassemble split TLS ClientHello messages.", "type": "boolean" }, "unknownKeyshare": { "description": "Server cannot handle an unknown key exchange algorithm in the ClientHello keyshare extension. Compliant servers should respond with HelloRetryRequest for a supported algorithm.", "type": "boolean" } }, "required": [ "splitClientHello", "hrrFailure", "unknownKeyshare" ] }, "host": { "description": "The host that was tested", "type": "string" }, "kex": { "description": "TLS CurveID of the negotiated key exchange", "type": "number" }, "kexName": { "description": "Human-readable name of the key exchange algorithm", "type": "string" }, "pq": { "description": "Whether the negotiated key exchange uses Post-Quantum cryptography (specifically X25519MLKEM768)", "type": "boolean" } }, "required": [ "kex", "kexName", "pq", "host", "bugs" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Post-Quantum" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.post-quantum.tls", "x-fern-sdk-method-name": "support", "x-forge-hidden": true } }, "/radar/quality/iqi/summary": { "get": { "operationId": "radar-get-quality-index-summary", "summary": "Get Internet Quality Index (IQI) summary", "description": "Retrieves a summary (percentiles) of bandwidth, latency, or DNS response time from the Radar Internet Quality Index (IQI).", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "metric", "in": "query", "description": "Defines which metric to return (bandwidth, latency, or DNS response time).", "required": true, "schema": { "description": "Defines which metric to return (bandwidth, latency, or DNS response time).", "type": "string", "example": "latency", "enum": [ "BANDWIDTH", "DNS", "LATENCY" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "p25": { "type": "string", "example": "32.20938" }, "p50": { "type": "string", "example": "61.819881" }, "p75": { "type": "string", "example": "133.813087" } }, "required": [ "p75", "p50", "p25" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Quality" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.quality.iqi", "x-fern-sdk-method-name": "summary", "x-forge-hidden": true } }, "/radar/quality/iqi/timeseries_groups": { "get": { "operationId": "radar-get-quality-index-timeseries-group", "summary": "Get Internet Quality Index (IQI) time series", "description": "Retrieves a time series (percentiles) of bandwidth, latency, or DNS response time from the Radar Internet Quality Index (IQI).", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "interpolation", "in": "query", "description": "Enables interpolation for all series (using the average).", "schema": { "description": "Enables interpolation for all series (using the average).", "type": "boolean" } }, { "name": "metric", "in": "query", "description": "Defines which metric to return (bandwidth, latency, or DNS response time).", "required": true, "schema": { "description": "Defines which metric to return (bandwidth, latency, or DNS response time).", "type": "string", "example": "latency", "enum": [ "BANDWIDTH", "DNS", "LATENCY" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "p25": [ "31.253439" ], "p50": [ "60.337738" ], "p75": [ "125.940175" ], "timestamps": [ "2023-04-17T00:00:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "nullable": true, "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Quality" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.quality.iqi", "x-fern-sdk-method-name": "timeseries-groups", "x-forge-hidden": true } }, "/radar/quality/speed/histogram": { "get": { "operationId": "radar-get-quality-speed-histogram", "summary": "Get speed tests histogram", "description": "Retrieves a histogram from the previous 90 days of Cloudflare Speed Test data, split into fixed bandwidth (Mbps), latency (ms), or jitter (ms) buckets.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "bucketSize", "in": "query", "description": "Specifies the width for every bucket in the histogram.", "schema": { "description": "Specifies the width for every bucket in the histogram.", "type": "integer" } }, { "name": "metricGroup", "in": "query", "description": "Metrics to be returned.", "schema": { "description": "Metrics to be returned.", "type": "string", "example": "bandwidth", "default": "bandwidth", "enum": [ "BANDWIDTH", "LATENCY", "JITTER" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "histogram_0": { "type": "object", "properties": { "bandwidthDownload": { "type": "array", "items": { "example": "83681", "type": "string" } }, "bandwidthUpload": { "type": "array", "items": { "example": "181079", "type": "string" } }, "bucketMin": { "type": "array", "items": { "example": "0", "type": "string" } } }, "required": [ "bandwidthUpload", "bandwidthDownload", "bucketMin" ] }, "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "bucketSize": { "description": "The width for every bucket in the histogram.", "type": "integer" }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "totalTests": { "type": "array", "items": { "type": "integer" } }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "bucketSize", "totalTests" ] } }, "required": [ "histogram_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Quality" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.quality.speed", "x-fern-sdk-method-name": "histogram", "x-forge-hidden": true } }, "/radar/quality/speed/summary": { "get": { "operationId": "radar-get-quality-speed-summary", "summary": "Get speed tests summary", "description": "Retrieves a summary of bandwidth, latency, jitter, and packet loss, from the previous 90 days of Cloudflare Speed Test data.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "bandwidthDownload": { "type": "string", "example": "83.765201" }, "bandwidthUpload": { "type": "string", "example": "39.005561" }, "jitterIdle": { "type": "string", "example": "25.648713" }, "jitterLoaded": { "type": "string", "example": "77.462155" }, "latencyIdle": { "type": "string", "example": "83.165385" }, "latencyLoaded": { "type": "string", "example": "270.561124" }, "packetLoss": { "type": "string", "example": "1.23705" } }, "required": [ "bandwidthDownload", "bandwidthUpload", "latencyIdle", "latencyLoaded", "jitterIdle", "jitterLoaded", "packetLoss" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Quality" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.quality.speed", "x-fern-sdk-method-name": "summary", "x-forge-hidden": true } }, "/radar/quality/speed/top/ases": { "get": { "operationId": "radar-get-quality-speed-top-ases", "summary": "Get top ASes by speed test results", "description": "Retrieves the top autonomous systems by bandwidth, latency, jitter, or packet loss, from the previous 90 days of Cloudflare Speed Test data.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "orderBy", "in": "query", "description": "Specifies the metric to order the results by.", "schema": { "description": "Specifies the metric to order the results by.", "type": "string", "default": "BANDWIDTH_DOWNLOAD", "enum": [ "BANDWIDTH_DOWNLOAD", "BANDWIDTH_UPLOAD", "LATENCY_IDLE", "LATENCY_LOADED", "JITTER_IDLE", "JITTER_LOADED" ] } }, { "name": "reverse", "in": "query", "description": "Reverses the order of results.", "schema": { "description": "Reverses the order of results.", "type": "boolean" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "bandwidthDownload": { "type": "string", "example": "642.509004" }, "bandwidthUpload": { "type": "string", "example": "300.672274" }, "clientASN": { "type": "number", "example": 33353 }, "clientASName": { "type": "string", "example": "SIE-CGEI-ASN-1" }, "jitterIdle": { "type": "string", "example": "2.956908" }, "jitterLoaded": { "type": "string", "example": "19.500469" }, "latencyIdle": { "type": "string", "example": "15.925" }, "latencyLoaded": { "type": "string", "example": "65.65" }, "numTests": { "type": "number", "example": 13123 }, "rankPower": { "type": "number", "example": 0.77 } }, "required": [ "clientASN", "clientASName", "bandwidthDownload", "bandwidthUpload", "latencyIdle", "latencyLoaded", "jitterIdle", "jitterLoaded", "numTests", "rankPower" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Quality" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.quality.speed.top", "x-fern-sdk-method-name": "ases", "x-forge-hidden": true } }, "/radar/quality/speed/top/locations": { "get": { "operationId": "radar-get-quality-speed-top-locations", "summary": "Get top locations by speed test results", "description": "Retrieves the top locations by bandwidth, latency, jitter, or packet loss, from the previous 90 days of Cloudflare Speed Test data.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "orderBy", "in": "query", "description": "Specifies the metric to order the results by.", "schema": { "description": "Specifies the metric to order the results by.", "type": "string", "default": "BANDWIDTH_DOWNLOAD", "enum": [ "BANDWIDTH_DOWNLOAD", "BANDWIDTH_UPLOAD", "LATENCY_IDLE", "LATENCY_LOADED", "JITTER_IDLE", "JITTER_LOADED" ] } }, { "name": "reverse", "in": "query", "description": "Reverses the order of results.", "schema": { "description": "Reverses the order of results.", "type": "boolean" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "bandwidthDownload": { "type": "string", "example": "295.886073" }, "bandwidthUpload": { "type": "string", "example": "158.85269" }, "clientCountryAlpha2": { "type": "string", "example": "IS" }, "clientCountryName": { "type": "string", "example": "Iceland" }, "jitterIdle": { "type": "string", "example": "9.640685" }, "jitterLoaded": { "type": "string", "example": "46.480023" }, "latencyIdle": { "type": "string", "example": "15.208124" }, "latencyLoaded": { "type": "string", "example": "114.758887" }, "numTests": { "type": "number", "example": 13123 }, "rankPower": { "type": "number", "example": 0.77 } }, "required": [ "clientCountryAlpha2", "clientCountryName", "bandwidthDownload", "bandwidthUpload", "latencyIdle", "latencyLoaded", "jitterIdle", "jitterLoaded", "numTests", "rankPower" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Quality" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.quality.speed.top", "x-fern-sdk-method-name": "locations", "x-forge-hidden": true } }, "/radar/ranking/domain/{domain}": { "get": { "operationId": "radar-get-ranking-domain-details", "summary": "Get domain rank details", "description": "Retrieves domain rank details. Cloudflare provides an ordered rank for the top 100 domains, but for the remainder it only provides ranking buckets like top 200 thousand, top one million, etc.. These are available through Radar datasets endpoints.", "parameters": [ { "name": "domain", "in": "path", "description": "Domain name.", "required": true, "schema": { "description": "Domain name.", "type": "string", "example": "google.com", "pattern": "^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$" } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "rankingType", "in": "query", "description": "The ranking type.", "schema": { "description": "The ranking type.", "type": "string", "example": "POPULAR", "default": "POPULAR", "enum": [ "POPULAR", "TRENDING_RISE", "TRENDING_STEADY" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "includeTopLocations", "in": "query", "description": "Includes top locations in the response.", "schema": { "description": "Includes top locations in the response.", "type": "boolean" } }, { "name": "date", "in": "query", "description": "Filters results by the specified array of dates.", "schema": { "description": "Filters results by the specified array of dates.", "type": "array", "items": { "format": "date", "type": "string" }, "example": "2022-09-19T00:00:00Z" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "details_0": { "type": "object", "properties": { "bucket": { "description": "Only available in POPULAR ranking for the most recent ranking.", "type": "string", "example": "2000" }, "categories": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 81 }, "name": { "type": "string", "example": "Content Servers" }, "superCategoryId": { "type": "integer", "example": 26 } }, "required": [ "superCategoryId", "name", "id" ], "type": "object" } }, "rank": { "type": "integer", "example": 3 }, "top_locations": { "type": "array", "items": { "properties": { "locationCode": { "type": "string", "example": "US" }, "locationName": { "type": "string", "example": "United States" }, "rank": { "type": "integer", "example": 1 } }, "required": [ "rank", "locationName", "locationCode" ], "type": "object" } } }, "required": [ "categories" ] }, "meta": { "type": "object", "properties": { "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } } }, "required": [ "dateRange" ] } }, "required": [ "details_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Domains Ranking" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ranking.domain", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/ranking/internet_services/categories": { "get": { "operationId": "radar-get-ranking-internet-services-categories", "summary": "List Internet services categories", "description": "Retrieves the list of Internet services categories.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "date", "in": "query", "description": "Filters results by the specified array of dates.", "schema": { "description": "Filters results by the specified array of dates.", "type": "array", "items": { "format": "date", "type": "string" }, "example": "2022-09-19T00:00:00Z" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "categories_0": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Generative AI" } }, "required": [ "name" ], "type": "object" } } }, "required": [ "categories_0" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Internet Services Ranking" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ranking.internet-services", "x-fern-sdk-method-name": "categories", "x-forge-hidden": true } }, "/radar/ranking/internet_services/timeseries_groups": { "get": { "operationId": "radar-get-ranking-internet-services-timeseries", "summary": "Get Internet services rank time series", "description": "Retrieves Internet Services rank update changes over time.", "parameters": [ { "name": "serviceCategory", "in": "query", "description": "Filters results by Internet service category.", "schema": { "description": "Filters results by Internet service category.", "type": "array", "items": { "maxLength": 100, "type": "string" }, "example": "Generative AI" } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "Google": [ 2 ], "timestamps": [ "2022-09-02T00:00:00Z" ] }, "additionalProperties": { "items": { "anyOf": [ { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, { "type": "number" } ], "description": "A numeric string." }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Internet Services Ranking" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ranking.internet-services", "x-fern-sdk-method-name": "timeseries-groups", "x-forge-hidden": true } }, "/radar/ranking/internet_services/top": { "get": { "operationId": "radar-get-ranking-top-internet-services", "summary": "Get top Internet services", "description": "Retrieves top Internet services based on their rank.", "parameters": [ { "name": "serviceCategory", "in": "query", "description": "Filters results by Internet service category.", "schema": { "description": "Filters results by Internet service category.", "type": "array", "items": { "maxLength": 100, "type": "string" }, "example": "Generative AI" } }, { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "date", "in": "query", "description": "Filters results by the specified array of dates.", "schema": { "description": "Filters results by the specified array of dates.", "type": "array", "items": { "format": "date", "type": "string" }, "example": "2022-09-19T00:00:00Z" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "rank": { "type": "integer", "example": 1 }, "service": { "type": "string", "example": "Google" } }, "required": [ "rank", "service" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Internet Services Ranking" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ranking.internet-services", "x-fern-sdk-method-name": "top", "x-forge-hidden": true } }, "/radar/ranking/timeseries_groups": { "get": { "operationId": "radar-get-ranking-domain-timeseries", "summary": "Get domains rank time series", "description": "Retrieves domains rank over time.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "rankingType", "in": "query", "description": "The ranking type.", "schema": { "description": "The ranking type.", "type": "string", "example": "POPULAR", "default": "POPULAR", "enum": [ "POPULAR", "TRENDING_RISE", "TRENDING_STEADY" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 location codes.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 location codes.", "type": "array", "items": { "type": "string" }, "example": "US" } }, { "name": "domains", "in": "query", "description": "Filters results by domain name. Specify a comma-separated list of domain names.", "schema": { "description": "Filters results by domain name. Specify a comma-separated list of domain names.", "type": "array", "items": { "example": "google.com", "maxLength": 253, "minLength": 1, "pattern": "^(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)\\.)+(?:[A-Za-z]{2,63})$", "type": "string" }, "example": "google.com,facebook.com" } }, { "name": "domainCategory", "in": "query", "description": "Filters results by domain category.", "schema": { "description": "Filters results by domain category.", "type": "array", "items": { "maxLength": 100, "type": "string" }, "example": "News & Media" } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "google.com": [ 2 ], "timestamps": [ "2022-09-02T00:00:00Z" ] }, "additionalProperties": { "items": { "anyOf": [ { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, { "type": "number" } ], "description": "A numeric string." }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Domains Ranking" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ranking", "x-fern-sdk-method-name": "timeseries-groups", "x-forge-hidden": true } }, "/radar/ranking/top": { "get": { "operationId": "radar-get-ranking-top-domains", "summary": "Get top or trending domains", "description": "Retrieves the top or trending domains based on their rank. Popular domains are domains of broad appeal based on how people use the Internet. Trending domains are domains that are generating a surge in interest. For more information on top domains, see https://blog.cloudflare.com/radar-domain-rankings/.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 location codes.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 location codes.", "type": "array", "items": { "type": "string" }, "example": "US" } }, { "name": "domainCategory", "in": "query", "description": "Filters results by domain category.", "schema": { "description": "Filters results by domain category.", "type": "array", "items": { "maxLength": 100, "type": "string" }, "example": "News & Media" } }, { "name": "date", "in": "query", "description": "Filters results by the specified array of dates.", "schema": { "description": "Filters results by the specified array of dates.", "type": "array", "items": { "format": "date", "type": "string" }, "example": "2022-09-19T00:00:00Z" } }, { "name": "rankingType", "in": "query", "description": "The ranking type.", "schema": { "description": "The ranking type.", "type": "string", "example": "POPULAR", "default": "POPULAR", "enum": [ "POPULAR", "TRENDING_RISE", "TRENDING_STEADY" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "categories": { "type": "array", "items": { "properties": { "id": { "type": "number", "example": 81 }, "name": { "type": "string", "example": "Content Servers" }, "superCategoryId": { "type": "number", "example": 26 } }, "required": [ "superCategoryId", "name", "id" ], "type": "object" } }, "domain": { "type": "string", "example": "google.com" }, "pctRankChange": { "description": "Only available in TRENDING rankings.", "type": "number", "example": 10.8 }, "rank": { "type": "integer", "example": 1 } }, "required": [ "rank", "domain", "categories" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Domains Ranking" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.ranking", "x-fern-sdk-method-name": "top", "x-forge-hidden": true } }, "/radar/robots_txt/top/domain_categories": { "get": { "operationId": "radar-get-robots-txt-top-domain-categories-by-files-parsed", "summary": "Get top domain categories by robots.txt files parsed", "description": "Retrieves the top domain categories by the number of robots.txt files parsed.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "userAgentCategory", "in": "query", "description": "Filters results by user agent category.", "schema": { "description": "Filters results by user agent category.", "type": "string", "example": "AI", "default": "AI", "enum": [ "AI" ] } }, { "name": "date", "in": "query", "description": "Filters results by the specified array of dates.", "schema": { "description": "Filters results by the specified array of dates.", "type": "array", "items": { "format": "date", "type": "string" }, "example": "2022-09-19T00:00:00Z" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "News & Media" }, "value": { "type": "integer", "example": 273 } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Robots.txt" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.robots-txt.top", "x-fern-sdk-method-name": "domain-categories", "x-forge-hidden": true } }, "/radar/robots_txt/top/user_agents/directive": { "get": { "operationId": "radar-get-robots-txt-top-user-agents-by-directive", "summary": "Get top user agents on robots.txt files", "description": "Retrieves the top user agents on robots.txt files.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "userAgentCategory", "in": "query", "description": "Filters results by user agent category.", "schema": { "description": "Filters results by user agent category.", "type": "string", "example": "AI", "default": "AI", "enum": [ "AI" ] } }, { "name": "date", "in": "query", "description": "Filters results by the specified array of dates.", "schema": { "description": "Filters results by the specified array of dates.", "type": "array", "items": { "format": "date", "type": "string" }, "example": "2022-09-19T00:00:00Z" } }, { "name": "domainCategory", "in": "query", "description": "Filters results by domain category.", "schema": { "description": "Filters results by domain category.", "type": "array", "items": { "maxLength": 100, "type": "string" }, "example": "News & Media" } }, { "name": "directive", "in": "query", "description": "Filters results by robots.txt directive.", "schema": { "description": "Filters results by robots.txt directive.", "type": "string", "enum": [ "ALLOW", "DISALLOW" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "fully": { "type": "integer", "example": 235 }, "name": { "type": "string", "example": "GPTBot" }, "partially": { "type": "integer", "example": 38 }, "value": { "type": "integer", "example": 273 } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Robots.txt" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.robots-txt.top.user-agents", "x-fern-sdk-method-name": "directive", "x-forge-hidden": true } }, "/radar/search/global": { "get": { "operationId": "radar-get-search-global", "summary": "Search for locations, ASes, reports, and more", "description": "Searches for locations, autonomous systems, reports, bots, certificate logs, certificate authorities, industries and verticals. Location names can be localized by sending an `Accept-Language` HTTP header with a BCP 47 language tag (e.g., `Accept-Language: pt-PT`). The full quality-value chain is supported (e.g., `pt-PT,pt;q=0.9,en;q=0.8`).", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per search category.", "schema": { "description": "Limits the number of objects per search category.", "type": "number" } }, { "name": "query", "in": "query", "description": "String used to perform the search operation.", "required": true, "schema": { "description": "String used to perform the search operation.", "type": "string", "example": "United" } }, { "name": "include", "in": "query", "description": "Search types included in results.", "schema": { "description": "Search types included in results.", "type": "array", "items": { "enum": [ "ADM1S", "ASNS", "BOTS", "CERTIFICATE_AUTHORITIES", "CERTIFICATE_LOGS", "ORIGINS", "ORIGIN_REGIONS", "INDUSTRIES", "LOCATIONS", "NOTEBOOKS", "TLDS", "VERTICALS" ], "type": "string" } } }, { "name": "exclude", "in": "query", "description": "Search types excluded from results.", "schema": { "description": "Search types excluded from results.", "type": "array", "items": { "enum": [ "ADM1S", "ASNS", "BOTS", "CERTIFICATE_AUTHORITIES", "CERTIFICATE_LOGS", "ORIGINS", "ORIGIN_REGIONS", "INDUSTRIES", "LOCATIONS", "NOTEBOOKS", "TLDS", "VERTICALS" ], "type": "string" } } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "search": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "13335" }, "name": { "type": "string", "example": "Cloudflare" }, "type": { "type": "string", "example": "asn" } }, "required": [ "code", "name", "type" ], "type": "object" } } }, "required": [ "search" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Search" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.search", "x-fern-sdk-method-name": "global", "x-forge-hidden": true } }, "/radar/tcp_resets_timeouts/summary": { "get": { "operationId": "radar-get-tcp-resets-timeouts-summary", "summary": "Get TCP resets and timeouts summary", "description": "Retrieves the distribution of connection stage by TCP connections terminated within the first 10 packets by a reset or timeout.", "parameters": [ { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "properties": { "later_in_flow": { "description": "Connection resets within the first 10 packets from the client, but after the server has received multiple data packets.", "type": "string", "example": "10" }, "no_match": { "description": "All other connections.", "type": "string", "example": "65" }, "post_ack": { "description": "Connection resets or timeouts after the server received both a SYN packet and an ACK packet, meaning the connection was successfully established.", "type": "string", "example": "5" }, "post_psh": { "description": "Connection resets or timeouts after the server received a packet with PSH flag set, following connection establishment.", "type": "string", "example": "10" }, "post_syn": { "description": "Connection resets or timeouts after the server received only a single SYN packet.", "type": "string", "example": "10" } }, "required": [ "no_match", "post_syn", "post_ack", "post_psh", "later_in_flow" ] } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar TCP Resets and Timeouts" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.tcp-resets-timeouts", "x-fern-sdk-method-name": "summary", "x-forge-hidden": true } }, "/radar/tcp_resets_timeouts/timeseries_groups": { "get": { "operationId": "radar-get-tcp-resets-timeouts-timeseries-group", "summary": "Get TCP resets and timeouts time series", "description": "Retrieves the distribution of connection stage by TCP connections terminated within the first 10 packets by a reset or timeout over time.", "parameters": [ { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "properties": { "later_in_flow": { "type": "array", "items": { "description": "Connection resets within the first 10 packets from the client, but after the server has received multiple data packets.", "example": "10", "type": "string" } }, "no_match": { "type": "array", "items": { "description": "All other connections.", "example": "65", "type": "string" } }, "post_ack": { "type": "array", "items": { "description": "Connection resets or timeouts after the server received both a SYN packet and an ACK packet, meaning the connection was successfully established.", "example": "5", "type": "string" } }, "post_psh": { "type": "array", "items": { "description": "Connection resets or timeouts after the server received a packet with PSH flag set, following connection establishment.", "example": "10", "type": "string" } }, "post_syn": { "type": "array", "items": { "description": "Connection resets or timeouts after the server received only a single SYN packet.", "example": "10", "type": "string" } }, "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps", "no_match", "post_syn", "post_ack", "post_psh", "later_in_flow" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar TCP Resets and Timeouts" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.tcp-resets-timeouts", "x-fern-sdk-method-name": "timeseries-groups", "x-forge-hidden": true } }, "/radar/tlds": { "get": { "operationId": "radar-get-tlds", "summary": "List TLDs", "description": "Retrieves a list of TLDs.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Skips the specified number of objects before fetching the results.", "schema": { "description": "Skips the specified number of objects before fetching the results.", "type": "integer", "minimum": 0 } }, { "name": "tldManager", "in": "query", "description": "Filters results by TLD manager.", "schema": { "description": "Filters results by TLD manager.", "type": "string", "maxLength": 100 } }, { "name": "tldType", "in": "query", "description": "Filters results by TLD type.", "schema": { "description": "Filters results by TLD type.", "type": "string", "enum": [ "GENERIC", "COUNTRY_CODE", "GENERIC_RESTRICTED", "INFRASTRUCTURE", "SPONSORED" ] } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain. Specify a comma-separated list of TLDs.", "schema": { "description": "Filters results by top-level domain. Specify a comma-separated list of TLDs.", "type": "string", "example": "com,pt" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "tlds": { "type": "array", "items": { "properties": { "manager": { "description": "The organization that manages the TLD.", "type": "string", "example": "VeriSign Global Registry Services" }, "tld": { "description": "The actual TLD.", "type": "string", "example": "com" }, "type": { "description": "The type of TLD.", "type": "string", "example": "GENERIC" } }, "required": [ "tld", "type", "manager" ], "type": "object" } } }, "required": [ "tlds" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Top-Level Domains" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.tlds", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/radar/tlds/performance/summary/{dimension}": { "get": { "operationId": "radar-get-tlds-performance-summary", "summary": "Get TLD Performance Summary", "description": "Returns a summary of TLD authoritative nameserver performance grouped by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Dimension to summarize TLD nameserver latency by.", "required": true, "schema": { "description": "Dimension to summarize TLD nameserver latency by.", "type": "string", "enum": [ "LATENCY", "NAMESERVER_LATENCY", "LOCATION_LATENCY" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain.", "schema": { "description": "Filters results by top-level domain.", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "nameserver", "in": "query", "description": "Filters results by nameserver hostname.", "schema": { "description": "Filters results by nameserver hostname.", "type": "string", "example": "a.gtld-servers.net", "maxLength": 253, "minLength": 1, "pattern": "^(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)\\.)+(?:[A-Za-z]{2,63})$" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "summary_0": { "type": "object", "example": { "a.gtld-servers.net": "2.0", "b.gtld-servers.net": "3.0" }, "additionalProperties": { "description": "A numeric string.", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" } } }, "required": [ "summary_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Top-Level Domains" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.tlds.performance", "x-fern-sdk-method-name": "summary", "x-forge-hidden": true } }, "/radar/tlds/performance/timeseries_groups/{dimension}": { "get": { "operationId": "radar-get-tlds-performance-timeseries-groups", "summary": "Get TLD Performance Over Time", "description": "Returns a timeseries of TLD authoritative nameserver performance grouped by the specified dimension.", "parameters": [ { "name": "dimension", "in": "path", "description": "Dimension for the TLD nameserver latency timeseries.", "required": true, "schema": { "description": "Dimension for the TLD nameserver latency timeseries.", "type": "string", "enum": [ "LATENCY", "NAMESERVER_LATENCY", "LOCATION_LATENCY" ] } }, { "name": "aggInterval", "in": "query", "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "schema": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/). When omitted, the interval is auto-selected from the requested date range; finer intervals are only available for shorter ranges. If the requested interval is too granular for the date range, the request is rejected.", "type": "string", "example": "1h", "enum": [ "15m", "1h", "1d", "1w" ] } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "tld", "in": "query", "description": "Filters results by top-level domain.", "schema": { "description": "Filters results by top-level domain.", "type": "array", "items": { "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$", "type": "string" }, "example": "com" } }, { "name": "nameserver", "in": "query", "description": "Filters results by nameserver hostname.", "schema": { "description": "Filters results by nameserver hostname.", "type": "string", "example": "a.gtld-servers.net", "maxLength": 253, "minLength": 1, "pattern": "^(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)\\.)+(?:[A-Za-z]{2,63})$" } }, { "name": "limitPerGroup", "in": "query", "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "schema": { "description": "Limits the number of objects per group to the top items within the specified time range. When item count exceeds the limit, extra items appear grouped under an \"other\" category. Only supported on high-cardinality dimensions; otherwise the request is rejected. Minimum value is 2.", "type": "integer", "example": 10 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "aggInterval": { "description": "Aggregation interval of the results (e.g., in 15 minutes or 1 hour intervals). Refer to [Aggregation intervals](https://developers.cloudflare.com/radar/concepts/aggregation-intervals/).", "type": "string", "enum": [ "FIFTEEN_MINUTES", "ONE_HOUR", "ONE_DAY", "ONE_WEEK", "ONE_MONTH" ] }, "confidenceInfo": { "type": "object", "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units", "aggInterval" ] }, "serie_0": { "type": "object", "example": { "p25": [ "1.0" ], "p50": [ "2.0" ], "p75": [ "3.0" ], "timestamps": [ "2025-01-01T00:00:00Z" ] }, "additionalProperties": { "items": { "description": "A numeric string.", "example": "10", "nullable": true, "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "type": "array" }, "properties": { "timestamps": { "type": "array", "items": { "format": "date-time", "type": "string" } } }, "required": [ "timestamps" ] } }, "required": [ "serie_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Top-Level Domains" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.tlds.performance", "x-fern-sdk-method-name": "timeseries-groups", "x-forge-hidden": true } }, "/radar/tlds/{tld}": { "get": { "operationId": "radar-get-tld-details", "summary": "Get TLD details", "description": "Retrieves the requested TLD information.", "parameters": [ { "name": "tld", "in": "path", "description": "Top-level domain.", "required": true, "schema": { "description": "Top-level domain.", "type": "string", "example": "com", "maxLength": 63, "minLength": 2, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "tld": { "type": "object", "properties": { "manager": { "description": "The organization that manages the TLD.", "type": "string", "example": "VeriSign Global Registry Services" }, "tld": { "description": "The actual TLD.", "type": "string", "example": "com" }, "type": { "description": "The type of TLD.", "type": "string", "example": "GENERIC" } }, "required": [ "tld", "type", "manager" ] } }, "required": [ "tld" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Top-Level Domains" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.tlds", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/traffic_anomalies": { "get": { "operationId": "radar-get-traffic-anomalies", "summary": "Get latest Internet traffic anomalies", "description": "Retrieves the latest Internet traffic anomalies, which are signals that might indicate an outage. These alerts are automatically detected by Radar and manually verified by our team.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Skips the specified number of objects before fetching the results.", "schema": { "description": "Skips the specified number of objects before fetching the results.", "type": "integer", "minimum": 0 } }, { "name": "dateRange", "in": "query", "description": "Filters results by a relative date range ending at the current time. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`), e.g. `7d`. Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `3dcontrol` covers days -10 to -7, `7dcontrol` covers days -14 to -7, `28dcontrol` covers days -56 to -28, and `10dcontrol` covers days -24 to -14). Mutually exclusive with `dateStart`/`dateEnd`.", "schema": { "description": "Filters results by a relative date range ending at the current time. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`), e.g. `7d`. Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `3dcontrol` covers days -10 to -7, `7dcontrol` covers days -14 to -7, `28dcontrol` covers days -56 to -28, and `10dcontrol` covers days -24 to -14). Mutually exclusive with `dateStart`/`dateEnd`.", "type": "string", "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "schema": { "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "VERIFIED", "UNVERIFIED" ] } }, { "name": "type", "in": "query", "description": "Filters results by entity type (LOCATION, AS, or ORIGIN).", "schema": { "description": "Filters results by entity type (LOCATION, AS, or ORIGIN).", "type": "array", "items": { "enum": [ "LOCATION", "AS", "ORIGIN" ], "type": "string" }, "example": "LOCATION" } }, { "name": "dataSource", "in": "query", "description": "Filters results by data source.", "schema": { "description": "Filters results by data source.", "type": "string", "example": "ALL", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify a single Autonomous System Number (ASN) as integer.", "schema": { "description": "Filters results by Autonomous System. Specify a single Autonomous System Number (ASN) as integer.", "type": "integer", "example": 174 } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify an alpha-2 location code.", "schema": { "description": "Filters results by location. Specify an alpha-2 location code.", "type": "string", "example": "US", "maxLength": 2, "minLength": 2 } }, { "name": "origin", "in": "query", "description": "Filters results by origin.", "schema": { "description": "Filters results by origin.", "type": "string", "example": "amazon-us-east-1", "maxLength": 100 } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "List of Internet traffic anomalies.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "trafficAnomalies": { "type": "array", "items": { "properties": { "asnDetails": { "type": "object", "nullable": true, "properties": { "asn": { "type": "string", "example": "189" }, "location": { "type": "object", "nullable": true, "properties": { "code": { "type": "string", "example": "US" }, "name": { "type": "string", "example": "United States" } }, "required": [ "code", "name" ] }, "name": { "type": "string", "example": "LUMEN-LEGACY-L3-PARTITION", "nullable": true } }, "required": [ "asn", "name", "location" ] }, "endDate": { "type": "string", "format": "date-time", "nullable": true }, "locationDetails": { "type": "object", "nullable": true, "properties": { "code": { "type": "string", "example": "US" }, "name": { "type": "string", "example": "United States" } }, "required": [ "code", "name" ] }, "originDetails": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "example": "us-east-1 Amazon Web Services", "nullable": true }, "origin": { "type": "string", "example": "amazon-us-east-1" } }, "required": [ "origin", "name" ] }, "startDate": { "type": "string", "example": "2023-08-02T23:15:00Z" }, "status": { "type": "string", "example": "UNVERIFIED" }, "type": { "type": "string", "example": "LOCATION" }, "uuid": { "type": "string", "example": "55a57f33-8bc0-4984-b4df-fdaff72df39d" }, "visibleInDataSources": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "required": [ "visibleInDataSources", "uuid", "type", "status", "startDate", "endDate", "locationDetails", "asnDetails", "originDetails" ], "type": "object" } } }, "required": [ "trafficAnomalies" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Traffic Anomalies" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.traffic-anomalies", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/traffic_anomalies/locations": { "get": { "operationId": "radar-get-traffic-anomalies-top", "summary": "Get top locations by total traffic anomalies", "description": "Retrieves the sum of Internet traffic anomalies, grouped by location. These anomalies are signals that might indicate an outage, automatically detected by Radar and manually verified by our team.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "dateRange", "in": "query", "description": "Filters results by a relative date range ending at the current time. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`), e.g. `7d`. Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `3dcontrol` covers days -10 to -7, `7dcontrol` covers days -14 to -7, `28dcontrol` covers days -56 to -28, and `10dcontrol` covers days -24 to -14). Mutually exclusive with `dateStart`/`dateEnd`.", "schema": { "description": "Filters results by a relative date range ending at the current time. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`), e.g. `7d`. Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `3dcontrol` covers days -10 to -7, `7dcontrol` covers days -14 to -7, `28dcontrol` covers days -56 to -28, and `10dcontrol` covers days -24 to -14). Mutually exclusive with `dateStart`/`dateEnd`.", "type": "string", "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "schema": { "description": "Start of the date range (inclusive). Alternative to `dateRange`; provide together with `dateEnd`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`.", "type": "string", "format": "date-time", "example": "2023-09-01T11:41:33.782Z" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "VERIFIED", "UNVERIFIED" ] } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "List of locations with number of traffic anomalies.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "trafficAnomalies": { "type": "array", "items": { "properties": { "clientCountryAlpha2": { "type": "string", "example": "PT" }, "clientCountryName": { "type": "string", "example": "Portugal" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "clientCountryAlpha2", "clientCountryName", "value" ], "type": "object" } } }, "required": [ "trafficAnomalies" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" } }, "result": { "type": "object" }, "success": { "type": "boolean", "example": false } }, "required": [ "result", "success", "errors" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Traffic Anomalies" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.traffic-anomalies.locations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/radar/traffic_anomalies/{uuid}": { "get": { "operationId": "radar-get-traffic-anomaly-by-uuid", "summary": "Get traffic anomaly by UUID", "description": "Retrieves a single Internet traffic anomaly by UUID.", "parameters": [ { "name": "uuid", "in": "path", "description": "Traffic anomaly UUID.", "required": true, "schema": { "description": "Traffic anomaly UUID.", "type": "string", "example": "b1bcd2c3-4cf0-4dad-b90f-719388bf6460", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Internet traffic anomaly.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "trafficAnomaly": { "type": "object", "properties": { "asnDetails": { "type": "object", "nullable": true, "properties": { "asn": { "type": "string", "example": "189" }, "location": { "type": "object", "nullable": true, "properties": { "code": { "type": "string", "example": "US" }, "name": { "type": "string", "example": "United States" } }, "required": [ "code", "name" ] }, "name": { "type": "string", "example": "LUMEN-LEGACY-L3-PARTITION", "nullable": true } }, "required": [ "asn", "name", "location" ] }, "endDate": { "type": "string", "format": "date-time", "nullable": true }, "locationDetails": { "type": "object", "nullable": true, "properties": { "code": { "type": "string", "example": "US" }, "name": { "type": "string", "example": "United States" } }, "required": [ "code", "name" ] }, "originDetails": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "example": "us-east-1 Amazon Web Services", "nullable": true }, "origin": { "type": "string", "example": "amazon-us-east-1" } }, "required": [ "origin", "name" ] }, "startDate": { "type": "string", "example": "2023-08-02T23:15:00Z" }, "status": { "type": "string", "example": "UNVERIFIED" }, "type": { "type": "string", "example": "LOCATION" }, "uuid": { "type": "string", "example": "55a57f33-8bc0-4984-b4df-fdaff72df39d" }, "visibleInDataSources": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "required": [ "visibleInDataSources", "uuid", "type", "status", "startDate", "endDate", "locationDetails", "asnDetails", "originDetails" ] } }, "required": [ "trafficAnomaly" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Traffic Anomalies" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "radar.traffic-anomalies", "x-fern-sdk-method-name": "getById", "x-forge-hidden": true } }, "/radar/verified_bots/top/bots": { "get": { "operationId": "radar-get-verified-bots-top-by-http-requests", "summary": "Get top verified bots by HTTP requests", "description": "Retrieves the top verified bots by HTTP requests, with owner and category.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "botCategory": { "type": "string", "example": "Search Engine Crawler" }, "botName": { "type": "string", "example": "GoogleBot" }, "botOwner": { "type": "string", "example": "Google" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "botName", "botCategory", "botOwner", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Verified Bots" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.verified-bots.top", "x-fern-sdk-method-name": "bots", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Bots API](https://developers.cloudflare.com/api/resources/radar/subresources/bots/) instead." } }, "/radar/verified_bots/top/categories": { "get": { "operationId": "radar-get-verified-bots-top-categories-by-http-requests", "summary": "Get top verified bot categories by HTTP requests", "description": "Retrieves the top verified bot categories by HTTP requests, along with their corresponding percentage, over the total verified bot HTTP requests.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of objects returned in the response.", "schema": { "description": "Limits the number of objects returned in the response.", "type": "integer", "example": 5, "default": 5, "exclusiveMinimum": true, "minimum": 0 } }, { "name": "name", "in": "query", "description": "Array of names used to label the series in the response.", "schema": { "description": "Array of names used to label the series in the response.", "type": "array", "items": { "example": "main_series", "type": "string" } } }, { "name": "dateRange", "in": "query", "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "schema": { "description": "Filters results by relative date range ending at the current time, with each value producing a separate series. Use `d` for days (up to `364d`) or `w` for weeks (up to `52w`). Append `control` to request the equivalent previous period for comparison: the comparison window is shifted back by the current window's length rounded up to a whole number of weeks, so it keeps the same weekday alignment and does not overlap the current window (e.g. `7dcontrol` covers days -14 to -7, `10dcontrol` covers days -24 to -14). For example, pass `7d` and `7dcontrol` to compare this week with the previous week. All series must resolve to the same duration as the main series; relative ranges (including `control`) satisfy this automatically. Use this parameter or set specific start and end dates (`dateStart` and `dateEnd` parameters).", "type": "array", "items": { "example": "7d", "pattern": "^((([1-9]|[1-9][0-9]|[1-2][0-9][0-9]|3[0-5][0-9]|36[0-4])[d](control)?)|(([1-9]|[1-4][0-9]|5[0-2])[w](control)?))$", "type": "string" }, "example": "7d" } }, { "name": "dateStart", "in": "query", "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "Start of the date range. Alternative to `dateRange`; provide together with `dateEnd`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "dateEnd", "in": "query", "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "schema": { "description": "End of the date range (inclusive). Alternative to `dateRange`; provide together with `dateStart`. When requesting comparison series, every series must resolve to the same duration as the main series. Each `dateStart`/`dateEnd` is floored to the nearest 15 minutes before evaluation, so windows whose durations match only before alignment may be rejected.", "type": "array", "items": { "format": "date-time", "type": "string" }, "example": "2023-09-01T11:41:33.782Z" } }, { "name": "asn", "in": "query", "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "schema": { "description": "Filters results by Autonomous System. Specify one or more Autonomous System Numbers (ASNs) as a comma-separated list. Prefix with `-` to exclude ASNs from results. For example, `-174, 3356` excludes results from AS174, but includes results from AS3356.", "type": "array", "items": { "type": "string" }, "example": "15169" } }, { "name": "location", "in": "query", "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "schema": { "description": "Filters results by location. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude locations from results. For example, `-US,PT` excludes results from the US, but includes results from PT.", "type": "array", "items": { "type": "string" }, "example": "US,CA" } }, { "name": "continent", "in": "query", "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "schema": { "description": "Filters results by continent. Specify a comma-separated list of alpha-2 codes. Prefix with `-` to exclude continents from results. For example, `-EU,NA` excludes results from EU, but includes results from NA.", "type": "array", "items": { "type": "string" }, "example": "EU,NA" } }, { "name": "format", "in": "query", "description": "Format in which results will be returned.", "schema": { "description": "Format in which results will be returned.", "type": "string", "example": "json", "enum": [ "JSON", "CSV" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "meta": { "description": "Metadata for the results.", "type": "object", "properties": { "confidenceInfo": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "items": { "description": "Annotation associated with the result (e.g. outage or other type of event).", "properties": { "dataSource": { "description": "Data source for annotations.", "type": "string", "enum": [ "ALL", "AI_BOTS", "AI_GATEWAY", "BGP", "BOTS", "CONNECTION_ANOMALY", "CT", "DNS", "DNS_MAGNITUDE", "DNS_AS112", "DOS", "EMAIL_ROUTING", "EMAIL_SECURITY", "FW", "FW_PG", "HTTP", "HTTP_CONTROL", "HTTP_CRAWLER_REFERER", "HTTP_ORIGINS", "IQI", "LEAKED_CREDENTIALS", "NET", "ROBOTS_TXT", "SPEED", "WORKERS_AI" ] }, "description": { "type": "string", "example": "Cable cut in Tonga" }, "endDate": { "type": "string", "format": "date-time" }, "eventType": { "description": "Event type for annotations.", "type": "string", "enum": [ "GENERAL", "OUTAGE", "PARTIAL_PROJECTION", "PIPELINE", "TRAFFIC_ANOMALY" ] }, "isInstantaneous": { "description": "Whether event is a single point in time or a time range.", "type": "boolean" }, "linkedUrl": { "type": "string", "format": "uri" }, "startDate": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "example": "BOT_CLASS", "type": "string" } } }, "required": [ "dataSource", "eventType", "description", "startDate", "endDate", "linkedUrl", "isInstantaneous" ], "type": "object" } }, "level": { "description": "Provides an indication of how much confidence Cloudflare has in the data.", "type": "integer" } }, "required": [ "level", "annotations" ] }, "dateRange": { "type": "array", "items": { "properties": { "endTime": { "description": "Adjusted end of date range.", "type": "string", "format": "date-time", "example": "2022-09-17T10:22:57.555Z" }, "startTime": { "description": "Adjusted start of date range.", "type": "string", "format": "date-time", "example": "2022-09-16T10:22:57.555Z" } }, "required": [ "startTime", "endTime" ], "type": "object" } }, "lastUpdated": { "description": "Timestamp of the last dataset update.", "type": "string", "format": "date-time" }, "normalization": { "description": "Normalization method applied to the results. Refer to [Normalization methods](https://developers.cloudflare.com/radar/concepts/normalization/).", "type": "string", "enum": [ "PERCENTAGE", "MIN0_MAX", "MIN_MAX", "RAW_VALUES", "PERCENTAGE_CHANGE", "ROLLING_AVERAGE", "OVERLAPPED_PERCENTAGE", "RATIO" ] }, "units": { "description": "Measurement units for the results.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "*" }, "value": { "type": "string", "example": "requests" } }, "required": [ "name", "value" ], "type": "object" } } }, "required": [ "dateRange", "confidenceInfo", "normalization", "lastUpdated", "units" ] }, "top_0": { "type": "array", "items": { "properties": { "botCategory": { "type": "string", "example": "Search" }, "value": { "description": "A numeric string.", "type": "string", "example": "10", "pattern": "^-?\\d+(\\.\\d+)?$" } }, "required": [ "botCategory", "value" ], "type": "object" } } }, "required": [ "top_0", "meta" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "result", "success" ] } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found." } }, "required": [ "error" ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Radar Verified Bots" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "radar.verified-bots.top", "x-fern-sdk-method-name": "categories", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Radar Bots API](https://developers.cloudflare.com/api/resources/radar/subresources/bots/) instead." } }, "/ready": { "get": { "operationId": "getReady", "summary": "Run readiness checks", "description": "Return a success message after running readiness checks", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "brand_protection" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ready", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/signed-url": { "get": { "operationId": "getSignedUrl", "summary": "Internal route for testing signed URLs", "description": "Internal route for testing signed URLs.", "responses": { "default": { "$ref": "#/components/responses/brand-protection-api_DEFAULT_ERROR" } }, "security": [ { "api_token": [] } ], "tags": [ "logo_match" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "signed-url", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/tenants/{tenant_id}": { "get": { "operationId": "Tenants_retrieveTenant", "summary": "Get tenant", "description": "Retrieves a Tenant by Tenant ID.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "$ref": "#/components/schemas/organizations-api_Tenant" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Tenants" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "tenant", "x-fern-sdk-method-name": "get" } }, "/tenants/{tenant_id}/account_types": { "get": { "operationId": "Tenants_validAccountTypes", "summary": "Get tenant account types", "description": "List of account types available for the Tenant to provision accounts.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "type": "array", "items": { "type": "string" } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Tenants" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "tenant.account-type", "x-fern-sdk-method-name": "list" } }, "/tenants/{tenant_id}/accounts": { "get": { "operationId": "Tenants_listAccounts", "summary": "List tenant accounts", "description": "List of accounts for the Tenant.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_Account" } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Tenants" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "tenant.account", "x-fern-sdk-method-name": "list" } }, "/tenants/{tenant_id}/entitlements": { "get": { "operationId": "Tenants_listEntitlements", "summary": "List tenant entitlements", "description": "List of innate entitlements available for the Tenant.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "$ref": "#/components/schemas/organizations-api_InnateEntitlements" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Tenants" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "tenant.entitlement", "x-fern-sdk-method-name": "list" } }, "/tenants/{tenant_id}/memberships": { "get": { "operationId": "Tenants_listMemberships", "summary": "List tenant memberships", "description": "List of active members (Cloudflare users) for the Tenant.", "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_TenantMembership" } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Tenants" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "tenant.membership", "x-fern-sdk-method-name": "list" } }, "/tenants/{tenant_tag}/custom_ns": { "get": { "operationId": "tenant-level-custom-nameservers-list-tenant-custom-nameservers", "summary": "List Tenant Custom Nameservers", "description": "Lists a tenant's custom nameservers.", "parameters": [ { "name": "tenant_tag", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-custom-nameservers_identifier-3" } } ], "responses": { "200": { "description": "List Tenant Custom Nameservers response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-custom-nameservers_tcns_response_collection" } } } }, "4XX": { "description": "List Tenant Custom Nameservers response failure.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_tcns_response_collection" }, { "$ref": "#/components/schemas/dns-custom-nameservers_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Tenant-Level Custom Nameservers" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "tenant-custom-nameservers", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "tenant-level-custom-nameservers-add-tenant-custom-nameserver", "summary": "Add Tenant Custom Nameserver", "description": "Adds a custom nameserver for a tenant.", "parameters": [ { "name": "tenant_tag", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-custom-nameservers_identifier-3" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-custom-nameservers_CustomNSInput" } } } }, "responses": { "200": { "description": "Add Tenant Custom Nameserver response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-custom-nameservers_tcns_response_single" } } } }, "4XX": { "description": "Add Tenant Custom Nameserver response failure.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_tcns_response_single" }, { "$ref": "#/components/schemas/dns-custom-nameservers_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Tenant-Level Custom Nameservers" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "tenant-custom-nameservers", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/tenants/{tenant_tag}/custom_ns/{custom_ns_id}": { "delete": { "operationId": "tenant-level-custom-nameservers-delete-tenant-custom-nameserver", "summary": "Delete Tenant Custom Nameserver", "description": "Deletes a tenant's custom nameserver.", "parameters": [ { "name": "custom_ns_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-custom-nameservers_ns_name" } }, { "name": "tenant_tag", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-custom-nameservers_identifier-3" } } ], "responses": { "200": { "description": "Delete Tenant Custom Nameserver response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-custom-nameservers_empty_response-3" } } } }, "4XX": { "description": "Delete Tenant Custom Nameserver response failure.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_empty_response-3" }, { "$ref": "#/components/schemas/dns-custom-nameservers_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Tenant-Level Custom Nameservers" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "tenant-custom-nameservers", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true } }, "/user": { "get": { "operationId": "user-user-details", "summary": "User Details", "description": "Retrieves detailed information about the currently authenticated user, including email, name, and account memberships.", "responses": { "200": { "description": "User Details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_single_user_response" } } } }, "4XX": { "description": "User Details response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "User" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.user.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "user-edit-user", "summary": "Edit User", "description": "Edit part of your user details.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "country": { "$ref": "#/components/schemas/iam_country" }, "first_name": { "$ref": "#/components/schemas/iam_first_name" }, "last_name": { "$ref": "#/components/schemas/iam_last_name" }, "telephone": { "$ref": "#/components/schemas/iam_telephone" }, "zipcode": { "$ref": "#/components/schemas/iam_zipcode" } } } } } }, "responses": { "200": { "description": "Edit User response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_single_user_response" } } } }, "4XX": { "description": "Edit User response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "User" ], "x-api-token-group": [ "User Details Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.user.update" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/user/analytics/dashboard": { "get": { "operationId": "user-analytics-get-dashboard", "summary": "Get user analytics dashboard", "description": "The user analytics dashboard provides totals and timeseries data aggregated\nacross all zones owned by the authenticated user for the given time period.\nOnly zones for which the user has the `#analytics:read` permission are included.\n\nThis endpoint is deprecated. Please use the GraphQL Analytics API instead:\nhttps://developers.cloudflare.com/analytics/graphql-api/", "parameters": [ { "name": "since", "in": "query", "schema": { "$ref": "#/components/schemas/zone-analytics-api_since" } }, { "name": "until", "in": "query", "schema": { "$ref": "#/components/schemas/zone-analytics-api_until" } }, { "name": "continuous", "in": "query", "schema": { "description": "When set to true, the API will move the requested time window backward,\nuntil it finds a region with completely aggregated data.\n\nThe API response _may not represent the requested time window_.", "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Get user analytics dashboard response", "content": { "application/json": { "examples": { "success": { "summary": "Successful user analytics dashboard response", "value": { "errors": [], "messages": [], "query": { "since": "2015-01-01T12:23:00Z", "until": "2015-01-02T12:23:00Z" }, "result": [ { "timeseries": [ { "bandwidth": { "all": 190290, "cached": 97717, "uncached": 92573 }, "requests": { "all": 51440 }, "since": "2015-01-01T12:23:00Z", "until": "2015-01-01T13:23:00Z" } ], "totals": { "bandwidth": { "all": 4567890, "cached": 2345678, "uncached": 2222212 }, "requests": { "all": 1234567 }, "since": "2015-01-01T12:23:00Z", "until": "2015-01-02T12:23:00Z" }, "zone_id": "023e105f4ecef8ad9ca31a8372d0c353" } ], "success": true } } }, "schema": { "$ref": "#/components/schemas/zone-analytics-api_user_dashboard_response" } } } }, "4XX": { "description": "Get user analytics dashboard response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zone-analytics-api_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] } ], "tags": [ "User Analytics (Deprecated)" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-cfPermissionsRequired": { "enum": [ "#analytics:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "user.analytics.dashboard", "x-fern-sdk-method-name": "get", "x-stainless-deprecation-message": "This endpoint is deprecated and will be removed in a future version. Please use the GraphQL Analytics API instead: https://developers.cloudflare.com/analytics/graphql-api/ It provides equivalent data and more features, including the ability to select only the metrics you need. Migration guide: https://developers.cloudflare.com/analytics/migration-guides/zone-analytics/\n" } }, "/user/audit_logs": { "get": { "operationId": "audit-logs-get-user-audit-logs", "summary": "Get user audit logs", "description": "Gets a list of audit logs for a user account. Can be filtered by who made the change, on which zone, and the timeframe of the change.", "parameters": [ { "name": "id", "in": "query", "schema": { "description": "Finds a specific log by its ID.", "type": "string", "example": "f174be97-19b1-40d6-954d-70cd5fbd52db" } }, { "name": "export", "in": "query", "schema": { "description": "Indicates that this request is an export of logs in CSV format.", "type": "boolean", "example": true } }, { "name": "action.type", "in": "query", "schema": { "description": "Filters by the action type.", "type": "string", "example": "add" } }, { "name": "actor.ip", "in": "query", "schema": { "description": "Filters by the IP address of the request that made the change by specific IP address or valid CIDR Range.", "type": "string", "example": "17.168.228.63" } }, { "name": "actor.email", "in": "query", "schema": { "description": "Filters by the email address of the actor that made the change.", "type": "string", "format": "email", "example": "alice@example.com" } }, { "name": "since", "in": "query", "schema": { "oneOf": [ { "description": "Limits the returned results to logs newer than the specified date. A `full-date` that conforms to RFC3339.", "example": "2019-04-30", "format": "date", "type": "string" }, { "description": "Limits the returned results to logs newer than the specified date. A `date-time` that conforms to RFC3339.", "example": "2019-04-30T01:12:20Z", "format": "date-time", "type": "string" } ] } }, { "name": "before", "in": "query", "schema": { "oneOf": [ { "description": "Limits the returned results to logs older than the specified date. A `full-date` that conforms to RFC3339.", "example": "2019-04-30", "format": "date", "type": "string" }, { "description": "Limits the returned results to logs older than the specified date. A `date-time` that conforms to RFC3339.", "example": "2019-04-30T01:12:20Z", "format": "date-time", "type": "string" } ] } }, { "name": "zone.name", "in": "query", "schema": { "description": "Filters by the name of the zone associated to the change.", "type": "string", "example": "example.com" } }, { "name": "direction", "in": "query", "schema": { "description": "Changes the direction of the chronological sorting.", "type": "string", "example": "desc", "default": "desc", "enum": [ "desc", "asc" ] } }, { "name": "per_page", "in": "query", "schema": { "description": "Sets the number of results to return per page.", "type": "number", "example": 25, "default": 100, "maximum": 1000, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "description": "Defines which page of results to return.", "type": "number", "example": 50, "default": 1, "minimum": 1 } }, { "name": "hide_user_logs", "in": "query", "schema": { "description": "Indicates whether or not to hide user level audit logs.", "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Get user audit logs response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/aaa_audit_logs_response_collection" } } } }, "4XX": { "description": "Get user audit logs response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aaa_audit_logs_response_collection" }, { "$ref": "#/components/schemas/aaa_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Audit Logs" ], "x-api-token-group": [ "Account Settings Write", "Account Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.audit-logs", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/user/billing/history": { "get": { "operationId": "user-billing-history-(-deprecated)-billing-history-details", "summary": "Billing History Details", "description": "Accesses your billing history object.", "parameters": [ { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of items per page.", "type": "number", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "order", "in": "query", "schema": { "description": "Field to order billing history by.", "type": "string", "example": "occurred_at", "enum": [ "type", "occurred_at", "action" ] } }, { "name": "occurred_at", "in": "query", "schema": { "$ref": "#/components/schemas/bill-subs-api_occurred_at" } }, { "name": "type", "in": "query", "schema": { "description": "The billing item type.", "type": "string", "example": "charge", "maxLength": 30, "readOnly": true } }, { "name": "action", "in": "query", "schema": { "description": "The billing item action.", "type": "string", "example": "subscription", "maxLength": 30, "readOnly": true } } ], "responses": { "200": { "description": "Billing History Details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_billing_history_collection" } } } }, "4XX": { "description": "Billing History Details response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "User Billing History" ], "x-api-token-group": [ "Billing Write", "Billing Read" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.billing.history", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/user/billing/profile": { "get": { "operationId": "user-billing-profile-(-deprecated)-billing-profile-details", "summary": "Billing Profile Details", "description": "Accesses your billing profile object.", "responses": { "200": { "description": "Billing Profile Details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_billing_response_single" } } } }, "4XX": { "description": "Billing Profile Details response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "User Billing Profile" ], "x-api-token-group": [ "Billing Write", "Billing Read" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.billing.profile", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/user/communication_preferences": { "get": { "operationId": "user-communication-preferences-get", "summary": "Get communication preferences", "description": "Retrieve the communication preferences for the authenticated user, including email verification status, marketing subscription opt-in/opt-out state, and language locale. Callers authenticate with standard Cloudflare API tokens or keys.", "responses": { "200": { "description": "Successfully retrieved communication preferences.", "content": { "application/json": { "examples": { "success": { "summary": "Successful preferences retrieval", "value": { "errors": [], "messages": [], "result": { "created_on": "2024-06-01T14:20:00Z", "email": { "hard_bounce": false, "verified": true }, "language-locale": "en-US", "preferences": { "marketing": { "created_on": "2024-01-15T10:30:00Z", "subscribed": false, "updated_on": "2024-08-12T09:45:00Z" }, "product_news": { "created_on": "2024-01-15T10:30:00Z", "subscribed": true, "updated_on": "2024-06-01T14:20:00Z" } }, "updated_on": "2024-08-12T09:45:00Z" }, "success": true } } }, "schema": { "$ref": "#/components/schemas/cps_communication_preferences_response" } } } }, "400": { "description": "The request contains invalid parameters.", "content": { "application/json": { "examples": { "recipient_invalid": { "summary": "Recipient ID is invalid (zero)", "value": { "errors": [ { "code": 4002, "message": "Invalid request" } ], "messages": [], "result": [], "success": false } }, "recipient_not_present": { "summary": "Recipient ID not present in request context", "value": { "errors": [ { "code": 4001, "message": "Invalid request" } ], "messages": [], "result": [], "success": false } } }, "schema": { "$ref": "#/components/schemas/cps_api_response_common_failure" } } } }, "401": { "description": "The request lacks valid authentication credentials.", "content": { "application/json": { "examples": { "unauthorized": { "summary": "Request unauthorized", "value": { "errors": [ { "code": 4010, "message": "Request unauthorized" } ], "messages": [], "result": [], "success": false } } }, "schema": { "$ref": "#/components/schemas/cps_api_response_common_failure" } } } }, "403": { "description": "The authenticated user does not own the requested resource.", "content": { "application/json": { "examples": { "user_id_mismatch": { "summary": "User ID in URI does not match authenticated user", "value": { "errors": [ { "code": 4030, "message": "Request unauthorized" } ], "messages": [], "result": [], "success": false } } }, "schema": { "$ref": "#/components/schemas/cps_api_response_common_failure" } } } }, "404": { "description": "The requested user identity does not exist.", "content": { "application/json": { "examples": { "not_found": { "summary": "User identity not found", "value": { "errors": [ { "code": 4040, "message": "Id not found" } ], "messages": [], "result": [], "success": false } } }, "schema": { "$ref": "#/components/schemas/cps_api_response_common_failure" } } } }, "500": { "description": "The server encountered an unexpected error.", "content": { "application/json": { "examples": { "failed_to_fetch_preference_types": { "summary": "Failed to fetch preference types", "value": { "errors": [ { "code": 5002, "message": "Something went wrong" } ], "messages": [], "result": [], "success": false } }, "failed_to_fetch_preferences": { "summary": "Failed to fetch recipient preferences", "value": { "errors": [ { "code": 5001, "message": "Something went wrong" } ], "messages": [], "result": [], "success": false } } }, "schema": { "$ref": "#/components/schemas/cps_api_response_common_failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Communication Preferences" ], "x-api-token-group": [ "User Details Read" ] }, "put": { "operationId": "user-communication-preferences-update", "summary": "Update communication preferences", "description": "Set one or more communication preferences for the authenticated user. Supply a map of preference keys to subscription states, and an optional language locale. This endpoint does not modify email verification settings. Callers authenticate with standard Cloudflare API tokens or keys.", "requestBody": { "required": true, "content": { "application/json": { "examples": { "update_all": { "summary": "Update preferences and language", "value": { "language-locale": "es-ES", "preferences": { "marketing": { "subscribed": true }, "product_news": { "subscribed": true } } } }, "update_language": { "summary": "Update language locale", "value": { "language-locale": "fr-FR", "preferences": {} } }, "update_subscriptions": { "summary": "Update marketing subscription preferences", "value": { "preferences": { "marketing": { "subscribed": false }, "product_news": { "subscribed": true } } } } }, "schema": { "$ref": "#/components/schemas/cps_update_communication_preferences_request" } } } }, "responses": { "200": { "description": "Successfully updated communication preferences.", "content": { "application/json": { "examples": { "success": { "summary": "Preferences updated successfully", "value": { "errors": [], "messages": [], "result": { "created_on": "2024-09-01T16:00:00Z", "email": { "hard_bounce": false, "verified": true }, "language-locale": "es-ES", "preferences": { "marketing": { "created_on": "2024-01-15T10:30:00Z", "subscribed": false, "updated_on": "2024-09-01T16:00:00Z" }, "product_news": { "created_on": "2024-01-15T10:30:00Z", "subscribed": true, "updated_on": "2024-09-01T16:00:00Z" } }, "updated_on": "2024-09-01T16:00:00Z" }, "success": true } } }, "schema": { "$ref": "#/components/schemas/cps_communication_preferences_response" } } } }, "400": { "description": "The request contains invalid parameters or body.", "content": { "application/json": { "examples": { "bad_body": { "summary": "Failed to decode request body", "value": { "errors": [ { "code": 4003, "message": "Invalid request" } ], "messages": [], "result": [], "success": false } }, "recipient_invalid": { "summary": "Recipient ID is invalid (zero)", "value": { "errors": [ { "code": 4002, "message": "Invalid request" } ], "messages": [], "result": [], "success": false } }, "recipient_not_present": { "summary": "Recipient ID not present in request context", "value": { "errors": [ { "code": 4001, "message": "Invalid request" } ], "messages": [], "result": [], "success": false } } }, "schema": { "$ref": "#/components/schemas/cps_api_response_common_failure" } } } }, "401": { "description": "The request lacks valid authentication credentials.", "content": { "application/json": { "examples": { "unauthorized": { "summary": "Request unauthorized", "value": { "errors": [ { "code": 4010, "message": "Request unauthorized" } ], "messages": [], "result": [], "success": false } } }, "schema": { "$ref": "#/components/schemas/cps_api_response_common_failure" } } } }, "403": { "description": "The authenticated user does not own the requested resource.", "content": { "application/json": { "examples": { "user_id_mismatch": { "summary": "User ID in URI does not match authenticated user", "value": { "errors": [ { "code": 4030, "message": "Request unauthorized" } ], "messages": [], "result": [], "success": false } } }, "schema": { "$ref": "#/components/schemas/cps_api_response_common_failure" } } } }, "404": { "description": "The requested user identity does not exist.", "content": { "application/json": { "examples": { "not_found": { "summary": "User identity not found", "value": { "errors": [ { "code": 4040, "message": "Id not found" } ], "messages": [], "result": [], "success": false } } }, "schema": { "$ref": "#/components/schemas/cps_api_response_common_failure" } } } }, "500": { "description": "The server encountered an unexpected error.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Failed to update preferences", "value": { "errors": [ { "code": 5003, "message": "Something went wrong" } ], "messages": [], "result": [], "success": false } } }, "schema": { "$ref": "#/components/schemas/cps_api_response_common_failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Communication Preferences" ], "x-api-token-group": [ "User Details Write" ] } }, "/user/firewall/access_rules/rules": { "get": { "operationId": "ip-access-rules-for-a-user-list-ip-access-rules", "summary": "List IP Access rules", "description": "Fetches IP Access rules of the user. You can filter the results using several optional parameters.", "parameters": [ { "name": "mode", "in": "query", "schema": { "$ref": "#/components/schemas/firewall_schemas-mode" } }, { "name": "configuration.target", "in": "query", "schema": { "description": "Defines the target to search in existing rules.", "type": "string", "example": "ip", "enum": [ "ip", "ip_range", "asn", "country" ] } }, { "name": "configuration.value", "in": "query", "schema": { "description": "Defines the target value to search for in existing rules: an IP address, an IP address range, or a country code, depending on the provided `configuration.target`.\nNotes: You can search for a single IPv4 address, an IP address range with a subnet of '/16' or '/24', or a two-letter ISO-3166-1 alpha-2 country code.", "type": "string", "example": "198.51.100.4" } }, { "name": "notes", "in": "query", "schema": { "description": "Defines the string to search for in the notes of existing IP Access rules.\nNotes: For example, the string 'attack' would match IP Access rules with notes 'Attack 26/02' and 'Attack 27/02'. The search is case insensitive.", "type": "string", "example": "my note" } }, { "name": "match", "in": "query", "schema": { "description": "Defines the search requirements. When set to `all`, all the search requirements must match. When set to `any`, only one of the search requirements has to match.", "type": "string", "default": "all", "enum": [ "any", "all" ] } }, { "name": "page", "in": "query", "schema": { "description": "Defines the requested page within paginated list of results.", "type": "number", "example": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Defines the maximum number of results requested.", "type": "number", "example": 20 } }, { "name": "order", "in": "query", "schema": { "description": "Defines the field used to sort returned rules.", "type": "string", "example": "mode", "enum": [ "configuration.target", "configuration.value", "mode" ] } }, { "name": "direction", "in": "query", "schema": { "description": "Defines the direction used to sort returned rules.", "type": "string", "example": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "List IP Access rules response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_rule_collection_response" } } } }, "4XX": { "description": "List IP Access rules response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_rule_collection_response" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "IP Access rules for a user" ], "x-api-token-group": [ "Account Firewall Access Rules Write", "Account Firewall Access Rules Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.firewall.access-rules", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "ip-access-rules-for-a-user-create-an-ip-access-rule", "summary": "Create an IP Access rule", "description": "Creates a new IP Access rule for all zones owned by the current user.\n\nNote: To create an IP Access rule that applies to a specific zone, refer to the [IP Access rules for a zone](#ip-access-rules-for-a-zone) endpoints.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "configuration": { "$ref": "#/components/schemas/firewall_configuration" }, "mode": { "$ref": "#/components/schemas/firewall_schemas-mode" }, "notes": { "default": "", "anyOf": [ { "$ref": "#/components/schemas/firewall_notes" } ] } }, "required": [ "mode", "configuration" ] } } } }, "responses": { "200": { "description": "Create an IP Access rule response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_rule_single_response" } } } }, "4XX": { "description": "Create an IP Access rule response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_rule_single_response" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "IP Access rules for a user" ], "x-api-token-group": [ "Account Firewall Access Rules Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.firewall.access-rules", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/user/firewall/access_rules/rules/{rule_id}": { "delete": { "operationId": "ip-access-rules-for-a-user-delete-an-ip-access-rule", "summary": "Delete an IP Access rule", "description": "Deletes an IP Access rule at the user level.\n\nNote: Deleting a user-level rule will affect all zones owned by the user.", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_rule_identifier" } } ], "responses": { "200": { "description": "Delete an IP Access rule response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_rule_single_id_response" } } } }, "4XX": { "description": "Delete an IP Access rule response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_rule_single_id_response" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "IP Access rules for a user" ], "x-api-token-group": [ "Account Firewall Access Rules Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.firewall.access-rules", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes the user-level IP Access Rule and affects every zone owned by the user." }, "get": { "operationId": "ip-access-rules-for-a-user-get-an-ip-access-rule", "summary": "Get an IP Access rule", "description": "Fetches the details of an IP Access rule defined at the user level.", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_rule_identifier" } } ], "responses": { "200": { "description": "Get an IP Access rule response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_rule_single_response" } } } }, "4XX": { "description": "Get an IP Access rule response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_rule_single_response" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "IP Access rules for a user" ], "x-api-token-group": [ "Account Firewall Access Rules Write", "Account Firewall Access Rules Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.firewall.access-rules", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "ip-access-rules-for-a-user-update-an-ip-access-rule", "summary": "Update an IP Access rule", "description": "Updates an IP Access rule defined at the user level. You can only update the rule action (`mode` parameter) and notes.", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_rule_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/firewall_schemas-mode" }, "notes": { "$ref": "#/components/schemas/firewall_notes" } } } } } }, "responses": { "200": { "description": "Update an IP Access rule response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_rule_single_response" } } } }, "4XX": { "description": "Update an IP Access rule response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_rule_single_response" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "IP Access rules for a user" ], "x-api-token-group": [ "Account Firewall Access Rules Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.firewall.access-rules", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/user/invites": { "get": { "operationId": "user'-s-invites-list-invitations", "summary": "List Invitations", "description": "Lists all invitations associated with my user.", "responses": { "200": { "description": "List Invitations response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_schemas-collection_invite_response" } } } }, "4XX": { "description": "List Invitations response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "User's Invites" ], "x-api-token-group": [ "Memberships Write", "Memberships Read" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.invites", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/user/invites/{invite_id}": { "get": { "operationId": "user'-s-invites-invitation-details", "summary": "Invitation Details", "description": "Gets the details of an invitation.", "parameters": [ { "name": "invite_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_invite_components-schemas-identifier" } } ], "responses": { "200": { "description": "Invitation Details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_single_invite_response" } } } }, "4XX": { "description": "Invitation Details response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "User's Invites" ], "x-api-token-group": [ "Memberships Write", "Memberships Read" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.invites", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "user'-s-invites-respond-to-invitation", "summary": "Respond to Invitation", "description": "Responds to an invitation.", "parameters": [ { "name": "invite_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_invite_components-schemas-identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of your response to the invitation (rejected or accepted).", "example": "accepted", "enum": [ "accepted", "rejected" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Respond to Invitation response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_single_invite_response" } } } }, "4XX": { "description": "Respond to Invitation response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "User's Invites" ], "x-api-token-group": [ "Memberships Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.invites", "x-fern-sdk-method-name": "respond", "x-forge-hidden": true } }, "/user/load_balancers/monitors": { "get": { "operationId": "load-balancer-monitors-list-monitors", "summary": "List Monitors", "description": "List configured monitors for a user.", "responses": { "200": { "description": "Successful list monitors response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_monitor-response-collection" } } } }, "4XX": { "description": "Failed list monitors response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_monitor-response-collection" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Monitors" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write", "Load Balancing: Monitors and Pools Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.monitors", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "load-balancer-monitors-create-monitor", "summary": "Create Monitor", "description": "Create a configured monitor.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_monitor-editable" } ] } } } }, "responses": { "200": { "description": "Create Monitor response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_monitor-response-single" } } } }, "4XX": { "description": "Create Monitor response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_monitor-response-single" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Monitors" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.monitors", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/user/load_balancers/monitors/{monitor_id}": { "delete": { "operationId": "load-balancer-monitors-delete-monitor", "summary": "Delete Monitor", "description": "Delete a configured monitor.", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_identifier" } } ], "responses": { "200": { "description": "Delete Monitor response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_id_response" } } } }, "4XX": { "description": "Delete Monitor response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_id_response" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Monitors" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.monitors", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "load-balancer-monitors-monitor-details", "summary": "Monitor Details", "description": "List a single configured monitor for a user.", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_identifier" } } ], "responses": { "200": { "description": "Monitor Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_monitor-response-single" } } } }, "4XX": { "description": "Monitor Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_monitor-response-single" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Monitors" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write", "Load Balancing: Monitors and Pools Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.monitors", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "load-balancer-monitors-patch-monitor", "summary": "Patch Monitor", "description": "Apply changes to an existing monitor, overwriting the supplied properties.", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_monitor-editable" } ] } } } }, "responses": { "200": { "description": "Patch Monitor response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_monitor-response-single" } } } }, "4XX": { "description": "Patch Monitor response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_monitor-response-single" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Monitors" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.monitors", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "load-balancer-monitors-update-monitor", "summary": "Update Monitor", "description": "Modify a configured monitor.", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_monitor-editable" } ] } } } }, "responses": { "200": { "description": "Update Monitor response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_monitor-response-single" } } } }, "4XX": { "description": "Update Monitor response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_monitor-response-single" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Monitors" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.monitors", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/user/load_balancers/monitors/{monitor_id}/preview": { "post": { "operationId": "load-balancer-monitors-preview-monitor", "summary": "Preview Monitor", "description": "Preview pools using the specified monitor with provided monitor details. The returned preview_id can be used in the preview endpoint to retrieve the results.", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_monitor-editable" } ] } } } }, "responses": { "200": { "description": "Preview Monitor response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_preview_response" } } } }, "4XX": { "description": "Preview Monitor response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_preview_response" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Monitors" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.monitors.preview", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/user/load_balancers/monitors/{monitor_id}/references": { "get": { "operationId": "load-balancer-monitors-list-monitor-references", "summary": "List Monitor References", "description": "Get the list of resources that reference the provided monitor.", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_identifier" } } ], "responses": { "200": { "description": "List Monitor References response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_monitor-references-response" } } } }, "4XX": { "description": "List Monitor References response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_monitor-references-response" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Monitors" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write", "Load Balancing: Monitors and Pools Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.monitors.references", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/user/load_balancers/pools": { "get": { "operationId": "load-balancer-pools-list-pools", "summary": "List Pools", "description": "List configured pools.", "parameters": [ { "name": "monitor", "in": "query", "schema": { "description": "The ID of the Monitor to use for checking the health of origins within this pool.", "type": "string" } } ], "responses": { "200": { "description": "List Pools response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_schemas-response_collection" } } } }, "4XX": { "description": "List Pools response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_schemas-response_collection" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Pools" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write", "Load Balancing: Monitors and Pools Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.pools", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "patch": { "operationId": "load-balancer-pools-patch-pools", "summary": "Patch Pools", "description": "Apply changes to a number of existing pools, overwriting the supplied properties. Pools are ordered by ascending `name`. Returns the list of affected pools. Supports the standard pagination query parameters, either `limit`/`offset` or `per_page`/`page`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "string", "properties": { "notification_email": { "$ref": "#/components/schemas/load-balancing_patch_pools_notification_email" } } } } } }, "responses": { "200": { "description": "Patch Pools response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_schemas-response_collection" } } } }, "4XX": { "description": "Patch Pools response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_schemas-response_collection" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Pools" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.pools.edit.pools", "x-fern-sdk-method-name": "pools", "x-forge-hidden": true }, "post": { "operationId": "load-balancer-pools-create-pool", "summary": "Create Pool", "description": "Create a new pool.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "check_regions": { "$ref": "#/components/schemas/load-balancing_check_regions" }, "description": { "$ref": "#/components/schemas/load-balancing_schemas-description" }, "enabled": { "$ref": "#/components/schemas/load-balancing_enabled" }, "health_sources": { "$ref": "#/components/schemas/load-balancing_health_sources" }, "latitude": { "$ref": "#/components/schemas/load-balancing_latitude" }, "load_shedding": { "$ref": "#/components/schemas/load-balancing_load_shedding" }, "longitude": { "$ref": "#/components/schemas/load-balancing_longitude" }, "minimum_origins": { "$ref": "#/components/schemas/load-balancing_minimum_origins" }, "monitor": { "$ref": "#/components/schemas/load-balancing_monitor_id" }, "monitor_group": { "$ref": "#/components/schemas/load-balancing_monitor_group_id" }, "name": { "$ref": "#/components/schemas/load-balancing_name" }, "networks": { "$ref": "#/components/schemas/load-balancing_networks" }, "notification_email": { "$ref": "#/components/schemas/load-balancing_notification_email" }, "notification_filter": { "$ref": "#/components/schemas/load-balancing_notification_filter" }, "origin_steering": { "$ref": "#/components/schemas/load-balancing_origin_steering" }, "origins": { "$ref": "#/components/schemas/load-balancing_origins" } }, "required": [ "origins", "name" ] } } } }, "responses": { "200": { "description": "Create Pool response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_schemas-single_response" } } } }, "4XX": { "description": "Create Pool response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_schemas-single_response" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Pools" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.pools", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/user/load_balancers/pools/{pool_id}": { "delete": { "operationId": "load-balancer-pools-delete-pool", "summary": "Delete Pool", "description": "Delete a configured pool.", "parameters": [ { "name": "pool_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_schemas-identifier" } } ], "responses": { "200": { "description": "Delete Pool response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_schemas-id_response" } } } }, "4XX": { "description": "Delete Pool response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_schemas-id_response" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Pools" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.pools", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "load-balancer-pools-pool-details", "summary": "Pool Details", "description": "Fetch a single configured pool.", "parameters": [ { "name": "pool_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_schemas-identifier" } } ], "responses": { "200": { "description": "Pool Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_schemas-single_response" } } } }, "4XX": { "description": "Pool Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_schemas-single_response" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Pools" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write", "Load Balancing: Monitors and Pools Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.pools", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "load-balancer-pools-patch-pool", "summary": "Patch Pool", "description": "Apply changes to an existing pool, overwriting the supplied properties.", "parameters": [ { "name": "pool_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_schemas-identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "check_regions": { "$ref": "#/components/schemas/load-balancing_check_regions" }, "description": { "$ref": "#/components/schemas/load-balancing_schemas-description" }, "disabled_at": { "$ref": "#/components/schemas/load-balancing_schemas-disabled_at" }, "enabled": { "$ref": "#/components/schemas/load-balancing_enabled" }, "health_sources": { "$ref": "#/components/schemas/load-balancing_health_sources" }, "latitude": { "$ref": "#/components/schemas/load-balancing_latitude" }, "load_shedding": { "$ref": "#/components/schemas/load-balancing_load_shedding" }, "longitude": { "$ref": "#/components/schemas/load-balancing_longitude" }, "minimum_origins": { "$ref": "#/components/schemas/load-balancing_minimum_origins" }, "monitor": { "$ref": "#/components/schemas/load-balancing_monitor_id" }, "monitor_group": { "$ref": "#/components/schemas/load-balancing_monitor_group_id" }, "name": { "$ref": "#/components/schemas/load-balancing_name" }, "notification_email": { "$ref": "#/components/schemas/load-balancing_notification_email" }, "notification_filter": { "$ref": "#/components/schemas/load-balancing_notification_filter" }, "origin_steering": { "$ref": "#/components/schemas/load-balancing_origin_steering" }, "origins": { "$ref": "#/components/schemas/load-balancing_origins" } } } } } }, "responses": { "200": { "description": "Patch Pool response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_schemas-single_response" } } } }, "4XX": { "description": "Patch Pool response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_schemas-single_response" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Pools" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.pools.edit.pools", "x-fern-sdk-method-name": "pool", "x-forge-hidden": true }, "put": { "operationId": "load-balancer-pools-update-pool", "summary": "Update Pool", "description": "Modify a configured pool.", "parameters": [ { "name": "pool_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_schemas-identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "check_regions": { "$ref": "#/components/schemas/load-balancing_check_regions" }, "description": { "$ref": "#/components/schemas/load-balancing_schemas-description" }, "disabled_at": { "$ref": "#/components/schemas/load-balancing_schemas-disabled_at" }, "enabled": { "$ref": "#/components/schemas/load-balancing_enabled" }, "health_sources": { "$ref": "#/components/schemas/load-balancing_health_sources" }, "latitude": { "$ref": "#/components/schemas/load-balancing_latitude" }, "load_shedding": { "$ref": "#/components/schemas/load-balancing_load_shedding" }, "longitude": { "$ref": "#/components/schemas/load-balancing_longitude" }, "minimum_origins": { "$ref": "#/components/schemas/load-balancing_minimum_origins" }, "monitor": { "$ref": "#/components/schemas/load-balancing_monitor_id" }, "monitor_group": { "$ref": "#/components/schemas/load-balancing_monitor_group_id" }, "name": { "$ref": "#/components/schemas/load-balancing_name" }, "networks": { "$ref": "#/components/schemas/load-balancing_networks" }, "notification_email": { "$ref": "#/components/schemas/load-balancing_notification_email" }, "notification_filter": { "$ref": "#/components/schemas/load-balancing_notification_filter" }, "origin_steering": { "$ref": "#/components/schemas/load-balancing_origin_steering" }, "origins": { "$ref": "#/components/schemas/load-balancing_origins" } }, "required": [ "origins", "name" ] } } } }, "responses": { "200": { "description": "Update Pool response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_schemas-single_response" } } } }, "4XX": { "description": "Update Pool response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_schemas-single_response" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Pools" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.pools", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/user/load_balancers/pools/{pool_id}/health": { "get": { "operationId": "load-balancer-pools-pool-health-details", "summary": "Pool Health Details", "description": "Fetch the latest pool health status for a single pool.", "parameters": [ { "name": "pool_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_schemas-identifier" } } ], "responses": { "200": { "description": "Pool Health Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_health_details" } } } }, "4XX": { "description": "Pool Health Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_health_details" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Pools" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write", "Load Balancing: Monitors and Pools Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.pools.health", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/user/load_balancers/pools/{pool_id}/preview": { "post": { "operationId": "load-balancer-pools-preview-pool", "summary": "Preview Pool", "description": "Preview pool health using provided monitor details. The returned preview_id can be used in the preview endpoint to retrieve the results.", "parameters": [ { "name": "pool_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_schemas-identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_monitor-editable" } ] } } } }, "responses": { "200": { "description": "Preview Pool response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_preview_response" } } } }, "4XX": { "description": "Preview Pool response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_preview_response" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Pools" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.pools.preview", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/user/load_balancers/pools/{pool_id}/references": { "get": { "operationId": "load-balancer-pools-list-pool-references", "summary": "List Pool References", "description": "Get the list of resources that reference the provided pool.", "parameters": [ { "name": "pool_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_schemas-identifier" } } ], "responses": { "200": { "description": "List Pool References response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_pools-references-response" } } } }, "4XX": { "description": "List Pool References response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_pools-references-response" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Pools" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write", "Load Balancing: Monitors and Pools Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.pools.references", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/user/load_balancers/preview/{preview_id}": { "get": { "operationId": "load-balancer-monitors-preview-result", "summary": "Preview Result", "description": "Get the result of a previous preview operation using the provided preview_id.", "parameters": [ { "name": "preview_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_preview_id" } } ], "responses": { "200": { "description": "Preview Result response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_preview_result_response" } } } }, "4XX": { "description": "Preview Result response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_preview_result_response" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Monitors" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write", "Load Balancing: Monitors and Pools Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.preview", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/user/load_balancers/regions": { "get": { "operationId": "user-load-balancer-regions-list-regions", "summary": "List Regions", "description": "List all region mappings in the user context.", "parameters": [ { "name": "subdivision_code", "in": "query", "schema": { "$ref": "#/components/schemas/load-balancing_subdivision_code_a2" } }, { "name": "country_code", "in": "query", "schema": { "description": "Two-letter alpha-2 country code as defined in ISO 3166-1.", "type": "string", "example": "US" } } ], "responses": { "200": { "description": "List Regions response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_region_components-schemas-response_collection" } } } }, "4XX": { "description": "List Regions response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_region_components-schemas-response_collection" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Regions" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write", "Load Balancing: Monitors and Pools Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancers.regions", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/user/load_balancing_analytics/events": { "get": { "operationId": "load-balancer-healthcheck-events-list-healthcheck-events", "summary": "List Healthcheck Events", "description": "List origin health changes.", "parameters": [ { "name": "until", "in": "query", "schema": { "$ref": "#/components/schemas/load-balancing_until" } }, { "name": "pool_name", "in": "query", "schema": { "$ref": "#/components/schemas/load-balancing_pool_name" } }, { "name": "origin_healthy", "in": "query", "schema": { "$ref": "#/components/schemas/load-balancing_origin_healthy" } }, { "name": "pool_id", "in": "query", "schema": { "$ref": "#/components/schemas/load-balancing_schemas-identifier" } }, { "name": "since", "in": "query", "schema": { "description": "Start date and time of requesting data period in the ISO8601 format.", "type": "string", "format": "date-time", "example": "2016-11-11T12:00:00Z" } }, { "name": "origin_name", "in": "query", "schema": { "description": "The name for the origin to filter.", "type": "string", "example": "primary-dc-1" } }, { "name": "pool_healthy", "in": "query", "schema": { "description": "If true, filter events where the pool status is healthy. If false, filter events where the pool status is unhealthy.", "type": "boolean", "example": true, "default": true } } ], "responses": { "200": { "description": "List Healthcheck Events response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_components-schemas-response_collection" } } } }, "4XX": { "description": "List Healthcheck Events response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_components-schemas-response_collection" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancer Healthcheck Events" ], "x-api-token-group": [ "Load Balancing: Monitors and Pools Write", "Load Balancing: Monitors and Pools Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.load-balancing-analytics.events", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/user/memberships/{membership_id}": { "get": { "operationId": "user-memberships-get", "summary": "Get User Membership", "description": "Get a specific membership for the currently authenticated user.", "parameters": [ { "name": "membership_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_membership_components-schemas-identifier" } } ], "responses": { "200": { "description": "Get User Membership response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_single_membership_response_with_policies" } } } }, "4XX": { "description": "Get User Membership response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "User's Account Memberships" ], "x-api-token-group": [ "Memberships Write", "Memberships Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.user.membership.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.memberships", "x-fern-sdk-method-name": "get" } }, "/user/organizations": { "get": { "operationId": "user'-s-organizations-list-organizations", "summary": "List Organizations", "description": "Lists organizations the user is associated with.", "parameters": [ { "name": "name", "in": "query", "schema": { "$ref": "#/components/schemas/iam_schemas-name" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of organizations per page.", "type": "number", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "order", "in": "query", "schema": { "description": "Field to order organizations by.", "type": "string", "example": "status", "enum": [ "id", "name", "status" ] } }, { "name": "direction", "in": "query", "schema": { "description": "Direction to order organizations.", "type": "string", "example": "desc", "enum": [ "asc", "desc" ] } }, { "name": "match", "in": "query", "schema": { "description": "Whether to match all search requirements or at least one (any).", "type": "string", "default": "all", "enum": [ "any", "all" ] } }, { "name": "status", "in": "query", "schema": { "description": "Whether the user is a member of the organization or has an inivitation pending.", "type": "string", "example": "member", "enum": [ "member", "invited" ] } } ], "responses": { "200": { "description": "List Organizations response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_collection_organization_response" } } } }, "4XX": { "description": "List Organizations response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "User's Organizations" ], "x-api-token-group": [ "Memberships Write", "Memberships Read" ], "x-cfDeprecation": { "description": "This endpoint and its related APIs are deprecated in favor of the `/accounts` equivalent APIs, which have a broader range of features and are backwards compatible with these API.", "display": true, "eol": "2020-02-04T00:00:00Z", "id": "org_deprecation" }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "user.organizations", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/user/organizations/{organization_id}": { "delete": { "operationId": "user'-s-organizations-leave-organization", "summary": "Leave Organization", "description": "Removes association to an organization.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_common_components-schemas-identifier" } } ], "responses": { "200": { "description": "Leave Organization response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/iam_common_components-schemas-identifier" } } } } } }, "4XX": { "description": "Leave Organization response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "User's Organizations" ], "x-cfDeprecation": { "description": "This endpoint and its related APIs are deprecated in favor of the `/accounts` equivalent APIs, which have a broader range of features and are backwards compatible with these API.", "display": true, "eol": "2020-02-04T00:00:00Z", "id": "org_deprecation" }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "user.organizations", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "Are you sure? This action cannot be undone." }, "get": { "operationId": "user'-s-organizations-organization-details", "summary": "Organization Details", "description": "Gets a specific organization the user is associated with.", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_common_components-schemas-identifier" } } ], "responses": { "200": { "description": "Organization Details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_single_organization_response" } } } }, "4XX": { "description": "Organization Details response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "User's Organizations" ], "x-cfDeprecation": { "description": "This endpoint and its related APIs are deprecated in favor of the `/accounts` equivalent APIs, which have a broader range of features and are backwards compatible with these API.", "display": true, "eol": "2020-02-04T00:00:00Z", "id": "org_deprecation" }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "user.organizations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/user/spectrum_analytics/zones/report": { "get": { "operationId": "spectrum-analytics-get-zones-report", "summary": "Get zones bandwidth report", "description": "Retrieves a list of total bandwidth by zone over a given time period.", "parameters": [ { "name": "since", "in": "query", "schema": { "$ref": "#/components/schemas/spectrum-analytics_since" } }, { "name": "until", "in": "query", "schema": { "$ref": "#/components/schemas/spectrum-analytics_until" } }, { "name": "cdn_traffic", "in": "query", "schema": { "description": "Include CDN traffic in the bandwidth aggregation.", "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Get zones bandwidth report response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-analytics_zones_report_response" } } } }, "4XX": { "description": "Get zones bandwidth report response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-analytics_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Spectrum Analytics" ], "x-api-token-group": [ "User Details Write", "User Details Read" ] } }, "/user/subscriptions": { "get": { "operationId": "user-subscription-get-user-subscriptions", "summary": "Get User Subscriptions", "description": "Lists all of a user's subscriptions.", "responses": { "200": { "description": "Get User Subscriptions response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_user_subscription_response_collection" } } } }, "4XX": { "description": "Get User Subscriptions response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "User Subscription" ], "x-api-token-group": [ "Billing Write", "Billing Read" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read" ] }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.subscriptions", "x-fern-sdk-method-name": "get" }, "post": { "operationId": "user-subscription-create-user-subscription", "summary": "Create User Subscription", "description": "Creates a user subscription.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_subscription-v2" } } } }, "responses": { "200": { "description": "Create User Subscription response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_user_subscription_response_single" } } } }, "4XX": { "description": "Create User Subscription response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_user_subscription_response_single" }, { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "User Subscription" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read", "#billing:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "user.subscriptions", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/user/subscriptions/{identifier}": { "delete": { "operationId": "user-subscription-delete-user-subscription", "summary": "Delete User Subscription", "description": "Deletes a user's subscription.", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_schemas-identifier" } } ], "responses": { "200": { "description": "Delete User Subscription response", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_id": { "$ref": "#/components/schemas/bill-subs-api_schemas-identifier" } } } } } }, "4XX": { "description": "Delete User Subscription response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "User Subscription" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:edit" ] }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.subscriptions", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "put": { "operationId": "user-subscription-update-user-subscription", "summary": "Update User Subscription", "description": "Updates a user's subscriptions.", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_schemas-identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_subscription-v2" } } } }, "responses": { "200": { "description": "Update User Subscription response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_user_subscription_response_single" } } } }, "4XX": { "description": "Update User Subscription response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "User Subscription" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read", "#billing:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.subscriptions", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/user/tenants": { "get": { "operationId": "User_listUserTenants", "summary": "List user tenants", "description": "Retrieves list of tenants the authenticated user / method has access to.", "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_Organization" } }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] } } } }, "4XX": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizations-api_V4ErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "User" ], "x-api-token-group": [ "User Details Write", "User Details Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.tenant", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/user/tokens": { "get": { "operationId": "user-api-tokens-list-tokens", "summary": "List Tokens", "description": "List all access tokens you created. Results include active, disabled, and recently-expired tokens when include_expired is set to true.", "parameters": [ { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Maximum number of results per page.", "type": "number", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "direction", "in": "query", "schema": { "description": "Direction to order results.", "type": "string", "example": "desc", "enum": [ "asc", "desc" ] } }, { "$ref": "#/components/parameters/iam_include_expired" } ], "responses": { "200": { "description": "List Tokens response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_collection_tokens_response" } } } }, "4XX": { "description": "List Tokens response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "User API Tokens" ], "x-api-token-group": [ "API Tokens Write", "API Tokens Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.token.list" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.tokens", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "user-api-tokens-create-token", "summary": "Create Token", "description": "Create a new access token.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_create_payload" } } } }, "responses": { "200": { "description": "Create Token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_single_token_create_response" } } } }, "4XX": { "description": "Create Token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "User API Tokens" ], "x-api-token-group": [ "API Tokens Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.token.create" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.tokens", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/user/tokens/permission_groups": { "get": { "operationId": "permission-groups-list-permission-groups", "summary": "List Token Permission Groups", "description": "Find all available permission groups for API Tokens.", "parameters": [ { "name": "name", "in": "query", "description": "Filter by the name of the permission group.\nThe value must be URL-encoded.", "schema": { "type": "string", "example": "Account%20Settings%20Write" } }, { "name": "scope", "in": "query", "description": "Filter by the scope of the permission group.\nThe value must be URL-encoded.", "schema": { "type": "string", "example": "com.cloudflare.api.account.zone" } } ], "responses": { "200": { "description": "List Token Permission Groups response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_permissions_group_response_collection" } } } }, "4XX": { "description": "List Token Permission Groups response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "User API Tokens" ], "x-api-token-group": [ "API Tokens Write", "API Tokens Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.token.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.tokens.permission-groups", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/user/tokens/verify": { "get": { "operationId": "user-api-tokens-verify-token", "summary": "Verify Token", "description": "Test whether a token works.", "responses": { "200": { "description": "Verify Token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_token_verify_response_single_segment" } } } }, "4XX": { "description": "Verify Token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "User API Tokens" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.tokens", "x-fern-sdk-method-name": "verify", "x-forge-hidden": true } }, "/user/tokens/{token_id}": { "delete": { "operationId": "user-api-tokens-delete-token", "summary": "Delete Token", "description": "Destroy a token.", "parameters": [ { "name": "token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_token_identifier" } } ], "responses": { "200": { "description": "Delete Token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-single-id" } } } }, "4XX": { "description": "Delete Token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "User API Tokens" ], "x-api-token-group": [ "API Tokens Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.token.delete" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.tokens", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "Are you sure? This action cannot be undone." }, "get": { "operationId": "user-api-tokens-token-details", "summary": "Token Details", "description": "Get information about a specific token.", "parameters": [ { "name": "token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_token_identifier" } } ], "responses": { "200": { "description": "Token Details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_single_token_response" } } } }, "4XX": { "description": "Token Details response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "User API Tokens" ], "x-api-token-group": [ "API Tokens Write", "API Tokens Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.token.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.tokens", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "user-api-tokens-update-token", "summary": "Update Token", "description": "Update an existing token.", "parameters": [ { "name": "token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_token_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_token_body" } } } }, "responses": { "200": { "description": "Update Token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_single_token_response" } } } }, "4XX": { "description": "Update Token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "User API Tokens" ], "x-api-token-group": [ "API Tokens Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.token.update" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.tokens", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/user/tokens/{token_id}/value": { "put": { "operationId": "user-api-tokens-roll-token", "summary": "Roll Token", "description": "Roll the token secret.", "parameters": [ { "name": "token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/iam_token_identifier" } } ], "responses": { "200": { "description": "Roll Token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_response_single_value" } } } }, "4XX": { "description": "Roll Token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/iam_api-response-common-failure" } } } } }, "security": [ { "api_token": [] } ], "tags": [ "User API Tokens" ], "x-api-token-group": [ "API Tokens Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.token.update" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "user.tokens", "x-fern-sdk-method-name": "roll", "x-forge-hidden": true, "x-forge-require-confirmation": "Rolling this token will invalidate the current secret and generate a new one. Any integrations using the current secret will stop working." } }, "/workers/builds/deploy_hooks/{deploy_hook_uuid}": { "post": { "operationId": "triggerDeployHook", "summary": "Trigger deploy hook", "description": "Trigger a build using a deploy hook. This endpoint does not require authentication - the deploy_hook_uuid acts as a secret token.", "parameters": [ { "$ref": "#/components/parameters/builds_DeployHookUuid" } ], "responses": { "200": { "description": "Build triggered successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/builds_APIResponse" }, { "properties": { "result": { "$ref": "#/components/schemas/builds_TriggerDeployHookResponse" } }, "type": "object" } ] } } } }, "404": { "$ref": "#/components/responses/builds_NotFound" }, "429": { "$ref": "#/components/responses/builds_TooManyRequests" } }, "security": [ { "api_token": [] }, {} ], "tags": [ "Deploy Hooks" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "builds.deploy-hooks", "x-fern-sdk-method-name": "trigger", "x-forge-hidden": true } }, "/zones": { "get": { "operationId": "zones-get", "summary": "List Zones", "description": "Lists, searches, sorts, and filters your zones. Listing zones across more than 500 accounts\nis currently not allowed.\n", "parameters": [ { "name": "name", "in": "query", "schema": { "description": "A domain name. Optional filter operators can be provided to extend refine the search:\n * `equal` (default)\n * `not_equal`\n * `starts_with`\n * `ends_with`\n * `contains`\n * `starts_with_case_sensitive`\n * `ends_with_case_sensitive`\n * `contains_case_sensitive`\n", "type": "string", "maxLength": 253 }, "examples": { "Basic Query": { "summary": "Simple Query", "value": "example.com" }, "Contains Query": { "summary": "Contains Query", "value": "contains:.org" }, "Ends With Query": { "summary": "Ends With Query", "value": "ends_with:arpa" }, "Starts With Query": { "summary": "Starts With Query", "value": "starts_with:dev" } } }, { "name": "status", "in": "query", "schema": { "description": "Specify a zone status to filter by.", "type": "string", "enum": [ "initializing", "pending", "active", "moved" ] } }, { "name": "type", "in": "query", "schema": { "description": "Zone types to filter by. Multiple types can be specified as a comma-separated list (e.g., ?type=full,partial,secondary). When this parameter is not provided, zones with type \"internal\" are excluded from the results.", "type": "array", "items": { "enum": [ "full", "partial", "secondary", "internal" ], "type": "string" } }, "explode": false, "style": "form" }, { "name": "account.id", "in": "query", "schema": { "description": "Filter by an account ID.", "type": "string" } }, { "name": "account.name", "in": "query", "schema": { "description": "An account Name. Optional filter operators can be provided to extend refine the search:\n * `equal` (default)\n * `not_equal`\n * `starts_with`\n * `ends_with`\n * `contains`\n * `starts_with_case_sensitive`\n * `ends_with_case_sensitive`\n * `contains_case_sensitive`\n", "type": "string", "maxLength": 253 }, "examples": { "Basic Query": { "summary": "Simple Query", "value": "Dev Account" }, "Contains Query": { "summary": "Contains Query", "value": "contains:Test" } } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of zones per page.", "type": "number", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "order", "in": "query", "schema": { "description": "Field to order zones by.", "type": "string", "example": "status", "enum": [ "name", "status", "account.id", "account.name", "plan.id" ] } }, { "name": "direction", "in": "query", "schema": { "description": "Direction to order zones.", "type": "string", "example": "desc", "enum": [ "asc", "desc" ] } }, { "name": "match", "in": "query", "schema": { "description": "Whether to match all search requirements or at least one (any).", "type": "string", "default": "all", "enum": [ "any", "all" ] } } ], "responses": { "200": { "description": "List Zones response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common" }, { "properties": { "result_info": { "$ref": "#/components/schemas/zones_result_info" } } }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/zones_zone" } } } } ] } } } }, "4XX": { "description": "List Zones response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone" ], "x-api-token-group": [ "Zone Zone Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones", "x-fern-sdk-method-name": "list" }, "post": { "operationId": "zones-post", "summary": "Create Zone", "description": "Creates a new zone (domain) in your Cloudflare account.\n\nThe zone is created in a pending state and must be activated by updating your domain's\nnameservers to point to Cloudflare, or by completing the verification process for partial\n(CNAME) setups.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/zones_identifier" } } }, "name": { "$ref": "#/components/schemas/zones_name" }, "type": { "$ref": "#/components/schemas/zones_type" } }, "required": [ "name", "account" ] } } } }, "responses": { "200": { "description": "Create Zone response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/zones_zone" } }, "type": "object" } ] } } } }, "4XX": { "description": "Create Zone response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone" ], "x-api-token-group": [ "Zone Zone Edit", "Zone DNS Edit" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones", "x-fern-sdk-method-name": "create" } }, "/zones/{zone_identifier}/analytics/colos": { "get": { "operationId": "zone-analytics-(-deprecated)-get-analytics-by-co-locations", "summary": "Get analytics by Co-locations", "description": "This view provides a breakdown of analytics data by datacenter. Note: This is available to Enterprise customers only.", "parameters": [ { "name": "zone_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zone-analytics-api_identifier" } }, { "name": "until", "in": "query", "schema": { "$ref": "#/components/schemas/zone-analytics-api_until" } }, { "name": "since", "in": "query", "schema": { "description": "The (inclusive) beginning of the requested time frame. This value can be a negative integer representing the number of minutes in the past relative to time the request is made, or can be an absolute timestamp that conforms to RFC 3339. At this point in time, it cannot exceed a time in the past greater than one year.\n\nRanges that the Cloudflare web application provides will provide the following period length for each point:\n- Last 60 minutes (from -59 to -1): 1 minute resolution\n- Last 7 hours (from -419 to -60): 15 minutes resolution\n- Last 15 hours (from -899 to -420): 30 minutes resolution\n- Last 72 hours (from -4320 to -900): 1 hour resolution\n- Older than 3 days (-525600 to -4320): 1 day resolution.", "example": "2015-01-01T12:23:00Z", "default": -10080, "anyOf": [ { "type": "string" }, { "type": "integer" } ] } }, { "name": "continuous", "in": "query", "schema": { "description": "When set to true, the API will move the requested time window backward, until it finds a region with completely aggregated data.\n\nThe API response _may not represent the requested time window_.", "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Get analytics by Co-locations response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zone-analytics-api_colo_response" } } } }, "4XX": { "description": "Get analytics by Co-locations response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zone-analytics-api_colo_response" }, { "$ref": "#/components/schemas/zone-analytics-api_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Analytics (Deprecated)" ], "x-api-token-group": [ "Analytics Read" ], "x-cfDeprecation": { "description": "Please use the new GraphQL Analytics API instead: https://developers.cloudflare.com/analytics/graphql-api/. It provides equivalent data and more features, including the ability to select only the metrics you need. Migration guide: https://developers.cloudflare.com/analytics/migration-guides/zone-analytics/.", "display": true, "eol": "2021-03-01T00:00:00Z", "id": "zone_analytics_deprecation" }, "x-cfPermissionsRequired": { "enum": [ "#analytics:read" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "analytics.colo", "x-fern-sdk-method-name": "get" } }, "/zones/{zone_identifier}/analytics/dashboard": { "get": { "operationId": "zone-analytics-(-deprecated)-get-dashboard", "summary": "Get dashboard", "description": "The dashboard view provides both totals and timeseries data for the given zone and time period across the entire Cloudflare network.", "parameters": [ { "name": "zone_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zone-analytics-api_identifier" } }, { "name": "until", "in": "query", "schema": { "$ref": "#/components/schemas/zone-analytics-api_until" } }, { "name": "since", "in": "query", "schema": { "description": "The (inclusive) beginning of the requested time frame. This value can be a negative integer representing the number of minutes in the past relative to time the request is made, or can be an absolute timestamp that conforms to RFC 3339. At this point in time, it cannot exceed a time in the past greater than one year.\n\nRanges that the Cloudflare web application provides will provide the following period length for each point:\n- Last 60 minutes (from -59 to -1): 1 minute resolution\n- Last 7 hours (from -419 to -60): 15 minutes resolution\n- Last 15 hours (from -899 to -420): 30 minutes resolution\n- Last 72 hours (from -4320 to -900): 1 hour resolution\n- Older than 3 days (-525600 to -4320): 1 day resolution.", "example": "2015-01-01T12:23:00Z", "default": -10080, "anyOf": [ { "type": "string" }, { "type": "integer" } ] } }, { "name": "continuous", "in": "query", "schema": { "description": "When set to true, the API will move the requested time window backward, until it finds a region with completely aggregated data.\n\nThe API response _may not represent the requested time window_.", "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Get dashboard response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zone-analytics-api_dashboard_response" } } } }, "4XX": { "description": "Get dashboard response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zone-analytics-api_dashboard_response" }, { "$ref": "#/components/schemas/zone-analytics-api_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Analytics (Deprecated)" ], "x-api-token-group": [ "Analytics Read" ], "x-cfDeprecation": { "description": "Please use the new GraphQL Analytics API instead: https://developers.cloudflare.com/analytics/graphql-api/. It provides equivalent data and more features, including the ability to select only the metrics you need. Migration guide: https://developers.cloudflare.com/analytics/migration-guides/zone-analytics/.", "display": true, "eol": "2021-03-01T00:00:00Z", "id": "zone_analytics_deprecation" }, "x-cfPermissionsRequired": { "enum": [ "#analytics:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "analytics.dashboard", "x-fern-sdk-method-name": "get" } }, "/zones/{zone_identifier}/custom_pages": { "get": { "operationId": "custom-pages-for-a-zone-list-custom-pages", "summary": "List custom pages", "description": "Fetches all the custom pages at the zone level.", "parameters": [ { "name": "zone_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } } ], "responses": { "200": { "description": "List custom pages response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_custom_page_result_list" } } } }, "4XX": { "description": "List custom pages response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_custom_page_result_list" }, { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom pages for a zone" ], "x-api-token-group": [ "Custom Pages Write", "Custom Pages Read", "Zone Settings Write", "Zone Settings Read" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages.zone-custom-pages", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/zones/{zone_identifier}/custom_pages/assets": { "get": { "operationId": "custom-assets-for-a-zone-list-custom-assets", "summary": "List custom assets", "description": "Fetches all the custom assets at the zone level.", "parameters": [ { "name": "zone_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 200, "minimum": 1 } } ], "responses": { "200": { "description": "List custom assets response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_custom_asset_result_list" } } } }, "4XX": { "description": "List custom assets response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_custom_asset_result_list" }, { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom assets for a zone" ], "x-api-token-group": [ "Custom Errors Write", "Custom Errors Read" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages.assets.list", "x-fern-sdk-method-name": "v2", "x-forge-hidden": true }, "post": { "operationId": "custom-assets-for-a-zone-create-a-custom-asset", "summary": "Create a custom asset", "description": "Creates a new custom asset at the zone level.", "parameters": [ { "name": "zone_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "description": { "$ref": "#/components/schemas/custom-pages_asset_description" }, "name": { "$ref": "#/components/schemas/custom-pages_asset_name" }, "url": { "$ref": "#/components/schemas/custom-pages_asset_url" } }, "required": [ "name", "description", "url" ] } } } }, "responses": { "200": { "description": "Create custom asset response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_custom_asset_result" } } } }, "4XX": { "description": "Create custom asset response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_custom_asset_result" }, { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom assets for a zone" ], "x-api-token-group": [ "Custom Errors Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages.assets.create", "x-fern-sdk-method-name": "v2", "x-forge-hidden": true } }, "/zones/{zone_identifier}/custom_pages/assets/{asset_name}": { "delete": { "operationId": "custom-assets-for-a-zone-delete-a-custom-asset", "summary": "Delete a custom asset", "description": "Deletes an existing custom asset.", "parameters": [ { "name": "asset_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_asset_name" } }, { "name": "zone_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } } ], "responses": { "204": { "description": "Delete a custom asset response" }, "4XX": { "description": "Delete a custom asset response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom assets for a zone" ], "x-api-token-group": [ "Custom Errors Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages.assets.delete", "x-fern-sdk-method-name": "v2", "x-forge-hidden": true }, "get": { "operationId": "custom-assets-for-a-zone-get-a-custom-asset", "summary": "Get a custom asset", "description": "Fetches the details of a custom asset.", "parameters": [ { "name": "asset_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_asset_name" } }, { "name": "zone_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } } ], "responses": { "200": { "description": "Get a custom asset response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_custom_asset_result" } } } }, "4XX": { "description": "Get a custom asset response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_custom_asset_result" }, { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom assets for a zone" ], "x-api-token-group": [ "Custom Errors Write", "Custom Errors Read" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages.assets.get", "x-fern-sdk-method-name": "v2", "x-forge-hidden": true }, "put": { "operationId": "custom-assets-for-a-zone-update-a-custom-asset", "summary": "Update a custom asset", "description": "Updates the configuration of an existing custom asset.", "parameters": [ { "name": "asset_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_asset_name" } }, { "name": "zone_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "description": { "$ref": "#/components/schemas/custom-pages_asset_description" }, "url": { "$ref": "#/components/schemas/custom-pages_asset_url" } }, "required": [ "description", "url" ] } } } }, "responses": { "200": { "description": "Update a custom asset response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_custom_asset_result" } } } }, "4XX": { "description": "Update a custom asset response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_custom_asset_result" }, { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom assets for a zone" ], "x-api-token-group": [ "Custom Errors Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages.assets.update", "x-fern-sdk-method-name": "v2", "x-forge-hidden": true } }, "/zones/{zone_identifier}/custom_pages/preview_tokens": { "post": { "operationId": "custom-pages-for-a-zone-create-preview-token", "summary": "Create a preview token", "description": "Creates a signed JWT token used to preview custom pages before they are published. The API gateway rewrites zone-scoped requests to the account-level service endpoint.", "parameters": [ { "name": "zone_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_preview_request" } } } }, "responses": { "200": { "description": "Create preview token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_preview_token_result" } } } }, "4XX": { "description": "Create preview token response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_preview_token_result" }, { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom pages for a zone" ], "x-api-token-group": [ "Custom Pages Write", "Custom Pages Read", "Zone Settings Write", "Zone Settings Read" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages.zone-custom-pages.preview-tokens", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_identifier}/custom_pages/{identifier}": { "get": { "operationId": "custom-pages-for-a-zone-get-a-custom-page", "summary": "Get a custom page", "description": "Fetches the details of a custom page.", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_error_page_type" } }, { "name": "zone_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } } ], "responses": { "200": { "description": "Get a custom page response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_custom_page" } } } }, "4XX": { "description": "Get a custom page response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_custom_page_result" }, { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom pages for a zone" ], "x-api-token-group": [ "Custom Pages Write", "Custom Pages Read", "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages.zone-custom-pages", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "custom-pages-for-a-zone-update-a-custom-page", "summary": "Update a custom page", "description": "Updates the configuration of an existing custom page.", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_error_page_type" } }, { "name": "zone_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/custom-pages_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "state": { "$ref": "#/components/schemas/custom-pages_state" }, "url": { "$ref": "#/components/schemas/custom-pages_url" } }, "required": [ "url", "state" ] } } } }, "responses": { "200": { "description": "Update a custom page response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-pages_custom_page_result" } } } }, "4XX": { "description": "Update a custom page response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_custom_page_result" }, { "$ref": "#/components/schemas/custom-pages_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Custom pages for a zone" ], "x-api-token-group": [ "Custom Pages Write", "Zone Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-pages", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}": { "delete": { "operationId": "zones-0-delete", "summary": "Delete Zone", "description": "Deletes an existing zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier" } } ], "responses": { "200": { "description": "Delete Zone response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-single-id" } } } }, "4XX": { "description": "Delete Zone response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone" ], "x-api-token-group": [ "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "zones-0-get", "summary": "Zone Details", "description": "Retrieves detailed information about a specific zone identified by its zone ID.\n\nReturns zone configuration, status, nameservers, and associated metadata.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier" } } ], "responses": { "200": { "description": "Zone Details response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/zones_zone" } }, "type": "object" } ] } } } }, "4XX": { "description": "Zone Details response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read", "Zero Trust: PII Read", "Zaraz Edit", "Zaraz Read", "Zaraz Admin", "Access: Apps and Policies Revoke", "Access: Apps and Policies Write", "Access: Apps and Policies Read", "Access: Apps and Policies Revoke", "Access: Mutual TLS Certificates Write", "Access: Organizations, Identity Providers, and Groups Write", "Zone Settings Write", "Zone Settings Read", "Zone Read", "DNS Read", "Workers Scripts Write", "Workers Scripts Read", "Zone Write", "Workers Routes Write", "Workers Routes Read", "Stream Write", "Stream Read", "SSL and Certificates Write", "SSL and Certificates Read", "Logs Write", "Logs Read", "Cache Purge", "Page Rules Write", "Page Rules Read", "Load Balancers Write", "Load Balancers Read", "Firewall Services Write", "Firewall Services Read", "DNS Write", "Apps Write", "Analytics Read", "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-cfPermissionsRequired": { "enum": [ "#zone:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "zones-0-patch", "summary": "Edit Zone", "description": "Edits a zone. Only one zone property can be changed at a time.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paused": { "$ref": "#/components/schemas/zones_paused" }, "plan": { "description": "(Deprecated) Please use the `/zones/{zone_id}/subscription` API\nto update a zone's plan. Changing this value will create/cancel\nassociated subscriptions. To view available plans for this zone,\nsee Zone Plans.\n", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/zones_identifier" } } }, "type": { "description": "A full zone implies that DNS is hosted with Cloudflare. A partial\nzone is typically a partner-hosted zone or a CNAME setup. This\nparameter is only available to Enterprise customers or if it has\nbeen explicitly enabled on a zone.\n", "type": "string", "example": "full", "enum": [ "full", "partial", "secondary", "internal" ] }, "vanity_name_servers": { "$ref": "#/components/schemas/zones_vanity_name_servers" } }, "example": { "paused": true } } } } }, "responses": { "200": { "description": "Edit Zone response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/zones_zone" } }, "type": "object" } ] } } } }, "4XX": { "description": "Edit Zone response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone" ], "x-api-token-group": [ "Zone Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/access/apps": { "get": { "operationId": "zone-level-access-applications-list-access-applications", "summary": "List Access Applications", "description": "List all Access Applications in a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "List Access Applications response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-22" } } } }, "4XX": { "description": "List Access Applications response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access applications" ], "x-api-token-group": [ "Access: Apps and Policies Revoke", "Access: Apps and Policies Write", "Access: Apps and Policies Read", "Access: Apps and Policies Revoke", "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps", "x-fern-sdk-method-name": "list", "x-forge-hidden": true, "x-stability": "beta" }, "post": { "operationId": "zone-level-access-applications-add-a-bookmark-application", "summary": "Add an Access application", "description": "Adds a new application to Access.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_apps" } } } }, "responses": { "201": { "description": "Add an Access application response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/access_single_response-21" }, { "properties": { "result": { "$ref": "#/components/schemas/access_apps" } }, "type": "object" } ] } } } }, "4XX": { "description": "Add an Access application response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access applications" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-stability": "beta" } }, "/zones/{zone_id}/access/apps/ca": { "get": { "operationId": "zone-level-access-short-lived-certificate-c-as-list-short-lived-certificate-c-as", "summary": "List short-lived certificate CAs", "description": "Lists short-lived certificate CAs and their public keys.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "List short-lived certificate CAs response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-20" } } } }, "4XX": { "description": "List short-lived certificate CAs response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access short-lived certificate CAs" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Read", "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps.ca", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/zones/{zone_id}/access/apps/{app_id}": { "delete": { "operationId": "zone-level-access-applications-delete-an-access-application", "summary": "Delete an Access application", "description": "Deletes an application from Access.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_app_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "202": { "description": "Delete an Access application response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response" } } } }, "4XX": { "description": "Delete an Access application response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access applications" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "zone-level-access-applications-get-an-access-application", "summary": "Get an Access application", "description": "Fetches information about an Access application.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_app_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get an Access application response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-21" } } } }, "4XX": { "description": "Get an Access application response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access applications" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Read", "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stability": "beta" }, "put": { "operationId": "zone-level-access-applications-update-a-bookmark-application", "summary": "Update an Access application", "description": "Updates an Access application.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_app_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_apps" } } } }, "responses": { "200": { "description": "Update an Access application response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/access_single_response-21" }, { "properties": { "result": { "$ref": "#/components/schemas/access_apps" } }, "type": "object" } ] } } } }, "4XX": { "description": "Update an Access application response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access applications" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps", "x-fern-sdk-method-name": "update", "x-forge-hidden": true, "x-stability": "beta" } }, "/zones/{zone_id}/access/apps/{app_id}/ca": { "delete": { "operationId": "zone-level-access-short-lived-certificate-c-as-delete-a-short-lived-certificate-ca", "summary": "Delete a short-lived certificate CA", "description": "Deletes a short-lived certificate CA.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "202": { "description": "Delete a short-lived certificate CA response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response-5" } } } }, "4XX": { "description": "Delete a short-lived certificate CA response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access short-lived certificate CAs" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps.ca", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "zone-level-access-short-lived-certificate-c-as-get-a-short-lived-certificate-ca", "summary": "Get a short-lived certificate CA", "description": "Fetches a short-lived certificate CA and its public key.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get a short-lived certificate CA response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-19" } } } }, "4XX": { "description": "Get a short-lived certificate CA response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access short-lived certificate CAs" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Read", "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps.ca", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "zone-level-access-short-lived-certificate-c-as-create-a-short-lived-certificate-ca", "summary": "Create a short-lived certificate CA", "description": "Generates a new short-lived certificate CA and public key.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Create a short-lived certificate CA response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-19" } } } }, "4XX": { "description": "Create a short-lived certificate CA response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access short-lived certificate CAs" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps.ca", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/access/apps/{app_id}/policies": { "get": { "operationId": "zone-level-access-policies-list-access-policies", "summary": "List Access policies", "description": "Lists Access policies configured for an application.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "List Access policies response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-23" } } } }, "4XX": { "description": "List Access policies response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access policies" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Read", "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps.policies", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "zone-level-access-policies-create-an-access-policy", "summary": "Create an Access policy", "description": "Create a new Access policy for an application.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approval_groups": { "$ref": "#/components/schemas/access_approval_groups-2" }, "approval_required": { "$ref": "#/components/schemas/access_approval_required-2" }, "decision": { "$ref": "#/components/schemas/access_decision-2" }, "exclude": { "$ref": "#/components/schemas/access_exclude-3" }, "include": { "$ref": "#/components/schemas/access_include" }, "isolation_required": { "$ref": "#/components/schemas/access_isolation_required-2" }, "name": { "$ref": "#/components/schemas/access_name-9" }, "precedence": { "$ref": "#/components/schemas/access_precedence-2" }, "purpose_justification_prompt": { "$ref": "#/components/schemas/access_purpose_justification_prompt" }, "purpose_justification_required": { "$ref": "#/components/schemas/access_purpose_justification_required-2" }, "require": { "$ref": "#/components/schemas/access_require-3" } }, "required": [ "name", "decision", "include" ] } } } }, "responses": { "201": { "description": "Create an Access policy response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-22" } } } }, "4XX": { "description": "Create an Access policy response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access policies" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps.policies", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/access/apps/{app_id}/policies/{policy_id}": { "delete": { "operationId": "zone-level-access-policies-delete-an-access-policy", "summary": "Delete an Access policy", "description": "Delete an Access policy.", "parameters": [ { "name": "policy_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "202": { "description": "Delete an Access policy response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response" } } } }, "4XX": { "description": "Delete an Access policy response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access policies" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps.policies", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "zone-level-access-policies-get-an-access-policy", "summary": "Get an Access policy", "description": "Fetches a single Access policy.", "parameters": [ { "name": "policy_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get an Access policy response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-22" } } } }, "4XX": { "description": "Get an Access policy response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access policies" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Read", "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps.policies", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "zone-level-access-policies-update-an-access-policy", "summary": "Update an Access policy", "description": "Update a configured Access policy.", "parameters": [ { "name": "policy_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approval_groups": { "$ref": "#/components/schemas/access_approval_groups-2" }, "approval_required": { "$ref": "#/components/schemas/access_approval_required-2" }, "decision": { "$ref": "#/components/schemas/access_decision-2" }, "exclude": { "$ref": "#/components/schemas/access_exclude-3" }, "include": { "$ref": "#/components/schemas/access_include" }, "isolation_required": { "$ref": "#/components/schemas/access_isolation_required-2" }, "name": { "$ref": "#/components/schemas/access_name-9" }, "precedence": { "$ref": "#/components/schemas/access_precedence-2" }, "purpose_justification_prompt": { "$ref": "#/components/schemas/access_purpose_justification_prompt" }, "purpose_justification_required": { "$ref": "#/components/schemas/access_purpose_justification_required-2" }, "require": { "$ref": "#/components/schemas/access_require-3" } }, "required": [ "name", "decision", "include" ] } } } }, "responses": { "200": { "description": "Update an Access policy response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-22" } } } }, "4XX": { "description": "Update an Access policy response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access policies" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps.policies", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/access/apps/{app_id}/revoke_tokens": { "post": { "operationId": "zone-level-access-applications-revoke-service-tokens", "summary": "Revoke application tokens", "description": "Revokes all tokens issued for an application.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_app_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "202": { "description": "Revoke application tokens response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_empty_response-2" } } } }, "4XX": { "description": "Revoke application tokens response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access applications" ], "x-api-token-group": [ "Access: Apps and Policies Revoke", "Access: Apps and Policies Write", "Access: Apps and Policies Revoke", "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps.revoke.tokens", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation revokes all service tokens for the application." } }, "/zones/{zone_id}/access/apps/{app_id}/settings": { "patch": { "operationId": "zone-level-access-applications-patch-update-access-application-settings", "summary": "Update application settings", "description": "Updates application settings.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_app_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_app_settings_request" } } } }, "responses": { "202": { "description": "Update application settings response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/access_single_response_update" } ] } } } }, "4XX": { "description": "Update application settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access applications" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps.settings", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "zone-level-access-applications-put-update-access-application-settings", "summary": "Update application settings", "description": "Updates application settings.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_app_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_app_settings_request" } } } }, "responses": { "202": { "description": "Update application settings response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/access_single_response_update" } ] } } } }, "4XX": { "description": "Update application settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access applications" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps.settings", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/access/apps/{app_id}/user_policy_checks": { "get": { "operationId": "zone-level-access-applications-test-access-policies", "summary": "Test Access policies", "description": "Tests if a specific user has permission to access an application.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_app_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Test Access policies response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_policy_check_response-2" } } } }, "4XX": { "description": "Test Access policies response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access applications" ], "x-api-token-group": [ "Access: Apps and Policies Write", "Access: Apps and Policies Read", "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.apps.user.policy.checks", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/access/certificates": { "get": { "operationId": "zone-level-access-mtls-authentication-list-mtls-certificates", "summary": "List mTLS certificates", "description": "Lists all mTLS certificates.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "List mTLS certificates response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-21" } } } }, "4XX": { "description": "List mTLS certificates response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access mTLS authentication" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write", "Access: Mutual TLS Certificates Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.certificates", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "zone-level-access-mtls-authentication-add-an-mtls-certificate", "summary": "Add an mTLS certificate", "description": "Adds a new mTLS root certificate to Access.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "associated_hostnames": { "$ref": "#/components/schemas/access_associated_hostnames-2" }, "certificate": { "description": "The certificate content.", "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIGAjCCA+qgAwIBAgIJAI7kymlF7CWT...N4RI7KKB7nikiuUf8vhULKy5IX10\nDrUtmu/B\n-----END CERTIFICATE-----" }, "name": { "$ref": "#/components/schemas/access_name-18" } }, "required": [ "name", "certificate" ] } } } }, "responses": { "201": { "description": "Add an mTLS certificate response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-20" } } } }, "4XX": { "description": "Add an mTLS certificate response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access mTLS authentication" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.certificates", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/access/certificates/settings": { "get": { "operationId": "zone-level-access-mtls-authentication-list-mtls-certificates-hostname-settings", "summary": "List all mTLS hostname settings", "description": "List all mTLS hostname settings for this zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "List mTLS hostname settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection_hostnames-2" } } } }, "4XX": { "description": "List mTLS hostname settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access mTLS authentication" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write", "Access: Mutual TLS Certificates Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.certificates.settings", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "put": { "operationId": "zone-level-access-mtls-authentication-update-an-mtls-certificate-settings", "summary": "Update an mTLS certificate's hostname settings", "description": "Updates an mTLS certificate's hostname settings.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "array", "items": { "$ref": "#/components/schemas/access_settings-2" } } }, "required": [ "settings" ] } } } }, "responses": { "202": { "description": "Update an mTLS certificates hostname settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection_hostnames-2" } } } }, "4XX": { "description": "Update an mTLS certificates hostname settings failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access mTLS authentication" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.certificates.settings", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/access/certificates/{certificate_id}": { "delete": { "operationId": "zone-level-access-mtls-authentication-delete-an-mtls-certificate", "summary": "Delete an mTLS certificate", "description": "Deletes an mTLS certificate.", "parameters": [ { "name": "certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Delete an mTLS certificate response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response-3" } } } }, "4XX": { "description": "Delete an mTLS certificate response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access mTLS authentication" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.certificates", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "zone-level-access-mtls-authentication-get-an-mtls-certificate", "summary": "Get an mTLS certificate", "description": "Fetches a single mTLS certificate.", "parameters": [ { "name": "certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get an mTLS certificate response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-20" } } } }, "4XX": { "description": "Get an mTLS certificate response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access mTLS authentication" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write", "Access: Mutual TLS Certificates Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.certificates", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "zone-level-access-mtls-authentication-update-an-mtls-certificate", "summary": "Update an mTLS certificate", "description": "Updates a configured mTLS certificate.", "parameters": [ { "name": "certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "associated_hostnames": { "$ref": "#/components/schemas/access_associated_hostnames-2" }, "name": { "$ref": "#/components/schemas/access_name-18" } }, "required": [ "associated_hostnames" ] } } } }, "responses": { "200": { "description": "Update an mTLS certificate response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-20" } } } }, "4XX": { "description": "Update an mTLS certificate response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access mTLS authentication" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.certificates", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/access/groups": { "get": { "operationId": "zone-level-access-groups-list-access-groups", "summary": "List Access groups", "description": "Lists all Access groups.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "List Access groups response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-18" } } } }, "4XX": { "description": "List Access groups response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access groups" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write", "Access: Organizations, Identity Providers, and Groups Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.groups", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "zone-level-access-groups-create-an-access-group", "summary": "Create an Access group", "description": "Creates a new Access group.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "exclude": { "$ref": "#/components/schemas/access_exclude" }, "include": { "$ref": "#/components/schemas/access_include" }, "name": { "$ref": "#/components/schemas/access_name-16" }, "require": { "$ref": "#/components/schemas/access_require" } }, "required": [ "name", "include" ] } } } }, "responses": { "201": { "description": "Create an Access group response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-17" } } } }, "4XX": { "description": "Create an Access group response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access groups" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.groups", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/access/groups/{group_id}": { "delete": { "operationId": "zone-level-access-groups-delete-an-access-group", "summary": "Delete an Access group", "description": "Deletes an Access group.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "202": { "description": "Delete an Access group response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response" } } } }, "4XX": { "description": "Delete an Access group response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access groups" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.groups", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "zone-level-access-groups-get-an-access-group", "summary": "Get an Access group", "description": "Fetches a single Access group.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get an Access group response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-17" } } } }, "4XX": { "description": "Get an Access group response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access groups" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write", "Access: Organizations, Identity Providers, and Groups Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.groups", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "zone-level-access-groups-update-an-access-group", "summary": "Update an Access group", "description": "Updates a configured Access group.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "exclude": { "$ref": "#/components/schemas/access_exclude" }, "include": { "$ref": "#/components/schemas/access_include" }, "name": { "$ref": "#/components/schemas/access_name-16" }, "require": { "$ref": "#/components/schemas/access_require" } }, "required": [ "name", "include" ] } } } }, "responses": { "200": { "description": "Update an Access group response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-17" } } } }, "4XX": { "description": "Update an Access group response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access groups" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.groups", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/access/identity_providers": { "get": { "operationId": "zone-level-access-identity-providers-list-access-identity-providers", "summary": "List Access identity providers", "description": "Lists all configured identity providers.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "List Access identity providers response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-17" } } } }, "4XX": { "description": "List Access identity providers response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access identity providers" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write", "Access: Organizations, Identity Providers, and Groups Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.zone-identity-providers", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "zone-level-access-identity-providers-add-an-access-identity-provider", "summary": "Add an Access identity provider", "description": "Adds a new identity provider to Access.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_identity-providers-2" } } } }, "responses": { "201": { "description": "Add an Access identity provider response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-16" } } } }, "4XX": { "description": "Add an Access identity provider response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access identity providers" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.zone-identity-providers", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-stability": "beta" } }, "/zones/{zone_id}/access/identity_providers/{identity_provider_id}": { "delete": { "operationId": "zone-level-access-identity-providers-delete-an-access-identity-provider", "summary": "Delete an Access identity provider", "description": "Deletes an identity provider from Access.", "parameters": [ { "name": "identity_provider_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "202": { "description": "Delete an Access identity provider response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_id_response" } } } }, "4XX": { "description": "Delete an Access identity provider response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access identity providers" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.zone-identity-providers", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "zone-level-access-identity-providers-get-an-access-identity-provider", "summary": "Get an Access identity provider", "description": "Fetches a configured identity provider.", "parameters": [ { "name": "identity_provider_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get an Access identity provider response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-16" } } } }, "4XX": { "description": "Get an Access identity provider response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access identity providers" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write", "Access: Organizations, Identity Providers, and Groups Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.zone-identity-providers", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "zone-level-access-identity-providers-update-an-access-identity-provider", "summary": "Update an Access identity provider", "description": "Updates a configured identity provider.", "parameters": [ { "name": "identity_provider_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_identity-providers-2" } } } }, "responses": { "200": { "description": "Update an Access identity provider response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-16" } } } }, "4XX": { "description": "Update an Access identity provider response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access identity providers" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.zone-identity-providers", "x-fern-sdk-method-name": "update", "x-forge-hidden": true, "x-stability": "beta" } }, "/zones/{zone_id}/access/organizations": { "get": { "operationId": "zone-level-zero-trust-organization-get-your-zero-trust-organization", "summary": "Get your Zero Trust organization", "description": "Returns the configuration for your Zero Trust organization.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier-4" } } ], "responses": { "200": { "description": "Get your Zero Trust organization response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_get_response-2" } } } }, "4XX": { "description": "Get your Zero Trust organization response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Zero Trust organization" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Revoke", "Access: Organizations, Identity Providers, and Groups Write", "Access: Organizations, Identity Providers, and Groups Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.zone-organizations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "zone-level-zero-trust-organization-create-your-zero-trust-organization", "summary": "Create your Zero Trust organization", "description": "Sets up a Zero Trust organization for your account.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier-4" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auth_domain": { "$ref": "#/components/schemas/access_auth_domain-2" }, "is_ui_read_only": { "$ref": "#/components/schemas/access_is_ui_read_only-2" }, "login_design": { "$ref": "#/components/schemas/access_login_design" }, "name": { "$ref": "#/components/schemas/access_name-15" }, "ui_read_only_toggle_reason": { "$ref": "#/components/schemas/access_ui_read_only_toggle_reason" }, "user_seat_expiration_inactive_time": { "$ref": "#/components/schemas/access_user_seat_expiration_inactive_time-2" } }, "required": [ "name", "auth_domain" ] } } } }, "responses": { "201": { "description": "Create your Zero Trust organization response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-15" } } } }, "4XX": { "description": "Create your Zero Trust organization response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Zero Trust organization" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.zone-organizations", "x-fern-sdk-method-name": "create", "x-forge-hidden": true }, "put": { "operationId": "zone-level-zero-trust-organization-update-your-zero-trust-organization", "summary": "Update your Zero Trust organization", "description": "Updates the configuration for your Zero Trust organization.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier-4" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auth_domain": { "$ref": "#/components/schemas/access_auth_domain-2" }, "is_ui_read_only": { "$ref": "#/components/schemas/access_is_ui_read_only-2" }, "login_design": { "$ref": "#/components/schemas/access_login_design" }, "name": { "$ref": "#/components/schemas/access_name-15" }, "ui_read_only_toggle_reason": { "$ref": "#/components/schemas/access_ui_read_only_toggle_reason" }, "user_seat_expiration_inactive_time": { "$ref": "#/components/schemas/access_user_seat_expiration_inactive_time-2" } } } } } }, "responses": { "200": { "description": "Update your Zero Trust organization response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-15" } } } }, "4XX": { "description": "Update your Zero Trust organization response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Zero Trust organization" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.zone-organizations", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/access/organizations/revoke_user": { "post": { "operationId": "zone-level-zero-trust-organization-revoke-all-access-tokens-for-a-user", "summary": "Revoke all Access tokens for a user", "description": "Revokes a user's access across all applications.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier-4" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "description": "The email of the user to revoke.", "type": "string", "example": "test@example.com" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Revoke all Access tokens for a user response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_empty_response" } } } }, "4XX": { "description": "Revoke all Access tokens for a user response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Zero Trust organization" ], "x-api-token-group": [ "Access: Organizations, Identity Providers, and Groups Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.zone-organizations", "x-fern-sdk-method-name": "revoke-user-create", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation revokes all access tokens for a user, affecting their access to all applications within the zone." } }, "/zones/{zone_id}/access/service_tokens": { "get": { "operationId": "zone-level-access-service-tokens-list-service-tokens", "summary": "List service tokens", "description": "Lists all service tokens.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "List service tokens response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_response_collection-19" } } } }, "4XX": { "description": "List service tokens response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access service tokens" ], "x-api-token-group": [ "Access: Service Tokens Write", "Access: Service Tokens Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.service-tokens", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "zone-level-access-service-tokens-create-a-service-token", "summary": "Create a service token", "description": "Generates a new service token. **Note:** This is the only time you can get the Client Secret. If you lose the Client Secret, you will have to create a new service token.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_secret_version": { "$ref": "#/components/schemas/access_client_secret_version" }, "duration": { "$ref": "#/components/schemas/access_duration-2" }, "enabled": { "$ref": "#/components/schemas/access_enabled" }, "name": { "$ref": "#/components/schemas/access_name-17" }, "previous_client_secret_expires_at": { "$ref": "#/components/schemas/access_previous_client_secret_expires_at" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Create a service token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_create_response-2" } } } }, "4XX": { "description": "Create a service token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access service tokens" ], "x-api-token-group": [ "Access: Service Tokens Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.service-tokens", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/access/service_tokens/{service_token_id}": { "delete": { "operationId": "zone-level-access-service-tokens-delete-a-service-token", "summary": "Delete a service token", "description": "Deletes a service token.", "parameters": [ { "name": "service_token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Delete a service token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-18" } } } }, "4XX": { "description": "Delete a service token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access service tokens" ], "x-api-token-group": [ "Access: Service Tokens Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.service-tokens", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "zone-level-access-service-tokens-get-a-service-token", "summary": "Get a service token", "description": "Fetches a single service token.", "parameters": [ { "name": "service_token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "responses": { "200": { "description": "Get a service token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-18" } } } }, "4XX": { "description": "Get a service token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access service tokens" ], "x-api-token-group": [ "Access: Service Tokens Write", "Access: Service Tokens Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.service-tokens", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "zone-level-access-service-tokens-update-a-service-token", "summary": "Update a service token", "description": "Updates a configured service token.", "parameters": [ { "name": "service_token_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/access_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_secret_version": { "$ref": "#/components/schemas/access_client_secret_version" }, "duration": { "$ref": "#/components/schemas/access_duration-2" }, "enabled": { "$ref": "#/components/schemas/access_enabled" }, "name": { "$ref": "#/components/schemas/access_name-17" }, "previous_client_secret_expires_at": { "$ref": "#/components/schemas/access_previous_client_secret_expires_at" } } } } } }, "responses": { "200": { "description": "Update a service token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_single_response-18" } } } }, "4XX": { "description": "Update a service token response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/access_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Access service tokens" ], "x-api-token-group": [ "Access: Service Tokens Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.service-tokens", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/acm/custom_trust_store": { "get": { "operationId": "custom-origin-trust-store-list-details", "summary": "List Custom Origin Trust Store Details", "description": "Get Custom Origin Trust Store for a Zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of records per page.", "type": "number", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "limit", "in": "query", "schema": { "description": "Limit to the number of records returned.", "type": "integer", "example": 10 } }, { "name": "offset", "in": "query", "schema": { "description": "Offset the results.", "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Custom Origin Trust Store Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_trust_store_response_collection" } } } }, "4XX": { "description": "Custom Origin Trust Store response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_trust_store_response_collection" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom Origin Trust Store" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "acm.custom-trust-store", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "custom-origin-trust-store-create", "summary": "Upload Custom Origin Trust Store", "description": "Upload a root CA certificate to the Custom Origin Trust Store for a Zone. Only root CA certificates are accepted.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "certificate": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate-3" } }, "required": [ "certificate" ] } } } }, "responses": { "200": { "description": "Upload Custom Origin Trust Store response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_trust_store_response_single" } } } }, "4XX": { "description": "Upload Custom Origin Trust Store response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_trust_store_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom Origin Trust Store" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read", "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "acm.custom-trust-store", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/acm/custom_trust_store/{custom_origin_trust_store_id}": { "delete": { "operationId": "custom-origin-trust-store-delete", "summary": "Delete Custom Origin Trust Store", "description": "Removes a root CA certificate from the custom origin trust store. Origins using certificates signed by this CA will no longer be trusted.", "parameters": [ { "name": "custom_origin_trust_store_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Delete Custom Origin Trust Store response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_trust_store_response_id_only" } } } }, "4XX": { "description": "Delete Custom Origin Trust Store response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom Origin Trust Store" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read", "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "acm.custom-trust-store", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "custom-origin-trust-store-details", "summary": "Custom Origin Trust Store Details", "description": "Retrieves details about a specific root CA certificate in the custom origin trust store, including expiration and subject information.", "parameters": [ { "name": "custom_origin_trust_store_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Custom Origin Trust Store Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_trust_store_response_single" } } } }, "4XX": { "description": "Custom Origin Trust Store Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_trust_store_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom Origin Trust Store" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "acm.custom-trust-store", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/acm/total_tls": { "get": { "operationId": "total-tls-total-tls-settings-details", "summary": "Total TLS Settings Details", "description": "Get Total TLS Settings for a Zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Total TLS Settings Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_total_tls_settings_response" } } } }, "4XX": { "description": "Total TLS Settings Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_total_tls_settings_response" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Total TLS" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "acm.total-tls", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "total-tls-enable-or-disable-total-tls", "summary": "Enable or Disable Total TLS", "description": "Set Total TLS Settings or disable the feature for a Zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "certificate_authority": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_authority-3" }, "enabled": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_enabled-3" } }, "required": [ "enabled" ] } } } }, "responses": { "200": { "description": "Enable or Disable Total TLS response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_total_tls_settings_response" } } } }, "4XX": { "description": "Enable or Disable Total TLS response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_total_tls_settings_response" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Total TLS" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read", "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "acm.total-tls", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/activation_check": { "put": { "operationId": "put-zones-zone_id-activation_check", "summary": "Rerun the Activation Check", "description": "Triggeres a new activation check for a PENDING Zone. This can be\ntriggered every 5 min for paygo/ent customers, every hour for FREE\nZones.", "parameters": [ { "name": "zone_id", "in": "path", "description": "Zone ID", "required": true, "schema": { "$ref": "#/components/schemas/zone-activation_identifier" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zone-activation_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/zone-activation_identifier" } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Client Error", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zone-activation_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone" ], "x-api-token-group": [ "Zone Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zone", "x-fern-sdk-method-name": "activate" } }, "/zones/{zone_id}/addressing/regional_hostnames": { "get": { "operationId": "dls-zone-regional-hostnames-list", "summary": "List Regional Hostnames", "description": "List all Regional Hostnames within a zone.", "parameters": [ { "$ref": "#/components/parameters/dls_zone_id" } ], "responses": { "200": { "description": "List hostnames response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dls_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/dls_regional_hostname_response" } } } } ] } } } }, "4XX": { "description": "Failure to list hostnames", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dls_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "DLS Regional Services" ], "x-api-token-group": [ "DNS Read", "DNS Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.regional_hostnames", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "dls-zone-regional-hostnames-create", "summary": "Create Regional Hostname", "description": "Create a new Regional Hostname entry. Cloudflare will only use data centers that are physically located within the chosen region to decrypt and service HTTPS traffic. Learn more about [Regional Services](https://developers.cloudflare.com/data-localization/regional-services/get-started/).", "parameters": [ { "$ref": "#/components/parameters/dls_zone_id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "hostname": { "$ref": "#/components/schemas/dls_hostname" }, "region_key": { "$ref": "#/components/schemas/dls_region_key" }, "routing": { "$ref": "#/components/schemas/dls_routing" } }, "required": [ "hostname", "region_key" ] } } } }, "responses": { "200": { "description": "Create hostname response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dls_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/dls_regional_hostname_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Failure to create hostname", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dls_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "DLS Regional Services" ], "x-api-token-group": [ "DNS Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.regional_hostnames", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/addressing/regional_hostnames/{hostname}": { "delete": { "operationId": "dls-zone-regional-hostnames-delete", "summary": "Delete Regional Hostname", "description": "Delete the region configuration for a specific Regional Hostname.", "parameters": [ { "$ref": "#/components/parameters/dls_zone_id" }, { "$ref": "#/components/parameters/dls_hostname" } ], "responses": { "200": { "description": "Delete hostname response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dls_api-response-common" } ] } } } }, "4XX": { "description": "Failure to delete hostname", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dls_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "DLS Regional Services" ], "x-api-token-group": [ "DNS Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.regional_hostnames", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "dls-zone-regional-hostnames-fetch", "summary": "Fetch Regional Hostname", "description": "Fetch the configuration for a specific Regional Hostname, within a zone.", "parameters": [ { "$ref": "#/components/parameters/dls_zone_id" }, { "$ref": "#/components/parameters/dls_hostname" } ], "responses": { "200": { "description": "Fetch hostname response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dls_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/dls_regional_hostname_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Failure to fetch hostname", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dls_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "DLS Regional Services" ], "x-api-token-group": [ "DNS Read", "DNS Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.regional_hostnames", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "dls-zone-regional-hostnames-patch", "summary": "Update Regional Hostname", "description": "Update the configuration for a specific Regional Hostname. Only the region_key of a hostname is mutable.", "parameters": [ { "$ref": "#/components/parameters/dls_zone_id" }, { "$ref": "#/components/parameters/dls_hostname" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "region_key": { "$ref": "#/components/schemas/dls_region_key" } }, "required": [ "region_key" ] } } } }, "responses": { "200": { "description": "Update hostname response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dls_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/dls_regional_hostname_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Failure to update hostname", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dls_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "DLS Regional Services" ], "x-api-token-group": [ "DNS Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "addressing.regional_hostnames", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/ai-audit/robots": { "get": { "operationId": "ai-audit-get-robots", "summary": "Get robots.txt rules", "description": "Fetches and parses the robots.txt file for a zone or a specific subdomain within the zone. Returns parsed user-agent rules, content signals, and sitemaps.", "parameters": [ { "name": "zone_id", "in": "path", "description": "Identifier of the zone.", "required": true, "schema": { "type": "string" } }, { "name": "subdomain", "in": "query", "description": "Optional subdomain to fetch robots.txt for. If omitted, fetches robots.txt for the zone apex domain.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response with parsed robots.txt rules.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ai-audit_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/ai-audit_robots_rules" } }, "type": "object" } ] } } } }, "400": { "description": "Bad request (invalid subdomain or missing parameters).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ai-audit_api-response-common-failure" } } } }, "401": { "description": "Unauthorized (missing or invalid authentication).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ai-audit_api-response-common-failure" } } } }, "403": { "description": "Forbidden (insufficient permissions or entitlement).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ai-audit_api-response-common-failure" } } } }, "404": { "description": "Domain not found or robots.txt not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ai-audit_api-response-common-failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ai-audit_api-response-common-failure" } } } }, "503": { "description": "Upstream authentication service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ai-audit_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Audit" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-sdk-group-name": "ai-audit.robots", "x-fern-sdk-method-name": "get" } }, "/zones/{zone_id}/ai-audit/robots/bulk": { "post": { "operationId": "ai-audit-bulk-get-robots", "summary": "Bulk get robots.txt rules", "description": "Fetches and parses robots.txt files for multiple domains within a zone in a single request. Each domain must belong to the specified zone. Results are keyed by hostname.", "parameters": [ { "name": "zone_id", "in": "path", "description": "Identifier of the zone.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Array of domain hostnames to fetch robots.txt for. Each domain must end with the zone name. Maximum 25 domains per request.", "type": "array", "items": { "type": "string" }, "example": [ "example.com", "blog.example.com" ], "maxItems": 25 } } } }, "responses": { "200": { "description": "Successful response with parsed robots.txt rules keyed by hostname.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ai-audit_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/ai-audit_bulk_robots_rules" } }, "type": "object" } ] } } } }, "400": { "description": "Bad request (invalid domains, exceeds 25-domain limit, or domain not in zone).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ai-audit_api-response-common-failure" } } } }, "401": { "description": "Unauthorized (missing or invalid authentication).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ai-audit_api-response-common-failure" } } } }, "403": { "description": "Forbidden (insufficient permissions or entitlement).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ai-audit_api-response-common-failure" } } } }, "404": { "description": "Domain not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ai-audit_api-response-common-failure" } } } }, "408": { "description": "Request timeout (bulk fetch exceeded global timeout).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ai-audit_api-response-common-failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ai-audit_api-response-common-failure" } } } }, "503": { "description": "Upstream authentication service unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ai-audit_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "AI Audit" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-sdk-group-name": "ai-audit.robots", "x-fern-sdk-method-name": "bulk-get" } }, "/zones/{zone_id}/ai-security/custom-topics": { "get": { "operationId": "ai-security-custom-topics-get", "summary": "Get the AI Security for Apps custom topics of a zone.", "description": "Get the custom topic categories defined for the zone. While AI Security for Apps is enabled, it scores every incoming prompt against these topics and writes the scores to the `cf.llm.prompt.custom_topic_categories` field, keyed by topic label. Topics can be configured while the detection is disabled, but no prompt is scored until you enable it.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_zone_id" } } ], "responses": { "200": { "description": "Get AI Security for Apps custom topics response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-topics" } } } }, "4XX": { "description": "Get AI Security for Apps custom topics failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-topics" }, { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "AI Security for Apps" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-security.custom-topics", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "ai-security-custom-topics-put", "summary": "Update the AI Security for Apps custom topics of a zone.", "description": "Update the custom topic list of the zone, overwriting it entirely with the topics in the request, so include\nevery topic you want to keep. Changes can take up to a minute to propagate.\n\nEach entry has a `label`, used to reference the topic in rule expressions and analytics, and a `topic`\ndescription, which the classifier scores prompts against while AI Security for Apps is enabled. The following\nrules apply:\n\n- A zone can hold at most 20 topics.\n- `label` must be 2–20 characters, using only lowercase letters (a–z), digits (0–9), and hyphens.\n- `topic` must be 2–50 printable ASCII characters.\n- Labels must be unique within the zone, and so must topic descriptions.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_zone_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_custom-topics" } } } }, "responses": { "200": { "description": "Update AI Security for Apps custom topics response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-topics" } } } }, "4XX": { "description": "Update AI Security for Apps custom topics failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-topics" }, { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "AI Security for Apps" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-security.custom-topics", "x-fern-sdk-method-name": "update", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation overwrites the AI Security for Apps custom topics for a zone." } }, "/zones/{zone_id}/ai-security/settings": { "get": { "operationId": "ai-security-settings-get", "summary": "Get the AI Security for Apps status for a zone.", "description": "Get the current AI Security for Apps status for the zone. While enabled, Cloudflare scans prompts sent to endpoints labeled `cf-llm` for personally identifiable information, unsafe topics, and prompt injection attempts.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_zone_id" } } ], "responses": { "200": { "description": "Get AI Security for Apps status response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_response-settings" } } } }, "4XX": { "description": "Get AI Security for Apps status failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_response-settings" }, { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "AI Security for Apps" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-security", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "ai-security-settings-put", "summary": "Update the AI Security for Apps status for a zone.", "description": "Update the AI Security for Apps status for the zone, enabling or disabling the detection. The detection results are exposed as `cf.llm.prompt.*` fields for use in custom rules and rate limiting rules; changes can take up to a minute to propagate.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_zone_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_settings" } } } }, "responses": { "200": { "description": "Update AI Security for Apps status response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_response-settings" } } } }, "4XX": { "description": "Update AI Security for Apps status failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_response-settings" }, { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure-3" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "AI Security for Apps" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ai-security", "x-fern-sdk-method-name": "update", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation toggles AI Security for Apps for a zone." } }, "/zones/{zone_id}/analytics/latency": { "get": { "operationId": "argo-analytics-for-zone-argo-analytics-for-a-zone", "summary": "Argo Analytics for a zone", "description": "Retrieves aggregate Argo Smart Routing analytics for a zone, including latency improvements, bandwidth savings, and routing statistics.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/argo-analytics_identifier" } }, { "name": "bins", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Argo Analytics for a zone response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/argo-analytics_response_single" } } } }, "4XX": { "description": "Argo Analytics for a zone response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/argo-analytics_response_single" }, { "$ref": "#/components/schemas/argo-analytics_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Argo Analytics for Zone" ], "x-api-token-group": [ "Analytics Read" ], "x-cfPermissionsRequired": { "enum": [ "#analytics:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "analytics.latency", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/analytics/latency/colos": { "get": { "operationId": "argo-analytics-for-geolocation-argo-analytics-for-a-zone-at-different-po-ps", "summary": "Argo Analytics for a zone at different PoPs", "description": "Retrieves Argo Smart Routing analytics broken down by geographic points of presence (PoPs). Shows latency improvements and routing efficiency per location.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/argo-analytics_identifier" } } ], "responses": { "200": { "description": "Argo Analytics for a zone at different PoPs response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/argo-analytics_response_single" } } } }, "4XX": { "description": "Argo Analytics for a zone at different PoPs response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/argo-analytics_response_single" }, { "$ref": "#/components/schemas/argo-analytics_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Argo Analytics for Geolocation" ], "x-api-token-group": [ "Analytics Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "analytics.latency.colos", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/api_gateway/configuration": { "get": { "operationId": "api-shield-settings-retrieve-information-about-specific-configuration-properties", "summary": "Get session identifier settings", "description": "Returns the authentication identifier characteristics configured for the zone. Header, cookie, or JWT claim values identify distinct API sessions.", "responses": { "200": { "$ref": "#/components/responses/api-shield_config-get-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic-failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "API Shield Settings" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.session-identifiers", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "name": "normalize", "in": "query", "description": "Ensures that the configuration is written or retrieved in normalized fashion", "schema": { "type": "boolean" } } ], "put": { "operationId": "api-shield-settings-set-configuration-properties", "summary": "Update session identifier settings", "description": "Replaces the zone's authentication identifier characteristics used to identify distinct API sessions.", "requestBody": { "$ref": "#/components/requestBodies/api-shield_config-update" }, "responses": { "200": { "$ref": "#/components/responses/api-shield_config-update-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic-failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "API Shield Settings" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.session-identifiers", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/api_gateway/discovery": { "get": { "operationId": "api-shield-api-discovery-retrieve-discovered-operations-on-a-zone-as-openapi", "summary": "Export discovered API operations as OpenAPI schemas", "description": "Returns the latest API operations discovered from zone traffic, rendered as OpenAPI schemas.", "responses": { "200": { "description": "Retrieve discovered operations on a zone, rendered as OpenAPI schemas response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_schema_response_discovery" } } } }, "4XX": { "description": "Retrieve discovered operations on a zone, rendered as OpenAPI schemas response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_schema_response_discovery" }, { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield API Discovery" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.discovery", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ] }, "/zones/{zone_id}/api_gateway/discovery/operations": { "get": { "operationId": "api-shield-api-discovery-retrieve-discovered-operations-on-a-zone", "summary": "List discovered web and API operations", "description": "Returns the latest web and API operations discovered from zone traffic.", "parameters": [ { "$ref": "#/components/parameters/api-shield_page" }, { "$ref": "#/components/parameters/api-shield_per_page" }, { "$ref": "#/components/parameters/api-shield_host_parameter" }, { "$ref": "#/components/parameters/api-shield_method_parameter" }, { "$ref": "#/components/parameters/api-shield_endpoint_parameter" }, { "$ref": "#/components/parameters/api-shield_direction_parameter" }, { "$ref": "#/components/parameters/api-shield_order_parameter" }, { "$ref": "#/components/parameters/api-shield_diff_parameter" }, { "$ref": "#/components/parameters/api-shield_api_discovery_origin_parameter" }, { "$ref": "#/components/parameters/api-shield_api_discovery_state_parameter" } ], "responses": { "200": { "description": "Retrieve discovered operations on a zone response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_discovery_operation" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Retrieve discovered operations on a zone response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield API Discovery" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.discovery.operations", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ], "patch": { "operationId": "api-shield-api-patch-discovered-operations", "summary": "Edit discovered web and API operations", "description": "Updates the state of one or more discovered web and API operations.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api_discovery_patch_multiple_request" } } } }, "responses": { "200": { "description": "Patch discovered operations response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_patch_discoveries_response" } } } }, "4XX": { "description": "Patch discovered operations response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield API Discovery" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.discovery.operations", "x-fern-sdk-method-name": "bulk-edit", "x-forge-hidden": true } }, "/zones/{zone_id}/api_gateway/discovery/operations/{discovery_id}": { "get": { "operationId": "api-shield-api-discovery-retrieve-discovered-operation-by-id", "summary": "Get a discovered web or API operation", "description": "Returns a discovered web or API operation by discovery ID.", "responses": { "200": { "description": "Retrieve discovered operation response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_discovery_operation" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Retrieve discovered operation response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield API Discovery" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.discovery.operations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "$ref": "#/components/parameters/api-shield_discovery_id" } ], "patch": { "operationId": "api-shield-api-patch-discovered-operation", "summary": "Edit a discovered web or API operation", "description": "Updates the state of a discovered web or API operation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api_discovery_state_patch" } ] } } } } } }, "responses": { "200": { "description": "Patch discovered operation response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_patch_discovery_response" } } } }, "4XX": { "description": "Patch discovered operation response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield API Discovery" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.discovery.operations", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/api_gateway/expression-template/fallthrough": { "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ], "post": { "operationId": "api-shield-expression-templates-fallthrough", "summary": "Generate a fallthrough WAF expression template", "description": "Generates a WAF expression template that matches fallthrough traffic for the supplied API hosts. This operation is deprecated and should not be used for new integrations.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_request_expression_templates_fallthrough" } } } }, "responses": { "200": { "description": "Generate fallthrough WAF expression template response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_response_expression_templates_fallthrough" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Generate fallthrough WAF expression template failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield WAF Expression Templates" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "api-security.expression-template.fallthrough", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use the cf.api_gateway.fallthrough_detected field in custom rule for a more customized logic check." } }, "/zones/{zone_id}/api_gateway/labels": { "get": { "operationId": "api-shield-labels-get-labels", "summary": "List operation labels", "description": "Returns all managed and user-defined labels available for web and API operations in the zone.", "parameters": [ { "$ref": "#/components/parameters/api-shield_page" }, { "$ref": "#/components/parameters/api-shield_per_page" }, { "$ref": "#/components/parameters/api-shield_order_parameter-2" }, { "$ref": "#/components/parameters/api-shield_direction_parameter" }, { "$ref": "#/components/parameters/api-shield_source_parameter" }, { "$ref": "#/components/parameters/api-shield_filter_parameter" }, { "$ref": "#/components/parameters/api-shield_with_mapped_resource_counts_parameter" } ], "responses": { "200": { "description": "Retrieve all labels response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_full_label" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Retrieve all labels response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Labels" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.labels", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ] }, "/zones/{zone_id}/api_gateway/labels/managed/{name}": { "get": { "operationId": "api-shield-labels-get-managed-label", "summary": "Get a managed operation label", "description": "Returns a managed label and the web and API operations associated with it.", "parameters": [ { "$ref": "#/components/parameters/api-shield_with_mapped_resource_counts_parameter" } ], "responses": { "200": { "description": "Retrieve managed label response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_full_managed_label" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Retrieve managed label response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Labels" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.labels.managed", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "$ref": "#/components/parameters/api-shield_label_name_parameter" } ] }, "/zones/{zone_id}/api_gateway/labels/managed/{name}/resources/operation": { "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "$ref": "#/components/parameters/api-shield_label_name_parameter" } ], "put": { "operationId": "api-shield-labels-replace-operations-attached-to-managed-label", "summary": "Replace operations attached to a managed label", "description": "Replaces the complete set of web and API operations attached to the managed label.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_replace_operations_attached_to_label_request" } } } }, "responses": { "200": { "description": "Replace all operations(s) attached to a managed label response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_full_managed_label" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Replace all operations(s) attached to a managed label failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Labels" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.labels.managed.operations", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/api_gateway/labels/user": { "delete": { "operationId": "api-shield-labels-delete-user-labels", "summary": "Delete user-defined operation labels", "description": "Deletes one or more user-defined labels and removes their associations with web and API operations.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label_name" } } } } }, "responses": { "200": { "description": "Delete user labels response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Delete user labels response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Labels" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.labels.user", "x-fern-sdk-method-name": "bulk-delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes the selected user-defined labels and removes them from associated web and API operations." }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ], "post": { "operationId": "api-shield-labels-create-user-labels", "summary": "Create user-defined operation labels", "description": "Creates one or more user-defined labels for classifying web and API operations.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label_request" } } } } }, "responses": { "200": { "description": "Create user labels response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Create user labels response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Labels" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.labels.user", "x-fern-sdk-method-name": "bulk-create", "x-forge-hidden": true } }, "/zones/{zone_id}/api_gateway/labels/user/{name}": { "delete": { "operationId": "api-shield-delete-user-label", "summary": "Delete a user-defined operation label", "description": "Deletes a user-defined label and removes its associations with web and API operations.", "responses": { "200": { "description": "Delete user label response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_label" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Delete label response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Labels" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.labels.user", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes the user-defined label and removes it from associated web and API operations." }, "get": { "operationId": "api-shield-labels-get-user-label", "summary": "Get a user-defined operation label", "description": "Returns a user-defined label and the web and API operations associated with it.", "parameters": [ { "$ref": "#/components/parameters/api-shield_with_mapped_resource_counts_parameter" } ], "responses": { "200": { "description": "Retrieve user label response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_full_label" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Retrieve user label response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Labels" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.labels.user", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "$ref": "#/components/parameters/api-shield_label_name_parameter" } ], "patch": { "operationId": "api-shield-patch-user-label", "summary": "Edit a user-defined operation label", "description": "Updates only the supplied fields on a user-defined label.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_patch_label_request" } } } }, "responses": { "200": { "description": "Patch label response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_label" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Patch label response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Labels" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.labels.user", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "api-shield-put-user-label", "summary": "Update a user-defined operation label", "description": "Replaces all editable fields on a user-defined label.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_put_label_request" } } } }, "responses": { "200": { "description": "Update label response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_label" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Update label response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Labels" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.labels.user", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/api_gateway/labels/user/{name}/resources/operation": { "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "$ref": "#/components/parameters/api-shield_label_name_parameter" } ], "put": { "operationId": "api-shield-labels-replace-operations-attached-to-user-label", "summary": "Replace operations attached to a user-defined label", "description": "Replaces the complete set of web and API operations attached to the user-defined label.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_replace_operations_attached_to_label_request" } } } }, "responses": { "200": { "description": "Replace all operations(s) attached to a user label response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_full_label" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Replace all operations(s) attached to a user label failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Labels" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.labels.user.operations", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/api_gateway/operations": { "delete": { "operationId": "api-shield-endpoint-management-delete-multiple-operations", "summary": "Delete web or API operations", "description": "Deletes multiple web or API operations from endpoint management in one request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_object-with-operation-id" }, "example": [ { "operation_id": "b17c8043-99a0-4202-b7d9-8f7cdbee02cd" }, { "operation_id": "3818d821-5901-4147-a474-f5f5aec1d54e" } ], "uniqueItems": true } } } }, "responses": { "200": { "description": "Delete multiple operations response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common" } } } }, "4XX": { "description": "Delete multiple operations response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Endpoint Management" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.operations", "x-fern-sdk-method-name": "bulk-delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes the selected web or API operations." }, "get": { "operationId": "api-shield-endpoint-management-retrieve-information-about-all-operations-on-a-zone", "summary": "List web and API operations", "description": "Lists web and API operations tracked for the zone, including each operation's method, path, and feature configuration.", "parameters": [ { "$ref": "#/components/parameters/api-shield_page" }, { "$ref": "#/components/parameters/api-shield_per_page" }, { "name": "order", "in": "query", "schema": { "description": "Field to order by. When requesting a feature, the feature keys are available for ordering as well, e.g., `thresholds.suggested_threshold`.", "type": "string", "example": "method", "enum": [ "method", "host", "endpoint", "thresholds.$key" ] } }, { "$ref": "#/components/parameters/api-shield_direction_parameter" }, { "$ref": "#/components/parameters/api-shield_host_parameter" }, { "$ref": "#/components/parameters/api-shield_method_parameter" }, { "$ref": "#/components/parameters/api-shield_endpoint_parameter" }, { "$ref": "#/components/parameters/api-shield_operation_feature_parameter" } ], "responses": { "200": { "description": "Retrieve information about all operations on a zone response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_multiple-operation-response-paginated" } } } }, "4XX": { "description": "Retrieve information about all operations on a zone response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Endpoint Management" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.operations", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ], "post": { "operationId": "api-shield-endpoint-management-add-operations-to-a-zone", "summary": "Create web or API operations", "description": "Creates one or more web or API operations. Hosts, methods, and paths are normalized; an existing matching operation is returned instead of duplicated.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_basic_operation" } } } } }, "responses": { "200": { "description": "Add operations to a zone response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_multiple-operation-response" } } } }, "4XX": { "description": "Add operations to a zone response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Endpoint Management" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.operations", "x-fern-sdk-method-name": "bulk-create", "x-forge-hidden": true } }, "/zones/{zone_id}/api_gateway/operations/item": { "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ], "post": { "operationId": "api-shield-endpoint-management-add-operation-to-a-zone", "summary": "Create a web or API operation", "description": "Creates one web or API operation. The host, method, and path are normalized; an existing matching operation is returned instead of duplicated.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_basic_operation" } } } }, "responses": { "200": { "description": "Add one operation to a zone response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_single-operation-response" } } } }, "4XX": { "description": "Add one operation to a zone response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Endpoint Management" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.operations", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/api_gateway/operations/labels": { "delete": { "operationId": "api-shield-operations-bulk-delete-labels-to-operations", "summary": "Remove labels from web or API operations", "description": "Removes labels from multiple web or API operations in one request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_bulk_delete_labels_on_operation_request" } } } }, "responses": { "200": { "description": "Bulk remove label(s) on operation(s) in endpoint management response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_operation_with_labels_only" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Bulk remove label(s) on operation(s) in endpoint management response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Labels" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.operations.labels", "x-fern-sdk-method-name": "bulk-delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation removes the selected labels from the selected web and API operations." }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ], "post": { "operationId": "api-shield-operations-bulk-post-labels-to-operations", "summary": "Attach labels to web or API operations", "description": "Attaches labels to multiple web or API operations in one request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_bulk_post_labels_on_operation_request" } } } }, "responses": { "200": { "description": "Bulk attach label(s) on operation(s) in endpoint management response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_operation_with_labels_only" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Bulk attach label(s) on operation(s) in endpoint management response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Labels" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.operations.labels", "x-fern-sdk-method-name": "bulk-create", "x-forge-hidden": true }, "put": { "operationId": "api-shield-operations-bulk-put-labels-to-operations", "summary": "Replace labels on web or API operations", "description": "Replaces the complete label sets on multiple web or API operations in one request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_bulk_put_labels_on_operation_request" } } } }, "responses": { "200": { "description": "Bulk replace label(s) on operation(s) in endpoint management response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_operation_with_labels_only" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Bulk replace label(s) on operation(s) in endpoint management response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Labels" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.operations.labels", "x-fern-sdk-method-name": "bulk-update", "x-forge-hidden": true } }, "/zones/{zone_id}/api_gateway/operations/schema_validation": { "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ], "patch": { "operationId": "api-shield-schema-validation-update-multiple-operation-level-settings", "summary": "Update multiple operation-level schema validation settings", "description": "Updates multiple operation-level schema validation settings on the zone. Deprecated; use `/zones/{zone_id}/schema_validation/settings/operations` instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_old_operation_schema_validation_settings_multiple_request" } } } }, "responses": { "200": { "description": "Update multiple operation-level schema validation settings response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_old_operation_schema_validation_settings_multiple_request" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Update multiple operation-level schema validation settings response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Schema Validation 2.0" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "api-security.schema-validation.legacy.settings.operations", "x-fern-sdk-method-name": "bulk-edit", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Schema Validation API](https://developers.cloudflare.com/api/resources/schema_validation/) instead." } }, "/zones/{zone_id}/api_gateway/operations/{operation_id}": { "delete": { "operationId": "api-shield-endpoint-management-delete-an-operation", "summary": "Delete a web or API operation", "description": "Deletes a web or API operation from endpoint management so its feature configuration is no longer tracked.", "responses": { "200": { "description": "Delete an operation response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common" } } } }, "4XX": { "description": "Delete an operation response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Endpoint Management" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.operations", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes the web or API operation." }, "get": { "operationId": "api-shield-endpoint-management-retrieve-information-about-an-operation", "summary": "Get a web or API operation", "description": "Returns a web or API operation, including its schema validation settings and requested feature data.", "parameters": [ { "$ref": "#/components/parameters/api-shield_operation_feature_parameter" }, { "$ref": "#/components/parameters/api-shield_with_schemas_parameter" } ], "responses": { "200": { "description": "Retrieve information about an operation response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_single-operation-response" } } } }, "4XX": { "description": "Retrieve information about an operation response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Endpoint Management" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.operations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "$ref": "#/components/parameters/api-shield_operation_id" } ] }, "/zones/{zone_id}/api_gateway/operations/{operation_id}/labels": { "delete": { "operationId": "api-shield-operations-delete-labels-from-operation", "summary": "Remove labels from a web or API operation", "description": "Removes one or more labels from a web or API operation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_delete_labels_on_operation_request" } } } }, "responses": { "200": { "description": "Remove label(s) on an operation in endpoint management response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_operation_with_labels_only" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Remove label(s) on an operation in endpoint management response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Labels" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.operations.labels", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation removes the selected labels from the web or API operation." }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "$ref": "#/components/parameters/api-shield_operation_id" } ], "post": { "operationId": "api-shield-operations-post-labels-to-operation", "summary": "Attach labels to a web or API operation", "description": "Attaches one or more labels to a web or API operation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_post_labels_on_operation_request" } } } }, "responses": { "200": { "description": "Attach label(s) on an operation in endpoint management response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_operation_with_labels_only" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Attach label(s) on an operation in endpoint management response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Labels" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.operations.labels", "x-fern-sdk-method-name": "create", "x-forge-hidden": true }, "put": { "operationId": "api-shield-operations-put-labels-to-operation", "summary": "Replace labels on a web or API operation", "description": "Replaces the complete label set on a web or API operation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_put_labels_on_operation_request" } } } }, "responses": { "200": { "description": "Replace label(s) on an operation in endpoint management response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_operation_with_labels_only" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Replace label(s) on an operation in endpoint management response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Labels" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.operations.labels", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/api_gateway/operations/{operation_id}/schema_validation": { "get": { "operationId": "api-shield-schema-validation-retrieve-operation-level-settings", "summary": "Retrieve operation-level schema validation settings", "description": "Retrieves operation-level schema validation settings on the zone. Deprecated; use `/zones/{zone_id}/schema_validation/settings/operations/{operation_id}` instead.", "responses": { "200": { "description": "Operation-level schema validation settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_old_operation_schema_validation_settings" } } } }, "4XX": { "description": "Operation-level schema validation settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Schema Validation 2.0" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "api-security.schema-validation.legacy.settings.operations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Schema Validation API](https://developers.cloudflare.com/api/resources/schema_validation/) instead." }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "$ref": "#/components/parameters/api-shield_operation_id" } ], "put": { "operationId": "api-shield-schema-validation-update-operation-level-settings", "summary": "Update operation-level schema validation settings", "description": "Updates operation-level schema validation settings on the zone. Deprecated; use `/zones/{zone_id}/schema_validation/settings/operations/{operation_id}` instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_old_operation_schema_validation_settings_modify_request" } } } }, "responses": { "200": { "description": "Update operation-level schema validation settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_old_operation_schema_validation_settings" } } } }, "4XX": { "description": "Update operation-level schema validation settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Schema Validation 2.0" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "api-security.schema-validation.legacy.settings.operations", "x-fern-sdk-method-name": "update", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Schema Validation API](https://developers.cloudflare.com/api/resources/schema_validation/) instead." } }, "/zones/{zone_id}/api_gateway/schemas": { "get": { "operationId": "api-shield-endpoint-management-retrieve-operations-and-features-as-open-api-schemas", "summary": "Export web and API operations as OpenAPI schemas", "description": "Returns tracked web and API operations and their feature configuration rendered as OpenAPI schemas.", "parameters": [ { "name": "host", "in": "query", "schema": { "description": "Receive schema only for the given host(s).", "type": "array", "items": { "example": "www.example.com", "type": "string" }, "uniqueItems": true } }, { "$ref": "#/components/parameters/api-shield_operation_feature_parameter" }, { "name": "include_schema_kind", "in": "query", "description": "Schema kinds to include in exported OpenAPI schemas.", "schema": { "type": "array", "items": { "enum": [ "learned" ], "type": "string" }, "uniqueItems": true }, "explode": true, "style": "form" } ], "responses": { "200": { "description": "Retrieve operations and features as OpenAPI schemas response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_schema-response-with-thresholds" } } } }, "4XX": { "description": "Retrieve operations and features as OpenAPI schemas response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Endpoint Management" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web-assets.schemas", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ] }, "/zones/{zone_id}/api_gateway/settings/schema_validation": { "get": { "operationId": "api-shield-schema-validation-retrieve-zone-level-settings", "summary": "Retrieve zone level schema validation settings", "description": "Retrieves zone level schema validation settings currently set on the zone. Deprecated; use `/zones/{zone_id}/schema_validation/settings` instead.", "responses": { "200": { "description": "Zone level schema validation settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_old_zone_schema_validation_settings" } } } }, "4XX": { "description": "Zone level schema validation settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Schema Validation 2.0" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "api-security.schema-validation.legacy.settings", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Schema Validation API](https://developers.cloudflare.com/api/resources/schema_validation/) instead." }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ], "patch": { "operationId": "api-shield-schema-validation-patch-zone-level-settings", "summary": "Update zone level schema validation settings", "description": "Updates zone level schema validation settings on the zone. Deprecated; use `/zones/{zone_id}/schema_validation/settings` instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_old_zone_schema_validation_settings_patch" } } } }, "responses": { "200": { "description": "Update zone level schema validation settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_old_zone_schema_validation_settings" } } } }, "4XX": { "description": "Update zone level schema validation settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Schema Validation 2.0" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "api-security.schema-validation.legacy.settings", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Schema Validation API](https://developers.cloudflare.com/api/resources/schema_validation/) instead." }, "put": { "operationId": "api-shield-schema-validation-update-zone-level-settings", "summary": "Update zone level schema validation settings", "description": "Updates zone level schema validation settings on the zone. Deprecated; use `/zones/{zone_id}/schema_validation/settings` instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_old_zone_schema_validation_settings_put" } } } }, "responses": { "200": { "description": "Update zone level schema validation settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_old_zone_schema_validation_settings" } } } }, "4XX": { "description": "Update zone level schema validation settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Schema Validation 2.0" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "api-security.schema-validation.legacy.settings", "x-fern-sdk-method-name": "update", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Schema Validation API](https://developers.cloudflare.com/api/resources/schema_validation/) instead." } }, "/zones/{zone_id}/api_gateway/user_schemas": { "get": { "operationId": "api-shield-schema-validation-retrieve-information-about-all-schemas", "summary": "Retrieve information about all schemas on a zone", "description": "Lists all OpenAPI schemas uploaded to API Shield for the zone, including their validation status and associated operations. Deprecated; use `/zones/{zone_id}/schema_validation/schemas` instead.", "parameters": [ { "$ref": "#/components/parameters/api-shield_page" }, { "$ref": "#/components/parameters/api-shield_per_page" }, { "$ref": "#/components/parameters/api-shield_old_omit_source" }, { "name": "validation_enabled", "in": "query", "schema": { "$ref": "#/components/schemas/api-shield_old_validation_enabled" } } ], "responses": { "200": { "description": "Retrieve information about all schemas on a zone response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_old_public_schema" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Retrieve information about all schemas on a zone response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Schema Validation 2.0" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "api-security.schema-validation.legacy.schemas", "x-fern-sdk-method-name": "list", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Schema Validation API](https://developers.cloudflare.com/api/resources/schema_validation/) instead." }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ], "post": { "operationId": "api-shield-schema-validation-post-schema", "summary": "Upload a legacy schema", "description": "Uploads an OpenAPI schema that defines expected request formats for API endpoints. Deprecated; use `/zones/{zone_id}/schema_validation/schemas` instead.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "description": "Schema file bytes", "type": "string", "format": "binary" }, "kind": { "$ref": "#/components/schemas/api-shield_old_kind" }, "name": { "description": "Name of the schema", "type": "string", "example": "petstore schema" }, "validation_enabled": { "description": "Flag whether schema is enabled for validation.", "type": "string", "enum": [ "true", "false" ] } }, "required": [ "file", "kind" ] } } } }, "responses": { "200": { "description": "Upload a schema response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_old_schema_upload_response" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Upload a schema response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_old_schema_upload_failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Schema Validation 2.0" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "api-security.schema-validation.legacy.schemas", "x-fern-sdk-method-name": "create", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Schema Validation API](https://developers.cloudflare.com/api/resources/schema_validation/) instead." } }, "/zones/{zone_id}/api_gateway/user_schemas/hosts": { "get": { "operationId": "api-shield-schema-validation-retrieve-user-schema-hosts", "summary": "Retrieve schema hosts in a zone", "description": "Lists all unique hosts found in uploaded OpenAPI schemas for the zone. Useful for understanding which domains have schema coverage. Deprecated; use `/zones/{zone_id}/schema_validation/schemas/hosts` instead.", "responses": { "200": { "description": "Retrieve schema hosts in a zone response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_old_response_user_schemas_hosts" } } }, "type": "object" } ] } } } }, "4XX": { "description": "Retrieve schema hosts in a zone response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Schema Validation 2.0" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "api-security.schema-validation.legacy.schemas.hosts", "x-fern-sdk-method-name": "list", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Schema Validation API](https://developers.cloudflare.com/api/resources/schema_validation/) instead." }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "$ref": "#/components/parameters/api-shield_page" }, { "$ref": "#/components/parameters/api-shield_per_page" } ] }, "/zones/{zone_id}/api_gateway/user_schemas/{schema_id}": { "delete": { "operationId": "api-shield-schema-delete-a-schema", "summary": "Delete a schema", "description": "Permanently removes an uploaded OpenAPI schema from API Shield schema validation. Operations using this schema will lose their validation rules. Deprecated; use `/zones/{zone_id}/schema_validation/schemas/{schema_id}` instead.", "responses": { "200": { "description": "Delete a schema response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-single" } } } }, "4XX": { "description": "Delete a schema response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Schema Validation 2.0" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "api-security.schema-validation.legacy.schemas", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation permanently deletes the legacy uploaded schema and removes its validation coverage.", "x-stainless-deprecation-message": "Use [Schema Validation API](https://developers.cloudflare.com/api/resources/schema_validation/) instead." }, "get": { "operationId": "api-shield-schema-validation-retrieve-information-about-specific-schema", "summary": "Retrieve information about a specific schema on a zone", "description": "Gets detailed information about a specific uploaded OpenAPI schema, including its contents and validation configuration. Deprecated; use `/zones/{zone_id}/schema_validation/schemas/{schema_id}` instead.", "parameters": [ { "$ref": "#/components/parameters/api-shield_old_omit_source" } ], "responses": { "200": { "description": "Retrieve information about a specific schema on a zone response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_old_public_schema" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Retrieve information about a specific schema zone response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Schema Validation 2.0" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "api-security.schema-validation.legacy.schemas", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Schema Validation API](https://developers.cloudflare.com/api/resources/schema_validation/) instead." }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "$ref": "#/components/parameters/api-shield_old_schema_id" } ], "patch": { "operationId": "api-shield-schema-validation-enable-validation-for-a-schema", "summary": "Enable validation for a schema", "description": "Activates schema validation for an uploaded OpenAPI schema. Requests to matching endpoints will be validated against the schema definitions. Deprecated; use `/zones/{zone_id}/schema_validation/schemas/{schema_id}` instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "validation_enabled": { "allOf": [ { "$ref": "#/components/schemas/api-shield_old_validation_enabled" }, { "enum": [ true ], "type": "boolean" } ] } } } } } }, "responses": { "200": { "description": "Enable validation for a schema response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_old_public_schema" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Enable validation for a schema response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Schema Validation 2.0" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "api-security.schema-validation.legacy.schemas", "x-fern-sdk-method-name": "set-validation", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Schema Validation API](https://developers.cloudflare.com/api/resources/schema_validation/) instead." } }, "/zones/{zone_id}/api_gateway/user_schemas/{schema_id}/operations": { "get": { "operationId": "api-shield-schema-validation-extract-operations-from-schema", "summary": "Retrieve all operations from a schema", "description": "Retrieves all operations from the schema. Operations that already exist in API Shield Endpoint Management will be returned as full operations. Deprecated; use `/zones/{zone_id}/schema_validation/schemas/{schema_id}/operations` instead.", "parameters": [ { "$ref": "#/components/parameters/api-shield_operation_feature_parameter" }, { "$ref": "#/components/parameters/api-shield_host_parameter" }, { "$ref": "#/components/parameters/api-shield_method_parameter" }, { "$ref": "#/components/parameters/api-shield_endpoint_parameter" }, { "$ref": "#/components/parameters/api-shield_page" }, { "$ref": "#/components/parameters/api-shield_per_page" }, { "name": "operation_status", "in": "query", "description": "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.", "schema": { "type": "string", "example": "new", "enum": [ "new", "existing" ] } } ], "responses": { "200": { "description": "Retrieve all operations from a schema response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/api-shield_operation" }, { "$ref": "#/components/schemas/api-shield_basic_operation" } ] } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Retrieve all operations from a schema response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "API Shield Schema Validation 2.0" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "api-security.schema-validation.legacy.schemas.operations", "x-fern-sdk-method-name": "list", "x-forge-hidden": true, "x-stainless-deprecation-message": "Use [Schema Validation API](https://developers.cloudflare.com/api/resources/schema_validation/) instead." }, "parameters": [ { "$ref": "#/components/parameters/api-shield_old_schema_id" }, { "$ref": "#/components/parameters/api-shield_zone_id" } ] }, "/zones/{zone_id}/argo/smart_routing": { "get": { "operationId": "argo-smart-routing-get-argo-smart-routing-setting", "summary": "Get Argo Smart Routing setting", "description": "Retrieves the value of Argo Smart Routing enablement setting.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/argo-config_identifier" } } ], "responses": { "200": { "description": "Get Argo Smart Routing enablement setting response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/argo-config_api_response_single" } } } }, "4XX": { "description": "Get Argo Smart Routing enablement setting failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/argo-config_api_response_common_failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Argo Smart Routing" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "argo.smart-routing", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "argo-smart-routing-patch-argo-smart-routing-setting", "summary": "Patch Argo Smart Routing setting", "description": "Configures the value of the Argo Smart Routing enablement setting.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/argo-config_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/argo-config_patch" } } } }, "responses": { "200": { "description": "Patch Argo Smart Routing enablement setting response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/argo-config_api_response_single" } } } }, "4XX": { "description": "Patch Argo Smart Routing enablement setting failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/argo-config_api_response_common_failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Argo Smart Routing" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read", "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "argo.smart-routing", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/argo/tiered_caching": { "get": { "operationId": "tiered-caching-get-tiered-caching-setting", "summary": "Get Tiered Caching setting", "description": "Tiered Cache works by dividing Cloudflare's data centers into a hierarchy of lower-tiers and upper-tiers. If content is not cached in lower-tier data centers (generally the ones closest to a visitor), the lower-tier must ask an upper-tier to see if it has the content. If the upper-tier does not have the content, only the upper-tier can ask the origin for content. This practice improves bandwidth efficiency by limiting the number of data centers that can ask the origin for content, which reduces origin load and makes websites more cost-effective to operate. Additionally, Tiered Cache concentrates connections to origin servers so they come from a small number of data centers rather than the full set of network locations. This results in fewer open connections using server resources.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "Get Tiered Caching setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_tiered_cache_response_value" } ] } } } }, "4XX": { "description": "Get Tiered Caching setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Tiered Caching" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "argo.tiered-caching", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "tiered-caching-patch-tiered-caching-setting", "summary": "Patch Tiered Caching setting", "description": "Tiered Cache works by dividing Cloudflare's data centers into a hierarchy of lower-tiers and upper-tiers. If content is not cached in lower-tier data centers (generally the ones closest to a visitor), the lower-tier must ask an upper-tier to see if it has the content. If the upper-tier does not have the content, only the upper-tier can ask the origin for content. This practice improves bandwidth efficiency by limiting the number of data centers that can ask the origin for content, which reduces origin load and makes websites more cost-effective to operate. Additionally, Tiered Cache concentrates connections to origin servers so they come from a small number of data centers rather than the full set of network locations. This results in fewer open connections using server resources.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_patch" } } } }, "responses": { "200": { "description": "Patch Tiered Caching setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_tiered_cache_response_value" } ] } } } }, "4XX": { "description": "Patch Tiered Caching setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Tiered Caching" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "argo.tiered-caching", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/available_plans": { "get": { "operationId": "zone-rate-plan-list-available-plans", "summary": "List Available Plans", "description": "Lists available plans the zone can subscribe to.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "responses": { "200": { "description": "List Available Plans response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/bill-subs-api_available-rate-plan" } } }, "type": "object" } ] } } } }, "4XX": { "description": "List Available Plans response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Rate Plan" ], "x-api-token-group": [ "Billing Write", "Billing Read" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.plans", "x-fern-sdk-method-name": "list" } }, "/zones/{zone_id}/available_plans/{plan_identifier}": { "get": { "operationId": "zone-rate-plan-available-plan-details", "summary": "Available Plan Details", "description": "Details of the available plan that the zone can subscribe to.", "parameters": [ { "name": "plan_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "responses": { "200": { "description": "Available Plan Details response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/bill-subs-api_available-rate-plan" } }, "type": "object" } ] } } } }, "4XX": { "description": "Available Plan Details response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Rate Plan" ], "x-api-token-group": [ "Billing Write", "Billing Read" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.plans", "x-fern-sdk-method-name": "get" } }, "/zones/{zone_id}/available_rate_plans": { "get": { "operationId": "zone-rate-plan-list-available-rate-plans", "summary": "List Available Rate Plans", "description": "Lists all rate plans the zone can subscribe to.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "responses": { "200": { "description": "List Available Rate Plans response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_plan_response_collection" } } } }, "4XX": { "description": "List Available Rate Plans response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Rate Plan" ], "x-api-token-group": [ "Billing Write", "Billing Read" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.rate-plans", "x-fern-sdk-method-name": "get" } }, "/zones/{zone_id}/bot_management": { "get": { "operationId": "bot-management-for-a-zone-get-config", "summary": "Get Zone Bot Management Config", "description": "Retrieve a zone's Bot Management Config", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bot-management_identifier" } } ], "responses": { "200": { "description": "Bot Management config response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bot-management_bot_management_response_body" } } } }, "4XX": { "description": "Bot Management config response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/bot-management_bot_management_response_body" }, { "$ref": "#/components/schemas/bot-management_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Bot Settings" ], "x-api-token-group": [ "Bot Management Write", "Bot Management Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "bot-management", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "bot-management-for-a-zone-update-config", "summary": "Update Zone Bot Management Config", "description": "Updates the Bot Management configuration for a zone.\n\nThis API is used to update:\n- **Bot Fight Mode**\n- **Super Bot Fight Mode**\n- **Bot Management for Enterprise**\n\nSee [Bot Plans](https://developers.cloudflare.com/bots/plans/) for more information on the different plans\n\\\nIf you recently upgraded or downgraded your plan, refer to the following examples to clean up old configurations.\nCopy and paste the example body to remove old zone configurations based on your current plan.\n#### Clean up configuration for Bot Fight Mode plan\n```json\n{\n \"sbfm_likely_automated\": \"allow\",\n \"sbfm_definitely_automated\": \"allow\",\n \"sbfm_verified_bots\": \"allow\",\n \"sbfm_static_resource_protection\": false,\n \"optimize_wordpress\": false,\n \"suppress_session_score\": false\n}\n```\n#### Clean up configuration for SBFM Pro plan\n```json\n{\n \"sbfm_likely_automated\": \"allow\",\n \"fight_mode\": false\n}\n```\n#### Clean up configuration for SBFM Biz plan\n```json\n{\n \"fight_mode\": false\n}\n```\n#### Clean up configuration for BM Enterprise Subscription plan\nIt is strongly recommended that you ensure you have [custom rules](https://developers.cloudflare.com/waf/custom-rules/) in place to protect your zone before disabling the SBFM rules. Without these protections, your zone is vulnerable to attacks.\n```json\n{\n \"sbfm_likely_automated\": \"allow\",\n \"sbfm_definitely_automated\": \"allow\",\n \"sbfm_verified_bots\": \"allow\",\n \"sbfm_static_resource_protection\": false,\n \"optimize_wordpress\": false,\n \"fight_mode\": false\n}\n```\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bot-management_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bot-management_config_single" } } } }, "responses": { "200": { "description": "Update Bot Management response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bot-management_bot_management_response_body" } } } }, "4XX": { "description": "Update Bot Management response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/bot-management_bot_management_response_body" }, { "$ref": "#/components/schemas/bot-management_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Bot Settings" ], "x-api-token-group": [ "Bot Management Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "bot-management", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/bot_management/feedback": { "get": { "operationId": "bot-management-zone-feedback-list", "summary": "List zone feedback reports", "description": "Returns all feedback reports previously submitted for the specified zone. Feedback reports help improve detection by sharing samples of traffic that were misclassified as bots or humans.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bot-management_identifier" } } ], "responses": { "200": { "description": "List of feedback reports", "content": { "application/json": { "examples": { "sample": { "summary": "Example list response", "value": [ { "created_at": "2025-10-01T12:00:00Z", "description": "Legitimate checkout traffic was blocked as bots", "expression": "(http.host eq 'shop.example.com' and http.request.uri.path starts_with '/checkout') and cf.bot_management.score lt 5", "first_request_seen_at": "2025-09-30T08:00:00Z", "last_request_seen_at": "2025-09-30T09:00:00Z", "requests": 1200, "requests_by_attribute": { "topIPs": [ { "metric": "203.0.113.10", "requests": 180 }, { "metric": "203.0.113.11", "requests": 150 } ], "topPaths": [ { "metric": "/checkout", "requests": 1000 } ] }, "requests_by_score": { "1": 200, "2": 300, "3": 400, "4": 300 }, "requests_by_score_src": { "heuristics": 200, "machine_learning": 1000 }, "subtype": "Spamming", "type": "false_positive" } ] } }, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/bot-management_feedback_report" } } } } }, "4XX": { "description": "Feedback list failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bot-management_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Feedback" ], "x-api-token-group": [ "Bot Management Feedback Report Write", "Bot Management Feedback Report Read", "Bot Management Write", "Bot Management Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "bot-management.feedback", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "bot-management-zone-feedback-create", "summary": "Submit a feedback report", "description": "Submit a feedback report for the specified zone. Use `type` to indicate whether the report is a false positive (good traffic flagged as bot) or a false negative (bot traffic missed). Furthermore, you can also use `expression` as a wirefilter to identify the affected traffic sample.\n\nSee more accepted API fields and expression types at https://developers.cloudflare.com/bots/concepts/feedback-loop/#api-fields and https://developers.cloudflare.com/bots/concepts/feedback-loop/#expression-fields, respectively.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bot-management_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "false_negative_example": { "summary": "False negative example", "value": { "description": "Automated scraping missed by detections", "expression": "http.host eq 'www.example.com' and http.request.uri.path starts_with '/products' and cf.bot_management.score gt 25", "first_request_seen_at": "2025-09-29T00:00:00Z", "last_request_seen_at": "2025-09-29T06:00:00Z", "requests": 2000, "requests_by_attribute": { "topIPs": [ { "metric": "203.0.113.55", "requests": 400 } ], "topJA3Hashes": [ { "metric": "ab12cd34ef56...", "requests": 900 } ] }, "requests_by_score": { "30": 800, "40": 700, "50": 500 }, "requests_by_score_src": { "heuristics": 200, "ml": 1800 }, "subtype": "Scraping", "type": "false_negative" } }, "false_positive_example": { "summary": "False positive example", "value": { "description": "Legitimate users flagged as bots during login", "expression": "http.host eq 'app.example.com' and http.request.uri.path starts_with '/login' and cf.bot_management.score lt 5", "first_request_seen_at": "2025-09-30T10:00:00Z", "last_request_seen_at": "2025-09-30T11:00:00Z", "requests": 500, "requests_by_attribute": { "topIPs": [ { "metric": "198.51.100.23", "requests": 60 } ], "topUserAgents": [ { "metric": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36", "requests": 220 } ] }, "requests_by_score": { "1": 120, "2": 150, "3": 130, "4": 100 }, "requests_by_score_src": { "heuristics": 50, "ml": 450 }, "subtype": "Login Abuse", "type": "false_positive" } } }, "schema": { "$ref": "#/components/schemas/bot-management_feedback_report" } } } }, "responses": { "201": { "description": "Feedback report created" }, "4XX": { "description": "Feedback creation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bot-management_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Feedback" ], "x-api-token-group": [ "Bot Management Feedback Report Write", "Bot Management Feedback Report Read", "Bot Management Write", "Bot Management Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "bot-management.feedback", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/cache/cache_reserve": { "get": { "operationId": "zone-cache-settings-get-cache-reserve-setting", "summary": "Get Cache Reserve setting", "description": "Increase cache lifetimes by automatically storing all cacheable files into Cloudflare's persistent object storage buckets. Requires Cache Reserve subscription. Note: using Tiered Cache with Cache Reserve is highly recommended to reduce Reserve operations costs. See the [developer docs](https://developers.cloudflare.com/cache/about/cache-reserve) for more information.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "Get Cache Reserve setting response.", "content": { "application/json": { "examples": { "off": { "$ref": "#/components/examples/cache-rules_cache_reserve_off" } }, "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_cache_reserve_response_value" } ] } } } }, "4XX": { "description": "Get Cache Reserve setting response failure.", "content": { "application/json": { "examples": { "Error": { "$ref": "#/components/examples/cache-rules_dummy_error_response" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Cache Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read", "Zone Read", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "cache.settings.reserve", "x-fern-sdk-method-name": "get", "x-forge-hidden": false }, "patch": { "operationId": "zone-cache-settings-change-cache-reserve-setting", "summary": "Change Cache Reserve setting", "description": "Increase cache lifetimes by automatically storing all cacheable files into Cloudflare's persistent object storage buckets. Requires Cache Reserve subscription. Note: using Tiered Cache with Cache Reserve is highly recommended to reduce Reserve operations costs. See the [developer docs](https://developers.cloudflare.com/cache/about/cache-reserve) for more information.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/cache-rules_cache_reserve_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Change Cache Reserve setting response.", "content": { "application/json": { "examples": { "on": { "$ref": "#/components/examples/cache-rules_cache_reserve_on" } }, "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_cache_reserve_response_value" } ] } } } }, "4XX": { "description": "Change Cache Reserve setting response failure.", "content": { "application/json": { "examples": { "Denied": { "$ref": "#/components/examples/cache-rules_cache_reserve_denied_clearing" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Cache Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "cache.settings.reserve", "x-fern-sdk-method-name": "edit", "x-forge-hidden": false } }, "/zones/{zone_id}/cache/cache_reserve_clear": { "get": { "operationId": "zone-cache-settings-get-cache-reserve-clear", "summary": "Get Cache Reserve Clear", "description": "You can use Cache Reserve Clear to clear your Cache Reserve, but you must first disable Cache Reserve. In most cases, this will be accomplished within 24 hours. You cannot re-enable Cache Reserve while this process is ongoing. Keep in mind that you cannot undo or cancel this operation.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "Get Cache Reserve Clear response.", "content": { "application/json": { "examples": { "Completed": { "$ref": "#/components/examples/cache-rules_cache_reserve_clear_completed" }, "In-progress": { "$ref": "#/components/examples/cache-rules_cache_reserve_clear_in_progress" } }, "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "$ref": "#/components/schemas/cache-rules_cache_reserve_clear_response_value" } ] } } } }, "4XX": { "description": "Get Cache Reserve Clear failure response.", "content": { "application/json": { "examples": { "Not found": { "$ref": "#/components/examples/cache-rules_cache_reserve_clear_not_found" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Cache Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read", "Zone Read", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "cache.settings.reserve", "x-fern-sdk-method-name": "status", "x-forge-hidden": false }, "post": { "operationId": "zone-cache-settings-start-cache-reserve-clear", "summary": "Start Cache Reserve Clear", "description": "You can use Cache Reserve Clear to clear your Cache Reserve, but you must first disable Cache Reserve. In most cases, this will be accomplished within 24 hours. You cannot re-enable Cache Reserve while this process is ongoing. Keep in mind that you cannot undo or cancel this operation.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "description": "The request body is currently not used.", "required": true, "content": { "application/json": { "example": "{}" } } }, "responses": { "200": { "description": "Start Cache Reserve Clear response.", "content": { "application/json": { "examples": { "In-progress": { "$ref": "#/components/examples/cache-rules_cache_reserve_clear_in_progress" } }, "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "$ref": "#/components/schemas/cache-rules_cache_reserve_clear_response_value" } ] } } } }, "4XX": { "description": "Start Cache Reserve Clear failure response.", "content": { "application/json": { "examples": { "Rejected": { "$ref": "#/components/examples/cache-rules_cache_reserve_clear_rejected_cr_on" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Cache Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "cache.settings.reserve", "x-fern-sdk-method-name": "clear", "x-forge-hidden": false, "x-forge-require-confirmation": "This operation permanently clears Cache Reserve for this zone and cannot be undone." } }, "/zones/{zone_id}/cache/origin_cloud_regions": { "get": { "operationId": "origin-cloud-regions-list", "summary": "List origin cloud region mappings", "description": "Returns all IP-to-cloud-region mappings configured for the zone. Each mapping tells Cloudflare which cloud vendor and region hosts the origin at that IP, enabling the edge to route via the nearest Tiered Cache upper-tier co-located with that cloud provider. Returns an empty array when no mappings exist.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "List origin cloud region mappings response.", "content": { "application/json": { "examples": { "empty": { "$ref": "#/components/examples/cache-rules_origin_cloud_regions_empty" }, "two_mappings": { "$ref": "#/components/examples/cache-rules_origin_cloud_regions_list" } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_origin_cloud_regions_list_result" } }, "type": "object" } ] } } } }, "4XX": { "description": "List origin cloud region mappings failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Cloud Regions" ], "x-cfDeprecation": { "description": "Use the v2 endpoints under `/zones/{zone_id}/origin/cloud_regions` instead. The v2 API uses idempotent PUT semantics for create+update, provides a flat response shape, and is the supported path for Terraform and SDK clients. The v1 endpoints under `/zones/{zone_id}/cache/origin_cloud_regions` will be removed on 2026-10-01.", "display": true, "eol": "2026-10-01T00:00:00Z", "id": "opcr_v1_deprecation" }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } }, "patch": { "operationId": "origin-cloud-regions-upsert", "summary": "Create or update an origin cloud region mapping", "description": "Adds or updates a single IP-to-cloud-region mapping for the zone. Unlike POST, this operation is idempotent — if a mapping for the IP already exists it is overwritten. Returns the complete updated list of all mappings for the zone. Returns 403 (code 1164) when the zone has reached the limit of 3,500 IP mappings.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "gcp": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_request_gcp" } }, "schema": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_request" } } } }, "responses": { "200": { "description": "Create or update origin cloud region mapping response.", "content": { "application/json": { "examples": { "patched": { "$ref": "#/components/examples/cache-rules_origin_cloud_regions_list" } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_origin_cloud_regions_list_result" } }, "type": "object" } ] } } } }, "4XX": { "description": "Create or update origin cloud region mapping failure.", "content": { "application/json": { "examples": { "invalid_vendor_region": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_invalid_vendor_region" }, "too_many_mappings": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_too_many_mappings" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Cloud Regions" ], "x-cfDeprecation": { "description": "Use the v2 endpoints under `/zones/{zone_id}/origin/cloud_regions` instead. The v2 API uses idempotent PUT semantics for create+update, provides a flat response shape, and is the supported path for Terraform and SDK clients. The v1 endpoints under `/zones/{zone_id}/cache/origin_cloud_regions` will be removed on 2026-10-01.", "display": true, "eol": "2026-10-01T00:00:00Z", "id": "opcr_v1_deprecation" }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } }, "post": { "operationId": "origin-cloud-regions-create", "summary": "Create an origin cloud region mapping", "description": "Adds a single IP-to-cloud-region mapping for the zone. The IP must be a valid IPv4 or IPv6 address and is normalized to canonical form before storage (RFC 5952 for IPv6). Returns 400 (code 1145) if a mapping for that IP already exists — use PATCH to update an existing entry. The vendor and region are validated against the list from `GET /zones/{zone_id}/cache/origin_cloud_regions/supported_regions`.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "aws": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_request_aws" } }, "schema": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_request" } } } }, "responses": { "200": { "description": "Create origin cloud region mapping response.", "content": { "application/json": { "examples": { "created": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_single" } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_single_result" } }, "type": "object" } ] } } } }, "4XX": { "description": "Create origin cloud region mapping failure.", "content": { "application/json": { "examples": { "already_exists": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_already_exists" }, "invalid_ip": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_invalid_ip" }, "invalid_vendor_region": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_invalid_vendor_region" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Cloud Regions" ], "x-cfDeprecation": { "description": "Use the v2 endpoints under `/zones/{zone_id}/origin/cloud_regions` instead. The v2 API uses idempotent PUT semantics for create+update, provides a flat response shape, and is the supported path for Terraform and SDK clients. The v1 endpoints under `/zones/{zone_id}/cache/origin_cloud_regions` will be removed on 2026-10-01.", "display": true, "eol": "2026-10-01T00:00:00Z", "id": "opcr_v1_deprecation" }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } } }, "/zones/{zone_id}/cache/origin_cloud_regions/batch": { "delete": { "operationId": "origin-cloud-regions-batch-delete", "summary": "Batch delete origin cloud region mappings", "description": "Removes up to 100 IP-to-cloud-region mappings in a single request. Each IP is validated independently — successfully deleted items are returned in the `succeeded` array and IPs that could not be found or are invalid are returned in the `failed` array.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "batch_delete": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_batch_delete_request" } }, "schema": { "type": "array", "items": { "description": "Origin IP address to delete.", "example": "192.0.2.1", "type": "string" }, "maxItems": 100 } } } }, "responses": { "200": { "description": "Batch delete origin cloud region mappings successful.", "content": { "application/json": { "examples": { "batch_deleted": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_batch_delete_response" } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_batch_result" } }, "type": "object" } ] } } } }, "4XX": { "description": "Batch delete origin cloud region mappings failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } }, "5XX": { "description": "Batch delete origin cloud region mappings internal error.", "content": { "application/json": { "examples": { "internal_error": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_batch_delete_internal_error" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Cloud Regions" ], "x-cfDeprecation": { "description": "Use the v2 endpoints under `/zones/{zone_id}/origin/cloud_regions` instead. The v2 API uses idempotent PUT semantics for create+update, provides a flat response shape, and is the supported path for Terraform and SDK clients. The v1 endpoints under `/zones/{zone_id}/cache/origin_cloud_regions` will be removed on 2026-10-01.", "display": true, "eol": "2026-10-01T00:00:00Z", "id": "opcr_v1_deprecation" }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } }, "patch": { "operationId": "origin-cloud-regions-batch-upsert", "summary": "Batch create or update origin cloud region mappings", "description": "Adds or updates up to 100 IP-to-cloud-region mappings in a single request. Each item is validated independently — valid items are applied and invalid items are returned in the `failed` array. The vendor and region for every item are validated against the list from `GET /zones/{zone_id}/cache/origin_cloud_regions/supported_regions`.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "batch_patch": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_batch_patch_request" } }, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_request" }, "maxItems": 100 } } } }, "responses": { "200": { "description": "Batch create or update origin cloud region mappings successful.", "content": { "application/json": { "examples": { "batch_patched": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_batch_patch_response" } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_batch_result" } }, "type": "object" } ] } } } }, "4XX": { "description": "Batch create or update origin cloud region mappings failure.", "content": { "application/json": { "examples": { "too_many_mappings": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_too_many_mappings" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } }, "5XX": { "description": "Batch create or update origin cloud region mappings internal error.", "content": { "application/json": { "examples": { "internal_error": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_batch_patch_internal_error" }, "region_validation_error": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_region_validation_error" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Cloud Regions" ], "x-cfDeprecation": { "description": "Use the v2 endpoints under `/zones/{zone_id}/origin/cloud_regions` instead. The v2 API uses idempotent PUT semantics for create+update, provides a flat response shape, and is the supported path for Terraform and SDK clients. The v1 endpoints under `/zones/{zone_id}/cache/origin_cloud_regions` will be removed on 2026-10-01.", "display": true, "eol": "2026-10-01T00:00:00Z", "id": "opcr_v1_deprecation" }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } } }, "/zones/{zone_id}/cache/origin_cloud_regions/supported_regions": { "get": { "operationId": "origin-cloud-regions-supported-regions", "summary": "List supported cloud vendors and regions", "description": "Returns the cloud vendors and regions that are valid values for origin cloud region mappings. Each region includes the Tiered Cache upper-tier colocation codes that will be used for cache routing when a mapping targeting that region is active. Requires the zone to have Tiered Cache enabled.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "List supported cloud vendors and regions response.", "content": { "application/json": { "examples": { "vendors": { "$ref": "#/components/examples/cache-rules_supported_cloud_regions" } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_supported_cloud_regions_result" } }, "type": "object" } ] } } } }, "4XX": { "description": "List supported cloud vendors and regions failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Cloud Regions" ], "x-cfDeprecation": { "description": "Use the v2 endpoints under `/zones/{zone_id}/origin/cloud_regions` instead. The v2 API uses idempotent PUT semantics for create+update, provides a flat response shape, and is the supported path for Terraform and SDK clients. The v1 endpoints under `/zones/{zone_id}/cache/origin_cloud_regions` will be removed on 2026-10-01.", "display": true, "eol": "2026-10-01T00:00:00Z", "id": "opcr_v1_deprecation" }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } } }, "/zones/{zone_id}/cache/origin_cloud_regions/{origin_ip}": { "delete": { "operationId": "origin-cloud-regions-delete", "summary": "Delete an origin cloud region mapping", "description": "Removes the cloud region mapping for a single origin IP address. The IP path parameter is normalized before lookup. Returns the deleted entry on success. Returns 404 (code 1163) if no mapping exists for the specified IP. When the last mapping for the zone is removed the underlying rule record is also deleted.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } }, { "name": "origin_ip", "in": "path", "description": "Origin IP address whose mapping should be deleted.", "required": true, "schema": { "type": "string", "example": "192.0.2.1" } } ], "responses": { "200": { "description": "Delete origin cloud region mapping response.", "content": { "application/json": { "examples": { "deleted": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_single" } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_single_result" } }, "type": "object" } ] } } } }, "4XX": { "description": "Delete origin cloud region mapping failure.", "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_not_found" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Cloud Regions" ], "x-cfDeprecation": { "description": "Use the v2 endpoints under `/zones/{zone_id}/origin/cloud_regions` instead. The v2 API uses idempotent PUT semantics for create+update, provides a flat response shape, and is the supported path for Terraform and SDK clients. The v1 endpoints under `/zones/{zone_id}/cache/origin_cloud_regions` will be removed on 2026-10-01.", "display": true, "eol": "2026-10-01T00:00:00Z", "id": "opcr_v1_deprecation" }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } }, "get": { "operationId": "origin-cloud-regions-get", "summary": "Get an origin cloud region mapping", "description": "Returns the cloud region mapping for a single origin IP address. The IP path parameter is normalized before lookup (RFC 5952 for IPv6). Returns 404 (code 1142) if the zone has no mappings or if the specified IP has no mapping.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } }, { "name": "origin_ip", "in": "path", "description": "Origin IP address to look up. IPv4 and IPv6 are supported.", "required": true, "schema": { "type": "string", "example": "192.0.2.1" } } ], "responses": { "200": { "description": "Get origin cloud region mapping response.", "content": { "application/json": { "examples": { "found": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_single" } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_single_result" } }, "type": "object" } ] } } } }, "4XX": { "description": "Get origin cloud region mapping failure.", "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_not_found" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Cloud Regions" ], "x-cfDeprecation": { "description": "Use the v2 endpoints under `/zones/{zone_id}/origin/cloud_regions` instead. The v2 API uses idempotent PUT semantics for create+update, provides a flat response shape, and is the supported path for Terraform and SDK clients. The v1 endpoints under `/zones/{zone_id}/cache/origin_cloud_regions` will be removed on 2026-10-01.", "display": true, "eol": "2026-10-01T00:00:00Z", "id": "opcr_v1_deprecation" }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } } }, "/zones/{zone_id}/cache/origin_post_quantum_encryption": { "get": { "operationId": "zone-cache-settings-get-origin-post-quantum-encryption-setting", "summary": "Get Origin Post-Quantum Encryption setting", "description": "Instructs Cloudflare to use Post-Quantum (PQ) key agreement algorithms when connecting to your origin. Preferred instructs Cloudflare to opportunistically send a Post-Quantum keyshare in the first message to the origin (for fastest connections when the origin supports and prefers PQ), supported means that PQ algorithms are advertised but only used when requested by the origin, and off means that PQ algorithms are not advertised.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "Get Origin Post-Quantum Encryption setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_origin_post_quantum_encryption_response_value" } ] } } } }, "4XX": { "description": "Get Origin Post-Quantum Encryption setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Post-Quantum" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read", "Zone Read", "Zone Write" ], "x-cfDeprecation": { "description": "Origin post-quantum encryption selection is now handled automatically by Auto-Origin TLS KEX (`/zones/{zone_id}/settings/auto_origin_tls_kex`) combined with Origin TLS Compliance Modes (`/zones/{zone_id}/settings/origin_tls_compliance_modes`). As that rollout proceeds, the manual `origin_post_quantum_encryption` setting becomes ineffective and the endpoint will be removed on 2026-07-19.", "display": true, "eol": "2026-07-19T00:00:00Z", "id": "origin_pqe_deprecation" }, "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-post-quantum-encryption", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "zone-cache-settings-change-origin-post-quantum-encryption-setting", "summary": "Change Origin Post-Quantum Encryption setting", "description": "Instructs Cloudflare to use Post-Quantum (PQ) key agreement algorithms when connecting to your origin. Preferred instructs Cloudflare to opportunistically send a Post-Quantum keyshare in the first message to the origin (for fastest connections when the origin supports and prefers PQ), supported means that PQ algorithms are advertised but only used when requested by the origin, and off means that PQ algorithms are not advertised.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/cache-rules_origin_post_quantum_encryption_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Change Origin Post-Quantum Encryption setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_origin_post_quantum_encryption_response_value" } ] } } } }, "4XX": { "description": "Change Origin Post-Quantum Encryption setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Post-Quantum" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write" ], "x-cfDeprecation": { "description": "Origin post-quantum encryption selection is now handled automatically by Auto-Origin TLS KEX (`/zones/{zone_id}/settings/auto_origin_tls_kex`) combined with Origin TLS Compliance Modes (`/zones/{zone_id}/settings/origin_tls_compliance_modes`). As that rollout proceeds, the manual `origin_post_quantum_encryption` setting becomes ineffective and the endpoint will be removed on 2026-07-19.", "display": true, "eol": "2026-07-19T00:00:00Z", "id": "origin_pqe_deprecation" }, "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-post-quantum-encryption", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/cache/regional_tiered_cache": { "get": { "operationId": "zone-cache-settings-get-regional-tiered-cache-setting", "summary": "Get Regional Tiered Cache setting", "description": "Instructs Cloudflare to check a regional hub data center on the way to your upper tier. This can help improve performance for smart and custom tiered cache topologies.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "Get Regional Tiered Cache setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_regional_tiered_cache_response_value" } ] } } } }, "4XX": { "description": "Get Regional Tiered Cache setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Cache Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read", "Zone Read", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "cache.settings.regional-tiered-cache", "x-fern-sdk-method-name": "get", "x-forge-hidden": false }, "patch": { "operationId": "zone-cache-settings-change-regional-tiered-cache-setting", "summary": "Change Regional Tiered Cache setting", "description": "Instructs Cloudflare to check a regional hub data center on the way to your upper tier. This can help improve performance for smart and custom tiered cache topologies.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/cache-rules_regional_tiered_cache_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Change Regional Tiered Cache setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_regional_tiered_cache_response_value" } ] } } } }, "4XX": { "description": "Change Regional Tiered Cache setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Cache Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "cache.settings.regional-tiered-cache", "x-fern-sdk-method-name": "edit", "x-forge-hidden": false } }, "/zones/{zone_id}/cache/tiered_cache_smart_topology_enable": { "delete": { "operationId": "smart-tiered-cache-delete-smart-tiered-cache-setting", "summary": "Delete Smart Tiered Cache setting", "description": "Smart Tiered Cache dynamically selects the single closest upper tier for each of your website’s origins with no configuration required, using our in-house performance and routing data. Cloudflare collects latency data for each request to an origin, and uses the latency data to determine how well any upper-tier data center is connected with an origin. As a result, Cloudflare can select the data center with the lowest latency to be the upper-tier for an origin.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "Delete Smart Tiered Cache setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_delete_response_single" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_smart_tiered_cache" } }, "type": "object" } ] } } } }, "4XX": { "description": "Delete Smart Tiered Cache setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Smart Tiered Cache" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "cache.settings.smart-tiered-cache", "x-fern-sdk-method-name": "delete", "x-forge-hidden": false }, "get": { "operationId": "smart-tiered-cache-get-smart-tiered-cache-setting", "summary": "Get Smart Tiered Cache setting", "description": "Smart Tiered Cache dynamically selects the single closest upper tier for each of your website’s origins with no configuration required, using our in-house performance and routing data. Cloudflare collects latency data for each request to an origin, and uses the latency data to determine how well any upper-tier data center is connected with an origin. As a result, Cloudflare can select the data center with the lowest latency to be the upper-tier for an origin.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "Get Smart Tiered Cache setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_smart_tiered_cache_response_value" } ] } } } }, "4XX": { "description": "Get Smart Tiered Cache setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Smart Tiered Cache" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read", "Zone Read", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "cache.settings.smart-tiered-cache", "x-fern-sdk-method-name": "get", "x-forge-hidden": false }, "patch": { "operationId": "smart-tiered-cache-patch-smart-tiered-cache-setting", "summary": "Patch Smart Tiered Cache setting", "description": "Smart Tiered Cache dynamically selects the single closest upper tier for each of your website’s origins with no configuration required, using our in-house performance and routing data. Cloudflare collects latency data for each request to an origin, and uses the latency data to determine how well any upper-tier data center is connected with an origin. As a result, Cloudflare can select the data center with the lowest latency to be the upper-tier for an origin.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_smart_tiered_cache_patch" } } } }, "responses": { "200": { "description": "Patch Smart Tiered Cache setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_smart_tiered_cache_response_value" } ] } } } }, "4XX": { "description": "Patch Smart Tiered Cache setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Smart Tiered Cache" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read", "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "cache.settings.smart-tiered-cache", "x-fern-sdk-method-name": "edit", "x-forge-hidden": false }, "post": { "operationId": "smart-tiered-cache-create-smart-tiered-cache-setting", "summary": "Create Smart Tiered Cache setting", "description": "Smart Tiered Cache dynamically selects the single closest upper tier for each of your website's origins with no configuration required, using our in-house performance and routing data. Cloudflare collects latency data for each request to an origin, and uses the latency data to determine how well any upper-tier data center is connected with an origin. As a result, Cloudflare can select the data center with the lowest latency to be the upper-tier for an origin.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_smart_tiered_cache_patch" } } } }, "responses": { "200": { "description": "Create Smart Tiered Cache setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_smart_tiered_cache_response_value" } ] } } } }, "4XX": { "description": "Create Smart Tiered Cache setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Smart Tiered Cache" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read", "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } } }, "/zones/{zone_id}/cache/variants": { "delete": { "operationId": "zone-cache-settings-delete-variants-setting", "summary": "Delete variants setting", "description": "Variant support enables caching variants of images with certain file extensions in addition to the original. This only applies when the origin server sends the 'Vary: Accept' response header. If the origin server sends 'Vary: Accept' but does not serve the variant requested, the response will not be cached. This will be indicated with BYPASS cache status in the response headers.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "Delete variants setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_delete_response_single" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_variants" } }, "type": "object" } ] } } } }, "4XX": { "description": "Delete variants setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Cache Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "cache.settings.variants", "x-fern-sdk-method-name": "delete", "x-forge-hidden": false }, "get": { "operationId": "zone-cache-settings-get-variants-setting", "summary": "Get variants setting", "description": "Variant support enables caching variants of images with certain file extensions in addition to the original. This only applies when the origin server sends the 'Vary: Accept' response header. If the origin server sends 'Vary: Accept' but does not serve the variant requested, the response will not be cached. This will be indicated with BYPASS cache status in the response headers.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "Get variants setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_variants_response_value" } ] } } } }, "4XX": { "description": "Get variants setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Cache Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read", "Zone Read", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "cache.settings.variants", "x-fern-sdk-method-name": "get", "x-forge-hidden": false }, "patch": { "operationId": "zone-cache-settings-change-variants-setting", "summary": "Change variants setting", "description": "Variant support enables caching variants of images with certain file extensions in addition to the original. This only applies when the origin server sends the 'Vary: Accept' response header. If the origin server sends 'Vary: Accept' but does not serve the variant requested, the response will not be cached. This will be indicated with BYPASS cache status in the response headers.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/cache-rules_variants_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Change variants setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_variants_response_value" } ] } } } }, "4XX": { "description": "Change variants setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Cache Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "cache.settings.variants", "x-fern-sdk-method-name": "edit", "x-forge-hidden": false } }, "/zones/{zone_id}/certificate_authorities/hostname_associations": { "get": { "operationId": "client-certificate-for-a-zone-list-hostname-associations", "summary": "List Hostname Associations", "description": "List Hostname Associations.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "mtls_certificate_id", "in": "query", "schema": { "description": "The UUID to match against for a certificate that was uploaded to the mTLS Certificate Management endpoint. If no mtls_certificate_id is given, the results will be the hostnames associated to your active Cloudflare Managed CA.", "type": "string", "example": "b2134436-2555-4acf-be5b-26c48136575e", "maxLength": 36, "minLength": 36 } } ], "responses": { "200": { "description": "List Hostname Associations Response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname_associations_response" } } } }, "4XX": { "description": "List Hostname Associations Response Failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "API Shield Client Certificates for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "certificate-authorities.hostname-associations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "client-certificate-for-a-zone-put-hostname-associations", "summary": "Replace Hostname Associations", "description": "Replace Hostname Associations.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname_association" } } } }, "responses": { "200": { "description": "Replace Hostname Associations Response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname_associations_response" } } } }, "4XX": { "description": "Replace Hostname Associations Response Failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "API Shield Client Certificates for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "certificate-authorities.hostname-associations", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/client_certificates": { "get": { "operationId": "client-certificate-for-a-zone-list-client-certificates", "summary": "List Client Certificates", "description": "List all of your Zone's API Shield mTLS Client Certificates by Status and/or using Pagination.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "status", "in": "query", "schema": { "description": "Client Certitifcate Status to filter results by.", "type": "string", "example": "all", "enum": [ "all", "active", "pending_reactivation", "pending_revocation", "revoked" ] } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of records per page.", "type": "number", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "limit", "in": "query", "schema": { "description": "Limit to the number of records returned.", "type": "integer", "example": 10 } }, { "name": "offset", "in": "query", "schema": { "description": "Offset the results.", "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "List Client Certificates Response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_client_certificate_response_collection" } } } }, "4XX": { "description": "List Client Certificates Response Failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "API Shield Client Certificates for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-certificates", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "client-certificate-for-a-zone-create-client-certificate", "summary": "Create Client Certificate", "description": "Create a new API Shield mTLS Client Certificate.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csr": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_csr-2" }, "validity_days": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_validity_days-2" } }, "required": [ "csr", "validity_days" ] } } } }, "responses": { "200": { "description": "Create Client Certificate Response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_client_certificate_response_single" } } } }, "4XX": { "description": "Create Client Certificate Response Failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_client_certificate_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "API Shield Client Certificates for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-certificates", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/client_certificates/{client_certificate_id}": { "delete": { "operationId": "client-certificate-for-a-zone-delete-client-certificate", "summary": "Revoke Client Certificate", "description": "Set a API Shield mTLS Client Certificate to pending_revocation status for processing to revoked status.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "client_certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Revoke Client Certificate Response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_client_certificate_response_single" } } } }, "4XX": { "description": "Revoke Client Certificate Response Failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "API Shield Client Certificates for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-certificates", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "client-certificate-for-a-zone-client-certificate-details", "summary": "Client Certificate Details", "description": "Get Details for a single mTLS API Shield Client Certificate.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "client_certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Client Certificate Details Response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_client_certificate_response_single" } } } }, "4XX": { "description": "Client Certificate Details Response Failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "API Shield Client Certificates for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-certificates", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "client-certificate-for-a-zone-edit-client-certificate", "summary": "Reactivate Client Certificate", "description": "If a API Shield mTLS Client Certificate is in a pending_revocation state, you may reactivate it with this endpoint.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "client_certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reactivate": { "type": "boolean", "example": true } } } } } }, "responses": { "200": { "description": "Reactivate Client Certificate Response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_client_certificate_response_single" } } } }, "4XX": { "description": "Reactivate Client Certificate Response Failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "API Shield Client Certificates for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-certificates", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/cloud_connector/rules": { "get": { "operationId": "zone-cloud-connector-rules", "summary": "Rules", "description": "Retrieves the Cloud Connector rules configured for a zone. Rules define how traffic is routed to cloud services.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cloud-connector_identifier" } } ], "responses": { "200": { "description": "Cloud Connector rules response", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cloud-connector_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cloud-connector_rules" } }, "type": "object" } ] } } } }, "4XX": { "description": "Cloud Connector response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/cloud-connector_api-response-common-failure" } ] } } } }, "5XX": { "description": "Cloud Connector response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/cloud-connector_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Zone Cloud Connector Rules GET" ], "x-api-token-group": [ "Cloud Connector Read", "Cloud Connector Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "cloud-connector.rules", "x-fern-sdk-method-name": "list" }, "put": { "operationId": "zone-cloud-conenctor-rules-put", "summary": "Put Rules", "description": "Updates Cloud Connector rules for a zone, replacing the existing rule configuration.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cloud-connector_identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/cloud-connector_rule" } } } } }, "responses": { "200": { "description": "Cloud Connector rules response", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cloud-connector_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cloud-connector_rules" } }, "type": "object" } ] } } } }, "4XX": { "description": "Cloud Connector response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/cloud-connector_api-response-common-failure" } ] } } } }, "5XX": { "description": "Cloud Connector response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/cloud-connector_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Zone Cloud Connector Rules PUT" ], "x-api-token-group": [ "Cloud Connector Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "cloud-connector.rules", "x-fern-sdk-method-name": "update" } }, "/zones/{zone_id}/content-upload-scan/disable": { "post": { "operationId": "waf-content-scanning-disable", "summary": "Disable Content Scanning for a zone.", "description": "Disable Content Scanning for a zone. The `cf.waf.content_scan.*` fields are no longer populated, so rules that reference them stop matching.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } } ], "responses": { "200": { "description": "Disable Content Scanning response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-2" } } } }, "4XX": { "description": "Disable Content Scanning failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure-2" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Content Scanning" ], "x-api-token-group": [ "Zone WAF Write", "Account WAF Write" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "content-scan", "x-fern-sdk-method-name": "disable" } }, "/zones/{zone_id}/content-upload-scan/enable": { "post": { "operationId": "waf-content-scanning-enable", "summary": "Enable Content Scanning for a zone.", "description": "Enable Content Scanning for a zone, so that Cloudflare inspects content objects uploaded to the zone and checks them for malware. Scan results populate the `cf.waf.content_scan.*` fields, which you can reference in custom rules and rate limiting rules.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } } ], "responses": { "200": { "description": "Enable Content Scanning response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-2" } } } }, "4XX": { "description": "Enable Content Scanning failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure-2" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Content Scanning" ], "x-api-token-group": [ "Zone WAF Write", "Account WAF Write" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "content-scan", "x-fern-sdk-method-name": "enable" } }, "/zones/{zone_id}/content-upload-scan/payloads": { "get": { "operationId": "waf-content-scanning-list-custom-scan-expressions", "summary": "List the Content Scanning custom expressions of a zone.", "description": "List the Content Scanning custom expressions configured for the zone, each with its own identifier. A custom expression tells the scanner how to reach content objects in a request it cannot parse on its own, such as files Base64-encoded inside a JSON body.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } } ], "responses": { "200": { "description": "List existing Content Scanning custom expressions response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-scan-collection" } } } }, "4XX": { "description": "List existing Content Scanning custom expressions failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-scan-collection" }, { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure-2" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Content Scanning" ], "x-api-token-group": [ "Zone WAF Write", "Zone WAF Read", "Account WAF Write", "Account WAF Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "content-scan.expressions", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "waf-content-scanning-add-custom-scan-expressions", "summary": "Create Content Scanning custom expressions for a zone.", "description": "Create one or more Content Scanning custom expressions, appending them to the existing list of the zone, and return the updated list. Each expression reaches content objects the scanner cannot find automatically, for example `lookup_json_string(http.request.body.raw, \"file\")`.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } } ], "requestBody": { "description": "Array of Content Scanning custom expressions to create.", "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "payload": { "$ref": "#/components/schemas/waf-product-api-bundle_custom-scan-payload" } }, "required": [ "payload" ], "type": "object" } } } } }, "responses": { "200": { "description": "Create Content Scanning custom expressions response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-scan-collection" } } } }, "4XX": { "description": "Create Content Scanning custom expressions failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-scan-collection" }, { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure-2" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Content Scanning" ], "x-api-token-group": [ "Zone WAF Write", "Account WAF Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "content-scan.expressions", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/content-upload-scan/payloads/{expression_id}": { "delete": { "operationId": "waf-content-scanning-delete-custom-scan-expressions", "summary": "Delete a Content Scanning custom expression from a zone.", "description": "Delete the Content Scanning custom expression with the given identifier and return the expressions that remain. Content objects reached only by the deleted expression are no longer scanned.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } }, { "name": "expression_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_custom-scan-id" } } ], "responses": { "200": { "description": "Delete Content Scanning custom expression response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-scan-collection" } } } }, "4XX": { "description": "Delete Content Scanning custom expression failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-scan-collection" }, { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure-2" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Content Scanning" ], "x-api-token-group": [ "Zone WAF Write", "Account WAF Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "content-scan.expressions", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes a Content Scanning custom expression." }, "patch": { "operationId": "waf-content-scanning-update-custom-scan-expression", "summary": "Update a Content Scanning custom expression for a zone.", "description": "Update the Content Scanning custom expression with the given identifier and return the updated list of expressions.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } }, { "name": "expression_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_custom-scan-id" } } ], "requestBody": { "description": "Content Scanning custom expression to update.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "$ref": "#/components/schemas/waf-product-api-bundle_custom-scan-payload" } }, "required": [ "payload" ] } } } }, "responses": { "200": { "description": "Update Content Scanning custom expression response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-scan-collection" } } } }, "4XX": { "description": "Update Content Scanning custom expression failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-scan-collection" }, { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure-2" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Content Scanning" ], "x-api-token-group": [ "Zone WAF Write", "Account WAF Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "content-scan.expressions", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/content-upload-scan/settings": { "get": { "operationId": "waf-content-scanning-get-status", "summary": "Get the Content Scanning status for a zone.", "description": "Get the current Content Scanning status for the zone, together with the date the status was last modified.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } } ], "responses": { "200": { "description": "Get Content Scanning status response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_response-status-2" } } } }, "4XX": { "description": "Get Content Scanning status failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure-2" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Content Scanning" ], "x-api-token-group": [ "Zone WAF Write", "Zone WAF Read", "Account WAF Write", "Account WAF Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "content-scan", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "waf-content-scanning-update-settings", "summary": "Update the Content Scanning status for a zone.", "description": "Update the Content Scanning status by setting the status value to `enabled` or `disabled`. This is equivalent to calling the dedicated enable and disable endpoints.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } } ], "requestBody": { "description": "Content Scanning settings to update.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "description": "The status value for Content Scanning.", "type": "string", "example": "enabled", "enum": [ "enabled", "disabled" ] } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Update Content Scanning settings response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_response-status-2" } } } }, "4XX": { "description": "Update Content Scanning settings failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure-2" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Content Scanning" ], "x-api-token-group": [ "Zone WAF Write", "Account WAF Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "content-scan", "x-fern-sdk-method-name": "update", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation toggles Content Scanning for a zone." } }, "/zones/{zone_id}/ct/alerting": { "get": { "operationId": "ct-alerting-get-subscription", "summary": "Get CT Alerting Subscription", "description": "Retrieve the Certificate Transparency alerting subscription settings for a zone. Returns whether CT monitoring is enabled and the list of email addresses that receive alerts, if any have been configured.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Get CT Alerting Subscription response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ct_alerting_subscription_response_single" } } } }, "4XX": { "description": "Get CT Alerting Subscription response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ct_alerting_subscription_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "CT Alerting" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ct-alerting", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "ct-alerting-update-subscription", "summary": "Update CT Alerting Subscription", "description": "Create or update the Certificate Transparency alerting subscription for a zone. Enables or disables email notifications when certificates are issued for the zone's domains.\nThe `enabled` field is required on every request and controls whether the subscription is active. The `emails` field is optional and, when provided, replaces the stored recipient list for the zone. When `emails` is omitted, the stored recipient list is preserved and only the enabled state is toggled. A maximum of 100 email addresses may be configured per zone.\nRequests that omit `enabled` are rejected with error code 1008.\nSubscribe and unsubscribe notification emails are only sent for recipients whose effective subscription state changes. Idempotent requests (no state change) send no notification email.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ct_alerting_subscription_update" } } } }, "responses": { "200": { "description": "Update CT Alerting Subscription response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ct_alerting_subscription_response_single" } } } }, "4XX": { "description": "Update CT Alerting Subscription response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ct_alerting_subscription_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "CT Alerting" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ct-alerting", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/custom_certificates": { "get": { "operationId": "custom-ssl-for-a-zone-list-ssl-configurations", "summary": "List SSL Configurations", "description": "List, search, and filter all of your custom SSL certificates. The higher priority will break ties across overlapping 'legacy_custom' certificates, but 'legacy_custom' certificates will always supercede 'sni_custom' certificates.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of zones per page.", "type": "number", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "match", "in": "query", "schema": { "description": "Whether to match all search requirements or at least one (any).", "type": "string", "default": "all", "enum": [ "any", "all" ] } }, { "name": "status", "in": "query", "schema": { "description": "Status of the zone's custom SSL.", "type": "string", "example": "active", "enum": [ "active", "expired", "deleted", "pending", "initializing" ], "readOnly": true } } ], "responses": { "200": { "description": "List SSL Configurations response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_collection" } } } }, "4XX": { "description": "List SSL Configurations response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_collection" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom SSL for a Zone" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write", "Access: Mutual TLS Certificates Read", "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-certificates", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "custom-ssl-for-a-zone-create-ssl-configuration", "summary": "Create SSL Configuration", "description": "Upload a new SSL certificate for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle_method": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_bundle_method" }, "certificate": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate" }, "custom_csr_id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_id" }, "deploy": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_deploy" }, "geo_restrictions": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_geo_restrictions" }, "policy": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_policy" }, "private_key": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_private_key" }, "type": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_type" } }, "required": [ "certificate" ] } } } }, "responses": { "200": { "description": "Create SSL Configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single" } } } }, "4XX": { "description": "Create SSL Configuration response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom SSL for a Zone" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write", "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-certificates", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/custom_certificates/prioritize": { "put": { "operationId": "custom-ssl-for-a-zone-re-prioritize-ssl-certificates", "summary": "Re-prioritize SSL Certificates", "description": "If a zone has multiple SSL certificates, you can set the order in which they should be used during a request. The higher priority will break ties across overlapping 'legacy_custom' certificates.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "certificates": { "description": "Array of ordered certificates.", "type": "array", "items": { "properties": { "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "priority": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_priority" } }, "type": "object" }, "example": [ { "id": "5a7805061c76ada191ed06f989cc3dac", "priority": 2 }, { "id": "9a7806061c88ada191ed06f989cc3dac", "priority": 1 } ] } }, "required": [ "certificates" ] } } } }, "responses": { "200": { "description": "Re-prioritize SSL Certificates response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_collection" } } } }, "4XX": { "description": "Re-prioritize SSL Certificates response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_collection" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom SSL for a Zone" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write", "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-certificates.prioritize", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/custom_certificates/{custom_certificate_id}": { "delete": { "operationId": "custom-ssl-for-a-zone-delete-ssl-configuration", "summary": "Delete SSL Configuration", "description": "Remove a SSL certificate from a zone.", "parameters": [ { "name": "custom_certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Delete SSL Configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_id_only" } } } }, "4XX": { "description": "Delete SSL Configuration response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_id_only" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom SSL for a Zone" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write", "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-certificates", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "custom-ssl-for-a-zone-ssl-configuration-details", "summary": "SSL Configuration Details", "description": "Retrieves details for a specific custom SSL certificate, including certificate metadata, bundle method, geographic restrictions, and associated keyless server configuration.", "parameters": [ { "name": "custom_certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "SSL Configuration Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single" } } } }, "4XX": { "description": "SSL Configuration Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom SSL for a Zone" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write", "Access: Mutual TLS Certificates Read", "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-certificates", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "custom-ssl-for-a-zone-edit-ssl-configuration", "summary": "Edit SSL Configuration", "description": "Upload a new private key and/or PEM/CRT for the SSL certificate. Note: PATCHing a configuration for sni_custom certificates will result in a new resource id being returned, and the previous one being deleted.", "parameters": [ { "name": "custom_certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle_method": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_bundle_method" }, "certificate": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate" }, "custom_csr_id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_id" }, "deploy": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_deploy" }, "geo_restrictions": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_geo_restrictions" }, "policy": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_policy" }, "private_key": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_private_key" } } } } } }, "responses": { "200": { "description": "Edit SSL Configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single" } } } }, "4XX": { "description": "Edit SSL Configuration response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom SSL for a Zone" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write", "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-certificates", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/custom_csrs": { "get": { "operationId": "custom-csrs-for-a-zone-list-custom-csrs", "summary": "List Custom CSRs", "description": "List all custom Certificate Signing Requests (CSRs) for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of custom CSRs per page.", "type": "number", "default": 20, "maximum": 50, "minimum": 5 } } ], "responses": { "200": { "description": "List Custom CSRs response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_response_collection" } } } }, "4XX": { "description": "List Custom CSRs response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_response_collection" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom CSRs for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-csrs", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "custom-csrs-for-a-zone-create-custom-csr", "summary": "Create Custom CSR", "description": "Generate a new custom Certificate Signing Request (CSR) for a zone. Cloudflare generates and securely stores the private key associated with the CSR. The CSR can then be provided to a Certificate Authority for signing. Once signed, the certificate is uploaded via the Custom SSL endpoint using the CSR ID.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_create_request" } } } }, "responses": { "201": { "description": "Create Custom CSR response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_response_single" } } } }, "4XX": { "description": "Create Custom CSR response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom CSRs for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-csrs", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/custom_csrs/{custom_csr_id}": { "delete": { "operationId": "custom-csrs-for-a-zone-delete-custom-csr", "summary": "Delete Custom CSR", "description": "Delete a custom Certificate Signing Request (CSR) and its associated private key. A CSR cannot be deleted if any custom certificates still reference it.", "parameters": [ { "name": "custom_csr_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Delete Custom CSR response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_response_id_only" } } } }, "4XX": { "description": "Delete Custom CSR response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_response_id_only" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom CSRs for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-csrs", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "custom-csrs-for-a-zone-custom-csr-details", "summary": "Custom CSR Details", "description": "Retrieve details for a specific custom Certificate Signing Request (CSR).", "parameters": [ { "name": "custom_csr_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Custom CSR Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_response_single" } } } }, "4XX": { "description": "Custom CSR Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom CSRs for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-csrs", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/custom_hostnames": { "get": { "operationId": "custom-hostname-for-a-zone-list-custom-hostnames", "summary": "List Custom Hostnames", "description": "List, search, sort, and filter all of your custom hostnames.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "hostname", "in": "query", "schema": { "description": "Fully qualified domain name to match against. This parameter cannot be used with the 'id', 'hostname.exact', 'hostname.contain', or 'hostname.startsWith' parameters.", "type": "string", "example": "app.example.com", "maxLength": 255 } }, { "name": "hostname.exact", "in": "query", "schema": { "description": "Fully qualified domain name to match against. This parameter cannot be used with the 'id', 'hostname', 'hostname.contain', or 'hostname.startsWith' parameters.", "type": "string", "example": "app.example.com", "maxLength": 255 } }, { "name": "hostname.startsWith", "in": "query", "schema": { "description": "Filters hostnames by a prefix match on the hostname value. This parameter cannot be used with the 'id', 'hostname', 'hostname.exact', or 'hostname.contain' parameters.", "type": "string", "example": "app", "maxLength": 255 } }, { "name": "hostname.contain", "in": "query", "schema": { "description": "Filters hostnames by a substring match on the hostname value. This parameter cannot be used with the 'id', 'hostname', 'hostname.exact', or 'hostname.startsWith' parameters.", "type": "string", "example": "example.com", "maxLength": 255 } }, { "name": "id", "in": "query", "schema": { "description": "Hostname ID to match against. This ID was generated and returned during the initial custom_hostname creation. This parameter cannot be used with the 'hostname', 'hostname.exact', 'hostname.contain', or 'hostname.startsWith' parameters.", "type": "string", "example": "0d89c70d-ad9f-4843-b99f-6cc0252067e9", "maxLength": 36, "minLength": 36 } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of hostnames per page.", "type": "number", "default": 20, "maximum": 1000, "minimum": 5 } }, { "name": "order", "in": "query", "schema": { "description": "Field to order hostnames by.", "type": "string", "example": "ssl", "default": "ssl", "enum": [ "ssl", "ssl_status" ] } }, { "name": "direction", "in": "query", "schema": { "description": "Direction to order hostnames.", "type": "string", "example": "desc", "enum": [ "asc", "desc" ] } }, { "name": "ssl_status", "in": "query", "schema": { "description": "Filter by SSL certificate status.", "type": "string", "example": "active", "enum": [ "initializing", "pending_validation", "deleted", "pending_issuance", "pending_deployment", "pending_deletion", "pending_expiration", "expired", "active", "initializing_timed_out", "validation_timed_out", "issuance_timed_out", "deployment_timed_out", "deletion_timed_out", "pending_cleanup", "staging_deployment", "staging_active", "deactivating", "inactive", "backup_issued", "holding_deployment" ] } }, { "name": "hostname_status", "in": "query", "schema": { "description": "Filter by the hostname's activation status.", "type": "string", "example": "provisioned", "enum": [ "active", "pending", "active_redeploying", "moved", "pending_deletion", "deleted", "pending_blocked", "pending_migration", "pending_provisioned", "test_pending", "test_active", "test_active_apex", "test_blocked", "test_failed", "provisioned", "blocked" ] } }, { "name": "certificate_authority", "in": "query", "schema": { "description": "Filter by the certificate authority that issued the SSL certificate.", "type": "string", "example": "google", "enum": [ "google", "lets_encrypt", "ssl_com" ] } }, { "name": "wildcard", "in": "query", "schema": { "description": "Filter by whether the custom hostname is a wildcard hostname.", "type": "boolean", "example": false } }, { "name": "custom_origin_server", "in": "query", "schema": { "description": "Filter by custom origin server name.", "type": "string", "example": "origin2.example.com" } }, { "name": "ssl", "in": "query", "schema": { "description": "Whether to filter hostnames based on if they have SSL enabled.", "type": "integer", "default": 0, "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "List Custom Hostnames response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_response_collection" } } } }, "4XX": { "description": "List Custom Hostnames response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_response_collection" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom Hostname for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-hostnames", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "custom-hostname-for-a-zone-create-custom-hostname", "summary": "Create Custom Hostname", "description": "Add a new custom hostname and request that an SSL certificate be issued for it. One of three validation methods—http, txt, email—should be used, with 'http' recommended if the CNAME is already in place (or will be soon). Specifying 'email' will send an email to the WHOIS contacts on file for the base domain plus hostmaster, postmaster, webmaster, admin, administrator. If http is used and the domain is not already pointing to the Managed CNAME host, the PATCH method must be used once it is (to complete validation). Enable bundling of certificates using the custom_cert_bundle field. The bundling process requires the following condition One certificate in the bundle must use an RSA, and the other must use an ECDSA.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_metadata": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_metadata" }, "custom_origin_server": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_origin_server" }, "custom_origin_sni": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_origin_sni" }, "hostname": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname_post" }, "ssl": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_sslpost" } }, "required": [ "hostname" ] } } } }, "responses": { "200": { "description": "Create Custom Hostname response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_response_single" } } } }, "4XX": { "description": "Create Custom Hostname response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom Hostname for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-hostnames", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/custom_hostnames/fallback_origin": { "delete": { "operationId": "custom-hostname-fallback-origin-for-a-zone-delete-fallback-origin-for-custom-hostnames", "summary": "Delete Fallback Origin for Custom Hostnames", "description": "Removes the fallback origin configuration for custom hostnames on a zone. Custom hostnames without specific origins will no longer have a fallback.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Delete Fallback Origin for Custom Hostnames response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_fallback_origin_response" } } } }, "4XX": { "description": "Delete Fallback Origin for Custom Hostnames response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_fallback_origin_response" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom Hostname Fallback Origin for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-hostnames.fallback-origin", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "custom-hostname-fallback-origin-for-a-zone-get-fallback-origin-for-custom-hostnames", "summary": "Get Fallback Origin for Custom Hostnames", "description": "Retrieves the current fallback origin configuration for custom hostnames on a zone. The fallback origin handles traffic when specific custom hostname origins are unavailable.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Get Fallback Origin for Custom Hostnames response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_fallback_origin_response" } } } }, "4XX": { "description": "Get Fallback Origin for Custom Hostnames response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_fallback_origin_response" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom Hostname Fallback Origin for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-hostnames.fallback-origin", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "custom-hostname-fallback-origin-for-a-zone-update-fallback-origin-for-custom-hostnames", "summary": "Update Fallback Origin for Custom Hostnames", "description": "Updates the fallback origin configuration for custom hostnames on a zone. Sets the default origin server for custom hostname traffic.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "origin": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_origin" } }, "required": [ "origin" ] } } } }, "responses": { "200": { "description": "Update Fallback Origin for Custom Hostnames response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_fallback_origin_response" } } } }, "4XX": { "description": "Update Fallback Origin for Custom Hostnames response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_fallback_origin_response" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom Hostname Fallback Origin for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-hostnames.fallback-origin", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/custom_hostnames/quota": { "get": { "operationId": "custom-hostname-for-a-zone-get-custom-hostname-quota", "summary": "Get Custom Hostname Quota", "description": "Returns custom hostname quota usage for a zone. The allocated quota is a soft limit; creating custom hostnames after usage exceeds this limit can still succeed until the hard cap is reached. Use the exceeded and hard_cap fields to track when usage is above the soft limit and when new custom hostname creation will be rejected.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Get Custom Hostname Quota response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_quota_response" } } } }, "4XX": { "description": "Get Custom Hostname Quota response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_api_response_failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom Hostname for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-hostnames.quota", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/custom_hostnames/{custom_hostname_id}": { "delete": { "operationId": "custom-hostname-for-a-zone-delete-custom-hostname-(-and-any-issued-ssl-certificates)", "summary": "Delete Custom Hostname (and any issued SSL certificates)", "description": "Permanently deletes a custom hostname and revokes any SSL certificates that were issued for it. This action cannot be undone.", "parameters": [ { "name": "custom_hostname_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Delete Custom Hostname (and any issued SSL certificates) response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } } } } }, "4XX": { "description": "Delete Custom Hostname (and any issued SSL certificates) response failure.", "content": { "application/json": { "schema": { "allOf": [ { "properties": { "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, "type": "object" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom Hostname for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-hostnames", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "custom-hostname-for-a-zone-custom-hostname-details", "summary": "Custom Hostname Details", "description": "Retrieves detailed information about a specific custom hostname, including SSL certificate status, ownership verification, and origin configuration.", "parameters": [ { "name": "custom_hostname_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Custom Hostname Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_response_single" } } } }, "4XX": { "description": "Custom Hostname Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom Hostname for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-hostnames", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "custom-hostname-for-a-zone-edit-custom-hostname", "summary": "Edit Custom Hostname", "description": "Modify SSL configuration for a custom hostname. When sent with SSL config that matches existing config, used to indicate that hostname should pass domain control validation (DCV). Can also be used to change validation type, e.g., from 'http' to 'email'. Bundle an existing certificate with another certificate by using the \"custom_cert_bundle\" field. The bundling process supports combining certificates as long as the following condition is met. One certificate must use the RSA algorithm, and the other must use the ECDSA algorithm.", "parameters": [ { "name": "custom_hostname_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_metadata": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_metadata" }, "custom_origin_server": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_origin_server" }, "custom_origin_sni": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_origin_sni" }, "ssl": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_sslpost" } } } } } }, "responses": { "200": { "description": "Edit Custom Hostname response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_response_single" } } } }, "4XX": { "description": "Edit Custom Hostname response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom Hostname for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-hostnames", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/custom_hostnames/{custom_hostname_id}/certificate_pack/{certificate_pack_id}/certificates/{certificate_id}": { "delete": { "operationId": "custom-hostname-for-a-zone-delete_single_certificate_and_key_in_a_custom_hostname", "summary": "Delete Single Certificate And Key For Custom Hostname", "description": "Delete a single custom certificate from a certificate pack that contains two bundled certificates. Deletion is subject to the following constraints. You cannot delete a certificate if it is the only remaining certificate in the pack. At least one certificate must remain in the pack.", "parameters": [ { "name": "custom_hostname_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "certificate_pack_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "202": { "description": "Delete Single Certificate and Key In a Custom Hostname response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } } } } }, "4XX": { "description": "Delete Single Certificate and Key In a Custom Hostname response failure.", "content": { "application/json": { "schema": { "allOf": [ { "properties": { "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, "type": "object" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom Hostname for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-hostnames.certificate-pack.certificates", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "put": { "operationId": "custom-hostname-for-a-zone-edit-custom-certificate-custom-hostname", "summary": "Replace Custom Certificate and Custom Key In Custom Hostname", "description": "Replace a single custom certificate within a certificate pack that contains two bundled certificates. The replacement must adhere to the following constraints. You can only replace an RSA certificate with another RSA certificate or an ECDSA certificate with another ECDSA certificate.", "parameters": [ { "name": "custom_hostname_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "certificate_pack_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_cert_and_key" } } } }, "responses": { "202": { "description": "Edit Custom Certificate In a Custom Hostname response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_response_single" } } } }, "4XX": { "description": "Edit Custom Certificate In a Custom Hostname response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Custom Hostname for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "custom-hostnames.certificate-pack.certificates", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/custom_ns": { "get": { "operationId": "account-level-custom-nameservers-usage-for-a-zone-get-account-custom-nameserver-related-zone-metadata", "summary": "Get Account Custom Nameserver Related Zone Metadata", "description": "Get metadata for account-level custom nameservers on a zone.\n\nDeprecated in favor of [Show DNS Settings](https://developers.cloudflare.com/api/operations/dns-settings-for-a-zone-list-dns-settings).\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-custom-nameservers_identifier-2" } } ], "responses": { "200": { "description": "Get Account Custom Nameserver Related Zone Metadata response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-custom-nameservers_get_response" } } } }, "4XX": { "description": "Get Account Custom Nameserver Related Zone Metadata response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_get_response" }, { "$ref": "#/components/schemas/dns-custom-nameservers_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Account-Level Custom Nameservers Usage for a Zone" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read", "Zero Trust: PII Read", "Zaraz Edit", "Zaraz Read", "Zaraz Admin", "Access: Apps and Policies Revoke", "Access: Apps and Policies Write", "Access: Apps and Policies Read", "Access: Apps and Policies Revoke", "Access: Mutual TLS Certificates Write", "Access: Organizations, Identity Providers, and Groups Write", "Zone Settings Write", "Zone Settings Read", "Zone Read", "DNS Read", "Workers Scripts Write", "Workers Scripts Read", "Zone Write", "Workers Routes Write", "Workers Routes Read", "Stream Write", "Stream Read", "SSL and Certificates Write", "SSL and Certificates Read", "Logs Write", "Logs Read", "Cache Purge", "Page Rules Write", "Page Rules Read", "Load Balancers Write", "Load Balancers Read", "Firewall Services Write", "Firewall Services Read", "DNS Write", "Apps Write", "Analytics Read", "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-cfPermissionsRequired": { "enum": [ "#zone:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "zones.custom-nameservers", "x-fern-sdk-method-name": "get", "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" } }, "put": { "operationId": "account-level-custom-nameservers-usage-for-a-zone-set-account-custom-nameserver-related-zone-metadata", "summary": "Set Account Custom Nameserver Related Zone Metadata", "description": "Set metadata for account-level custom nameservers on a zone.\n\nIf you would like new zones in the account to use account custom nameservers by default, use PUT /accounts/:identifier to set the account setting use_account_custom_ns_by_default to true.\n\nDeprecated in favor of [Update DNS Settings](https://developers.cloudflare.com/api/operations/dns-settings-for-a-zone-update-dns-settings).\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-custom-nameservers_identifier-2" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-custom-nameservers_zone_metadata" } } } }, "responses": { "200": { "description": "Set Account Custom Nameserver Related Zone Metadata response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-custom-nameservers_empty_response-2" } } } }, "4XX": { "description": "Set Account Custom Nameserver Related Zone Metadata response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_empty_response-2" }, { "$ref": "#/components/schemas/dns-custom-nameservers_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Account-Level Custom Nameservers Usage for a Zone" ], "x-api-token-group": [ "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "zones.custom-nameservers", "x-fern-sdk-method-name": "update", "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" } } }, "/zones/{zone_id}/dcv_delegation/uuid": { "get": { "operationId": "dcv-delegation-uuid-get", "summary": "Retrieve the DCV Delegation unique identifier.", "description": "Retrieve the account and zone specific unique identifier used as part of the CNAME target for DCV Delegation.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Retrieve the DCV Delegation unique identifier response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_dcv_delegation_response" } } } }, "4XX": { "description": "Retrieve the DCV Delegation unique identifier response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_dcv_delegation_response" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DCV Delegation" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dcv-delegation", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/devices/policy/certificates": { "get": { "operationId": "devices-get-policy-certificates", "summary": "Get device certificate provisioning status", "description": "Fetches device certificate provisioning.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/teams-devices_identifier" } } ], "responses": { "200": { "description": "Get WARP client provision certificates enabled status response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/teams-devices_devices_policy_certificates_single" } } } }, "4XX": { "description": "Get WARP client provision certificates enabled status failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_devices_policy_certificates_single" }, { "$ref": "#/components/schemas/teams-devices_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Devices" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.devices.policies.default.certificates", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "devices-update-policy-certificates", "summary": "Update device certificate provisioning status", "description": "Enable Zero Trust Clients to provision a certificate, containing a x509 subject, and referenced by Access device posture policies when the client visits MTLS protected domains. This facilitates device posture without a WARP session.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/teams-devices_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/teams-devices_devices_policy_certificates" } } } }, "responses": { "200": { "description": "Update a zone to toggle permission for devices to provision certificates response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/teams-devices_devices_policy_certificates_single" } } } }, "4XX": { "description": "Patch a zone to toggle permission for devices to provision certificates failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_devices_policy_certificates_single" }, { "$ref": "#/components/schemas/teams-devices_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Devices" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zero-trust.devices.policies.default.certificates", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/dns_analytics/report": { "get": { "operationId": "dns-analytics-table", "summary": "Table", "description": "Retrieves a list of summarised aggregate metrics over a given time period.\n\nSee [Analytics API properties](https://developers.cloudflare.com/dns/reference/analytics-api-properties/) for detailed information about the available query parameters.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-analytics_identifier" } }, { "name": "metrics", "in": "query", "schema": { "$ref": "#/components/schemas/dns-analytics_metrics" } }, { "name": "dimensions", "in": "query", "schema": { "$ref": "#/components/schemas/dns-analytics_dimensions" } }, { "name": "since", "in": "query", "schema": { "$ref": "#/components/schemas/dns-analytics_since" } }, { "name": "until", "in": "query", "schema": { "$ref": "#/components/schemas/dns-analytics_until" } }, { "name": "limit", "in": "query", "schema": { "$ref": "#/components/schemas/dns-analytics_limit" } }, { "name": "sort", "in": "query", "schema": { "$ref": "#/components/schemas/dns-analytics_sort" } }, { "name": "filters", "in": "query", "schema": { "$ref": "#/components/schemas/dns-analytics_filters" } } ], "responses": { "200": { "description": "Table response", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-analytics_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dns-analytics_report" } }, "type": "object" } ] } } } }, "4XX": { "description": "Table response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-analytics_api-response-common-failure" }, { "properties": { "result": { "$ref": "#/components/schemas/dns-analytics_report" } }, "type": "object" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Analytics" ], "x-api-token-group": [ "Analytics Read" ], "x-cfPermissionsRequired": { "enum": [ "#analytics:read" ] }, "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "dns.analytics.reports", "x-fern-sdk-method-name": "get", "x-stainless-deprecation-message": "This endpoint is deprecated. See [the API deprecation notice](https://developers.cloudflare.com/fundamentals/api/reference/deprecations/#2025-12-09)." } }, "/zones/{zone_id}/dns_analytics/report/bytime": { "get": { "operationId": "dns-analytics-by-time", "summary": "By Time", "description": "Retrieves a list of aggregate metrics grouped by time interval.\n\nSee [Analytics API properties](https://developers.cloudflare.com/dns/reference/analytics-api-properties/) for detailed information about the available query parameters.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-analytics_identifier" } }, { "name": "metrics", "in": "query", "schema": { "$ref": "#/components/schemas/dns-analytics_metrics" } }, { "name": "dimensions", "in": "query", "schema": { "$ref": "#/components/schemas/dns-analytics_dimensions" } }, { "name": "since", "in": "query", "schema": { "$ref": "#/components/schemas/dns-analytics_since" } }, { "name": "until", "in": "query", "schema": { "$ref": "#/components/schemas/dns-analytics_until" } }, { "name": "limit", "in": "query", "schema": { "$ref": "#/components/schemas/dns-analytics_limit" } }, { "name": "sort", "in": "query", "schema": { "$ref": "#/components/schemas/dns-analytics_sort" } }, { "name": "filters", "in": "query", "schema": { "$ref": "#/components/schemas/dns-analytics_filters" } }, { "name": "time_delta", "in": "query", "schema": { "$ref": "#/components/schemas/dns-analytics_time_delta" } } ], "responses": { "200": { "description": "By Time response", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-analytics_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dns-analytics_report_bytime" } }, "type": "object" } ] } } } }, "4XX": { "description": "By Time response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-analytics_api-response-common-failure" }, { "properties": { "result": { "$ref": "#/components/schemas/dns-analytics_report_bytime" } }, "type": "object" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Analytics" ], "x-api-token-group": [ "Analytics Read" ], "x-cfPermissionsRequired": { "enum": [ "#analytics:read" ] }, "x-fern-availability": "deprecated", "x-fern-ignore": true, "x-fern-sdk-group-name": "dns.analytics.reports.bytimes", "x-fern-sdk-method-name": "get", "x-stainless-deprecation-message": "This endpoint is deprecated. See [the API deprecation notice](https://developers.cloudflare.com/fundamentals/api/reference/deprecations/#2025-12-09)." } }, "/zones/{zone_id}/dns_records": { "get": { "operationId": "dns-records-for-a-zone-list-dns-records", "summary": "List DNS Records", "description": "List, search, sort, and filter a zones' DNS records.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } }, { "name": "name", "in": "query", "schema": { "description": "Exact value of the DNS record name. This is a convenience alias for `name.exact`.\n", "type": "string", "example": "www.example.com" } }, { "name": "name.exact", "in": "query", "schema": { "description": "Exact value of the DNS record name. Name filters are case-insensitive.\n", "type": "string", "example": "www.example.com" } }, { "name": "name.contains", "in": "query", "schema": { "description": "Substring of the DNS record name. Name filters are case-insensitive.\n", "type": "string", "example": "w.example." } }, { "name": "name.startswith", "in": "query", "schema": { "description": "Prefix of the DNS record name. Name filters are case-insensitive.\n", "type": "string", "example": "www.example" } }, { "name": "name.endswith", "in": "query", "schema": { "description": "Suffix of the DNS record name. Name filters are case-insensitive.\n", "type": "string", "example": ".example.com" } }, { "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/dns-records_type" } }, { "name": "content", "in": "query", "schema": { "description": "Exact value of the DNS record content. This is a convenience alias for `content.exact`.\n", "type": "string", "example": "127.0.0.1" } }, { "name": "content.exact", "in": "query", "schema": { "description": "Exact value of the DNS record content. Content filters are case-insensitive.\n", "type": "string", "example": "127.0.0.1" } }, { "name": "content.contains", "in": "query", "schema": { "description": "Substring of the DNS record content. Content filters are case-insensitive.\n", "type": "string", "example": "7.0.0." } }, { "name": "content.startswith", "in": "query", "schema": { "description": "Prefix of the DNS record content. Content filters are case-insensitive.\n", "type": "string", "example": "127.0." } }, { "name": "content.endswith", "in": "query", "schema": { "description": "Suffix of the DNS record content. Content filters are case-insensitive.\n", "type": "string", "example": ".0.1" } }, { "name": "proxied", "in": "query", "schema": { "$ref": "#/components/schemas/dns-records_proxied" } }, { "name": "match", "in": "query", "schema": { "$ref": "#/components/schemas/dns-records_match" } }, { "name": "comment", "in": "query", "schema": { "description": "Exact value of the DNS record comment. This is a convenience alias for `comment.exact`.\n", "type": "string", "example": "Hello, world" } }, { "name": "comment.present", "in": "query", "schema": { "description": "If this parameter is present, only records *with* a comment are returned.\n", "type": "string" } }, { "name": "comment.absent", "in": "query", "schema": { "description": "If this parameter is present, only records *without* a comment are returned.\n", "type": "string" } }, { "name": "comment.exact", "in": "query", "schema": { "description": "Exact value of the DNS record comment. Comment filters are case-insensitive.\n", "type": "string", "example": "Hello, world" } }, { "name": "comment.contains", "in": "query", "schema": { "description": "Substring of the DNS record comment. Comment filters are case-insensitive.\n", "type": "string", "example": "ello, worl" } }, { "name": "comment.startswith", "in": "query", "schema": { "description": "Prefix of the DNS record comment. Comment filters are case-insensitive.\n", "type": "string", "example": "Hello, w" } }, { "name": "comment.endswith", "in": "query", "schema": { "description": "Suffix of the DNS record comment. Comment filters are case-insensitive.\n", "type": "string", "example": "o, world" } }, { "name": "tag", "in": "query", "schema": { "description": "Condition on the DNS record tag.\n\nParameter values can be of the form `:` to search for an exact `name:value` pair, or just `` to search for records with a specific tag name regardless of its value.\n\nThis is a convenience shorthand for the more powerful `tag.` parameters.\nExamples:\n- `tag=important` is equivalent to `tag.present=important`\n- `tag=team:DNS` is equivalent to `tag.exact=team:DNS`\n", "type": "string", "example": "team:DNS" } }, { "name": "tag.present", "in": "query", "schema": { "description": "Name of a tag which must be present on the DNS record. Tag filters are case-insensitive.\n", "type": "string", "example": "important" } }, { "name": "tag.absent", "in": "query", "schema": { "description": "Name of a tag which must *not* be present on the DNS record. Tag filters are case-insensitive.\n", "type": "string", "example": "important" } }, { "name": "tag.exact", "in": "query", "schema": { "description": "A tag and value, of the form `:`. The API will only return DNS records that have a tag named `` whose value is ``. Tag filters are case-insensitive.\n", "type": "string", "example": "greeting:Hello, world" } }, { "name": "tag.contains", "in": "query", "schema": { "description": "A tag and value, of the form `:`. The API will only return DNS records that have a tag named `` whose value contains ``. Tag filters are case-insensitive.\n", "type": "string", "example": "greeting:ello, worl" } }, { "name": "tag.startswith", "in": "query", "schema": { "description": "A tag and value, of the form `:`. The API will only return DNS records that have a tag named `` whose value starts with ``. Tag filters are case-insensitive.\n", "type": "string", "example": "greeting:Hello, w" } }, { "name": "tag.endswith", "in": "query", "schema": { "description": "A tag and value, of the form `:`. The API will only return DNS records that have a tag named `` whose value ends with ``. Tag filters are case-insensitive.\n", "type": "string", "example": "greeting:o, world" } }, { "name": "search", "in": "query", "schema": { "$ref": "#/components/schemas/dns-records_search" } }, { "name": "tag_match", "in": "query", "schema": { "$ref": "#/components/schemas/dns-records_tag_match" } }, { "name": "page", "in": "query", "schema": { "$ref": "#/components/schemas/dns-records_page" } }, { "name": "per_page", "in": "query", "schema": { "$ref": "#/components/schemas/dns-records_per_page" } }, { "name": "order", "in": "query", "schema": { "$ref": "#/components/schemas/dns-records_order" } }, { "name": "direction", "in": "query", "schema": { "$ref": "#/components/schemas/dns-records_direction" } }, { "$ref": "#/components/parameters/dns-records_include_shadow_metadata" }, { "name": "shadowed_by_name", "in": "query", "schema": { "description": "Filters to records at or below the given NS delegation name, excluding the NS records that form the delegation itself. The value must be a subdomain of the zone; the zone apex is not accepted. Requires `include_shadow_metadata=true`. See [Shadowed records](https://developers.cloudflare.com/dns/manage-dns-records/reference/shadowed-records).\n", "type": "string", "example": "sub.example.com" } }, { "name": "shadowing_name", "in": "query", "schema": { "description": "Returns NS records that shadow the given name, searching at the name itself and each of its ancestor names within the zone, excluding the zone apex. The value must be a subdomain of the zone; the zone apex is not accepted. See [Shadowed records](https://developers.cloudflare.com/dns/manage-dns-records/reference/shadowed-records).\n", "type": "string", "example": "www.sub.example.com" } } ], "responses": { "200": { "description": "List DNS Records response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns_response_collection" } } } }, "4XX": { "description": "List DNS Records response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns_response_collection" }, { "$ref": "#/components/schemas/dns-records_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Records for a Zone" ], "x-api-token-group": [ "DNS Read", "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#dns_records:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.records", "x-fern-sdk-method-name": "list", "x-forge-params": { "zone_id": { "description": "Zone ID" } } }, "post": { "operationId": "dns-records-for-a-zone-create-dns-record", "summary": "Create DNS Record", "description": "Create a new DNS record for a zone.\n\nNotes:\n- A/AAAA records cannot exist on the same name as CNAME records.\n- NS records cannot exist on the same name as any other record type.\n- Domain names are always represented in Punycode, even if Unicode\n characters were used when creating the record.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } }, { "$ref": "#/components/parameters/dns-records_include_shadow_metadata" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns-record-post" } } } }, "responses": { "200": { "description": "Create DNS Record response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns_response_single" } } } }, "4XX": { "description": "Create DNS Record response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns_response_single" }, { "$ref": "#/components/schemas/dns-records_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Records for a Zone" ], "x-api-token-group": [ "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#dns_records:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.records", "x-fern-sdk-method-name": "create" } }, "/zones/{zone_id}/dns_records/batch": { "post": { "operationId": "dns-records-for-a-zone-batch-dns-records", "summary": "Batch DNS Records", "description": "Send a Batch of DNS Record API calls to be executed together.\n\nNotes:\n- Although Cloudflare will execute the batched operations in a single database transaction, Cloudflare's distributed KV store must treat each record change as a single key-value pair. This means that the propagation of changes is not atomic. See [the documentation](https://developers.cloudflare.com/dns/manage-dns-records/how-to/batch-record-changes/ \"Batch DNS records\") for more information.\n- The operations you specify within the /batch request body are always executed in the following order:\n\n - Deletes\n - Patches\n - Puts\n - Posts\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } }, { "$ref": "#/components/parameters/dns-records_include_shadow_metadata" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns-request-batch-object" } } } }, "responses": { "200": { "description": "Batch DNS Records response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns_response_batch" } } } }, "4XX": { "description": "Batch DNS Records response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Records for a Zone" ], "x-api-token-group": [ "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#dns_records:batch" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.records", "x-fern-sdk-method-name": "batch" } }, "/zones/{zone_id}/dns_records/export": { "get": { "operationId": "dns-records-for-a-zone-export-dns-records", "summary": "Export DNS Records", "description": "You can export your [BIND config](https://en.wikipedia.org/wiki/Zone_file \"Zone file\") through this endpoint.\n\nSee [the documentation](https://developers.cloudflare.com/dns/manage-dns-records/how-to/import-and-export/ \"Import and export records\") for more information.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } } ], "responses": { "200": { "description": "Export DNS Records response", "content": { "text/plain": { "schema": { "description": "Exported BIND zone file.", "type": "string", "example": "www.example.com. 300 IN A 127.0.0.1\n" } } } }, "4XX": { "description": "Export DNS Records response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Records for a Zone" ], "x-api-token-group": [ "DNS Read", "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#dns_records:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.records", "x-fern-sdk-method-name": "export" } }, "/zones/{zone_id}/dns_records/import": { "post": { "operationId": "dns-records-for-a-zone-import-dns-records", "summary": "Import DNS Records", "description": "You can upload your [BIND config](https://en.wikipedia.org/wiki/Zone_file \"Zone file\") through this endpoint. It assumes that cURL is called from a location with bind_config.txt (valid BIND config) present.\n\nSee [the documentation](https://developers.cloudflare.com/dns/manage-dns-records/how-to/import-and-export/ \"Import and export records\") for more information.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "description": "BIND config to import.\n\n**Tip:** When using cURL, a file can be uploaded using `--form 'file=@bind_config.txt'`.\n", "type": "string", "example": "www.example.com. 300 IN A 127.0.0.1" }, "proxied": { "description": "Whether or not proxiable records should receive the performance and security benefits of Cloudflare.\n\nThe value should be either `true` or `false`.", "type": "string", "example": "true", "default": "false" } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Import DNS Records response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns_response_import_scan" } } } }, "4XX": { "description": "Import DNS Records response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns_response_import_scan" }, { "$ref": "#/components/schemas/dns-records_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Records for a Zone" ], "x-api-token-group": [ "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#dns_records:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.records", "x-fern-sdk-method-name": "import" } }, "/zones/{zone_id}/dns_records/scan": { "post": { "operationId": "dns-records-for-a-zone-scan-dns-records", "summary": "Scan DNS Records", "description": "Scan for common DNS records on your domain and automatically add them to your zone. Useful if you haven't updated your nameservers yet.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": {} } }, "responses": { "200": { "description": "Scan DNS Records response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns_response_import_scan" } } } }, "4XX": { "description": "Scan DNS Records response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns_response_import_scan" }, { "$ref": "#/components/schemas/dns-records_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Records for a Zone" ], "x-api-token-group": [ "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#dns_records:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.records", "x-fern-sdk-method-name": "scan", "x-stainless-deprecation-message": "This endpoint is deprecated in favor of a new asynchronous version. Please use the [/scan/trigger](https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/scan/trigger) and [/scan/review](https://developers.cloudflare.com/api/resources/dns/subresources/records/methods/scan/review) endpoints instead.\n" } }, "/zones/{zone_id}/dns_records/scan/review": { "get": { "operationId": "dns-records-for-a-zone-review-dns-scan", "summary": "List Scanned DNS Records", "description": "Retrieves the list of DNS records discovered up to this point by the asynchronous scan. These records are temporary until explicitly accepted or rejected via `POST /scan/review`. Additional records may be discovered by the scan later.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } } ], "responses": { "200": { "description": "List of discovered DNS records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns_response_collection" } } } }, "4XX": { "description": "Scan review failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Records for a Zone" ], "x-api-token-group": [ "DNS Read", "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#dns_records:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.records", "x-fern-sdk-method-name": "scan-list" }, "post": { "operationId": "dns-records-for-a-zone-apply-dns-scan-results", "summary": "Review Scanned DNS Records", "description": "Accept or reject DNS records found by the DNS records scan. Accepted records will be permanently added to the zone, while rejected records will be permanently deleted.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns-request-review-scan-object" } } } }, "responses": { "200": { "description": "Records reviewed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns_response_review_scan" } } } }, "4XX": { "description": "Review failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Records for a Zone" ], "x-api-token-group": [ "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#dns_records:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.records", "x-fern-sdk-method-name": "scan-review" } }, "/zones/{zone_id}/dns_records/scan/trigger": { "post": { "operationId": "dns-records-for-a-zone-trigger-dns-scan", "summary": "Trigger DNS Record Scan", "description": "Initiates an asynchronous scan for common DNS records on your domain. Note that this **does not** automatically add records to your zone. The scan runs in the background, and results can be reviewed later using the `/scan/review` endpoints. Useful if you haven't updated your nameservers yet.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } } ], "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "description": "Trigger DNS Records Scan Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns_response_trigger_scan" } } } }, "4XX": { "description": "Trigger DNS Records Scan response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns_response_trigger_scan" }, { "$ref": "#/components/schemas/dns-records_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Records for a Zone" ], "x-api-token-group": [ "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#dns_records:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.records", "x-fern-sdk-method-name": "scan-trigger" } }, "/zones/{zone_id}/dns_records/usage": { "get": { "operationId": "dns-records-for-a-zone-get-usage", "summary": "Get DNS Record Usage", "description": "Get the current DNS record usage for a zone, including the number of records and the quota limit.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } } ], "responses": { "200": { "description": "Get DNS Record Usage response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns_response_zone_usage" } } } }, "4XX": { "description": "Get DNS Record Usage response failure.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns_response_zone_usage" }, { "$ref": "#/components/schemas/dns-records_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Records for a Zone" ], "x-api-token-group": [ "Zone DNS Settings Write", "Zone DNS Settings Read", "DNS Read", "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#dns_records:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.usage.zone", "x-fern-sdk-method-name": "get" } }, "/zones/{zone_id}/dns_records/{dns_record_id}": { "delete": { "operationId": "dns-records-for-a-zone-delete-dns-record", "summary": "Delete DNS Record", "description": "Permanently removes a DNS record from the zone.", "parameters": [ { "name": "dns_record_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": {} } }, "responses": { "200": { "description": "Delete DNS Record response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/dns-records_identifier" } } } } } } } }, "4XX": { "description": "Delete DNS Record response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/dns-records_identifier" } } } }, "type": "object" }, { "$ref": "#/components/schemas/dns-records_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Records for a Zone" ], "x-api-token-group": [ "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#dns_records:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.records", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "dns-records-for-a-zone-dns-record-details", "summary": "DNS Record Details", "description": "Retrieves details for a specific DNS record in the zone.", "parameters": [ { "name": "dns_record_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } }, { "$ref": "#/components/parameters/dns-records_include_shadow_metadata" } ], "responses": { "200": { "description": "DNS Record Details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns_response_single" } } } }, "4XX": { "description": "DNS Record Details response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns_response_single" }, { "$ref": "#/components/schemas/dns-records_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Records for a Zone" ], "x-api-token-group": [ "DNS Read", "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#dns_records:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.records", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "dns-records-for-a-zone-patch-dns-record", "summary": "Update DNS Record", "description": "Update an existing DNS record.\n\nNotes:\n- A/AAAA records cannot exist on the same name as CNAME records.\n- NS records cannot exist on the same name as any other record type.\n- Domain names are always represented in Punycode, even if Unicode\n characters were used when creating the record.\n", "parameters": [ { "name": "dns_record_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } }, { "$ref": "#/components/parameters/dns-records_include_shadow_metadata" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns-record-patch" } } } }, "responses": { "200": { "description": "Patch DNS Record response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns_response_single" } } } }, "4XX": { "description": "Patch DNS Record response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns_response_single" }, { "$ref": "#/components/schemas/dns-records_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Records for a Zone" ], "x-api-token-group": [ "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#dns_records:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.records", "x-fern-sdk-method-name": "edit" }, "put": { "operationId": "dns-records-for-a-zone-update-dns-record", "summary": "Overwrite DNS Record", "description": "Overwrite an existing DNS record.\n\nNotes:\n- A/AAAA records cannot exist on the same name as CNAME records.\n- NS records cannot exist on the same name as any other record type.\n- Domain names are always represented in Punycode, even if Unicode\n characters were used when creating the record.\n", "parameters": [ { "name": "dns_record_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-records_identifier" } }, { "$ref": "#/components/parameters/dns-records_include_shadow_metadata" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns-record-post" } } } }, "responses": { "200": { "description": "Update DNS Record response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-records_dns_response_single" } } } }, "4XX": { "description": "Update DNS Record response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns_response_single" }, { "$ref": "#/components/schemas/dns-records_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Records for a Zone" ], "x-api-token-group": [ "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#dns_records:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.records", "x-fern-sdk-method-name": "update" } }, "/zones/{zone_id}/dns_settings": { "get": { "operationId": "dns-settings-for-a-zone-list-dns-settings", "summary": "Show DNS Settings", "description": "Show DNS settings for a zone", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-settings_identifier" } } ], "responses": { "200": { "description": "Show DNS Settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-settings_dns_response_single-2" } } } }, "4XX": { "description": "Show DNS Settings response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_dns_response_single-2" }, { "$ref": "#/components/schemas/dns-settings_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Settings for a Zone" ], "x-api-token-group": [ "Zone DNS Settings Write", "Zone DNS Settings Read", "DNS Read", "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#dns_records:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.settings.zone", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "dns-settings-for-a-zone-update-dns-settings", "summary": "Update DNS Settings", "description": "Update DNS settings for a zone", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dns-settings_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-settings_dns-settings-zone-patch" } } } }, "responses": { "200": { "description": "Show DNS Settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dns-settings_dns_response_single-2" } } } }, "4XX": { "description": "Show DNS Settings response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_dns_response_single-2" }, { "$ref": "#/components/schemas/dns-settings_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNS Settings for a Zone" ], "x-api-token-group": [ "Zone DNS Settings Write", "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#dns_records:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.settings.zone", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/dnssec": { "delete": { "operationId": "dnssec-delete-dnssec-records", "summary": "Delete DNSSEC records", "description": "Delete DNSSEC.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dnssec_identifier" } } ], "responses": { "200": { "description": "Delete DNSSEC records response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dnssec_delete_dnssec_response_single" } } } }, "4XX": { "description": "Delete DNSSEC records response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dnssec_delete_dnssec_response_single" }, { "$ref": "#/components/schemas/dnssec_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNSSEC" ], "x-api-token-group": [ "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.dnssec", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "dnssec-dnssec-details", "summary": "DNSSEC Details", "description": "Details about DNSSEC status and configuration.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dnssec_identifier" } } ], "responses": { "200": { "description": "DNSSEC Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dnssec_dnssec_response_single" } } } }, "4XX": { "description": "DNSSEC Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dnssec_dnssec_response_single" }, { "$ref": "#/components/schemas/dnssec_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNSSEC" ], "x-api-token-group": [ "DNS Read", "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.dnssec", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "dnssec-edit-dnssec-status", "summary": "Edit DNSSEC Status", "description": "Enable or disable DNSSEC.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dnssec_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dnssec_multi_signer": { "$ref": "#/components/schemas/dnssec_dnssec_multi_signer" }, "dnssec_presigned": { "$ref": "#/components/schemas/dnssec_dnssec_presigned" }, "dnssec_use_nsec3": { "$ref": "#/components/schemas/dnssec_dnssec_use_nsec3" }, "status": { "description": "Status of DNSSEC, based on user-desired state and presence of necessary records.", "type": "string", "example": "active", "enum": [ "active", "disabled" ] } } } } } }, "responses": { "200": { "description": "Edit DNSSEC Status response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dnssec_dnssec_response_single" } } } }, "4XX": { "description": "Edit DNSSEC Status response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dnssec_dnssec_response_single" }, { "$ref": "#/components/schemas/dnssec_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNSSEC" ], "x-api-token-group": [ "DNS Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.dnssec", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/dnssec/zsk": { "get": { "operationId": "dnssec-list-dnssec-zsks", "summary": "List DNSSEC ZSKs", "description": "List the Zone Signing Keys (ZSKs) that DNSSEC uses for the zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/dnssec_identifier" } } ], "responses": { "200": { "description": "List DNSSEC ZSKs response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dnssec_dnssec_zsk_response_collection" } } } }, "4XX": { "description": "List DNSSEC ZSKs response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/dnssec_dnssec_zsk_response_collection" }, { "$ref": "#/components/schemas/dnssec_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "DNSSEC" ], "x-api-token-group": [ "DNS Read", "DNS Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.dnssec.list", "x-fern-sdk-method-name": "zsks" } }, "/zones/{zone_id}/email/auth/dmarc-reports": { "get": { "operationId": "get_dmarc_reports_status", "summary": "Get DMARC Report Status", "description": "Retrieves the current DMARC report configuration and status for a zone.\nReturns the RUA prefix, enabled status, approved sources, and DNS records.\n", "parameters": [ { "$ref": "#/components/parameters/email-auth_zone_id" } ], "responses": { "200": { "description": "DMARC report status retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/email-auth_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/email-auth_DmarcReportResponse" } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/email-auth_ClientError" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Email Auth" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-auth.dmarc-reports", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "configure_dmarc_reports", "summary": "Configure DMARC Reports", "description": "Updates the DMARC report configuration for a zone.\nAt least one of `enabled` or `skip_wizard` must be provided.\nWhen enabling, the handler will ensure the DMARC RUA record exists in DNS.\n", "parameters": [ { "$ref": "#/components/parameters/email-auth_zone_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email-auth_ConfigureDmarcReportsRequest" } } } }, "responses": { "200": { "description": "DMARC report configuration updated successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/email-auth_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/email-auth_DmarcReportResponse" } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/email-auth_ClientError" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Email Auth" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-auth.dmarc-reports", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/email/auth/spf/inspect": { "get": { "operationId": "inspect_spf", "summary": "Inspect SPF Record", "description": "Inspects a specific SPF TXT record and returns a parsed tree structure\nin the spflimit-worker format.\n\nThe record ID must be provided via the `id` query parameter.\n\nReturns a recursive tree showing:\n- Parsed components with their qualifiers and types\n- Nested includes recursively resolved within components\n- Per-component and total lookup counts\n- Detailed error information with context\n", "parameters": [ { "$ref": "#/components/parameters/email-auth_zone_id" }, { "$ref": "#/components/parameters/email-auth_record_id" } ], "responses": { "200": { "description": "SPF record inspected successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/email-auth_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/email-auth_SpfTree" } }, "type": "object" } ] } } } }, "4XX": { "$ref": "#/components/responses/email-auth_ClientError" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Email Auth" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-auth.spf", "x-fern-sdk-method-name": "inspect", "x-forge-hidden": true } }, "/zones/{zone_id}/email/routing": { "get": { "operationId": "email-routing-settings-get-email-routing-settings", "summary": "Get Email Routing settings", "description": "Get information about the settings for your Email Routing zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "responses": { "200": { "description": "Get Email Routing settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_email_settings_response_single" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.email.routing.config.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "email-routing-settings-update-email-routing-settings", "summary": "Update Email Routing settings", "description": "Update the settings for your Email Routing zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_update_email_routing_settings_properties" } } } }, "responses": { "200": { "description": "Update Email Routing settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_email_settings_response_single" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.email.routing.config.update" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "email-routing-settings-replace-email-routing-settings", "summary": "Update Email Routing settings", "description": "Update the settings for your Email Routing zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_update_email_routing_settings_properties" } } } }, "responses": { "200": { "description": "Update Email Routing settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_email_settings_response_single" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.email.routing.config.update" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/email/routing/disable": { "post": { "operationId": "email-routing-settings-disable-email-routing", "summary": "Disable Email Routing", "description": "Disable your Email Routing zone. Also removes additional MX records previously required for Email Routing to work.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": {} } }, "responses": { "200": { "description": "Disable Email Routing response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_email_settings_response_single" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.email.routing.config.update" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing", "x-fern-sdk-method-name": "disable", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation turns off email routing for a zone." } }, "/zones/{zone_id}/email/routing/dns": { "delete": { "operationId": "email-routing-settings-disable-email-routing-dns", "summary": "Disable Email Routing", "description": "Disable your Email Routing zone. Also removes additional MX records previously required for Email Routing to work.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_email_setting_dns_request_body" } } } }, "responses": { "200": { "description": "Disable Email Routing response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_email_settings_response_single" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing.dns", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "email-routing-settings-email-routing-dns-settings", "summary": "Email Routing - DNS settings", "description": "Show the DNS records needed to configure your Email Routing zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } }, { "name": "subdomain", "in": "query", "description": "Deprecated. When supplied, the response shape differs from the documented default and is not modeled in generated SDKs. Do not rely on this parameter.", "schema": { "$ref": "#/components/schemas/email_email_setting_name" }, "deprecated": true } ], "responses": { "200": { "description": "Email Routing - DNS settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_dns_settings_response_collection" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.email.routing.config.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing.dns", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "email-routing-settings-unlock-email-routing-dns", "summary": "Unlock Email Routing", "description": "Unlock MX Records previously locked by Email Routing.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_email_setting_dns_request_body" } } } }, "responses": { "200": { "description": "Unlock Email Routing MX records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_email_settings_response_single" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.email.routing.config.update" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing.dns", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "post": { "operationId": "email-routing-settings-enable-email-routing-dns", "summary": "Enable Email Routing", "description": "Enable you Email Routing zone. Add and lock the necessary MX and SPF records.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_email_setting_dns_request_body" } } } }, "responses": { "200": { "description": "Enable Email Routing response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_email_settings_response_single" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.email.routing.config.update" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing.dns", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/email/routing/enable": { "post": { "operationId": "email-routing-settings-enable-email-routing", "summary": "Enable Email Routing", "description": "Enable you Email Routing zone. Add and lock the necessary MX and SPF records.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": {} } }, "responses": { "200": { "description": "Enable Email Routing response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_email_settings_response_single" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.email.routing.config.update" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing", "x-fern-sdk-method-name": "enable", "x-forge-hidden": true } }, "/zones/{zone_id}/email/routing/rules": { "get": { "operationId": "email-routing-routing-rules-list-routing-rules", "summary": "List routing rules", "description": "Lists existing routing rules.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Maximum number of results per page.", "type": "number", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "enabled", "in": "query", "schema": { "description": "Filter by enabled routing rules.", "type": "boolean", "example": true, "enum": [ true, false ] } } ], "responses": { "200": { "description": "List routing rules response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_rules_response_collection" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing routing rules" ], "x-api-token-group": [ "Email Routing Rules Write", "Email Routing Rules Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.email.routing.rule.list" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing.rules", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "email-routing-routing-rules-create-routing-rule", "summary": "Create routing rule", "description": "Rules consist of a set of criteria for matching emails (such as an email being sent to a specific custom email address) plus a set of actions to take on the email (like forwarding it to a specific destination address). Forward actions require exactly one verified destination address.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_create_rule_properties" } } } }, "responses": { "200": { "description": "Create routing rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_rule_response_single" } } } }, "400": { "description": "Error 2054: Destination address is not verified. A forward action destination address must be verified before it can be used in a rule." }, "422": { "description": "Error 2007: Invalid Input. Forward actions must contain exactly one destination address." } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing routing rules" ], "x-api-token-group": [ "Email Routing Rules Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.email.routing.rule.create" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing.rules", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/email/routing/rules/catch_all": { "get": { "operationId": "email-routing-routing-rules-get-catch-all-rule", "summary": "Get catch-all rule", "description": "Get information on the default catch-all routing rule.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "responses": { "200": { "description": "Get catch-all rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_catch_all_rule_response_single" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing routing rules" ], "x-api-token-group": [ "Email Routing Rules Write", "Email Routing Rules Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.email.routing.rule.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing.rules.catch-alls", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "email-routing-routing-rules-update-catch-all-rule", "summary": "Update catch-all rule", "description": "Enable or disable catch-all routing rule, or change action to forward to a specific destination address. Forward actions require exactly one verified destination address.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_update_catch_all_rule_properties" } } } }, "responses": { "200": { "description": "Update catch-all rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_catch_all_rule_response_single" } } } }, "400": { "description": "Error 2054: Destination address is not verified. A forward action destination address must be verified before it can be used in a rule." }, "422": { "description": "Error 2007: Invalid Input. Forward actions must contain exactly one destination address." } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing routing rules" ], "x-api-token-group": [ "Email Routing Rules Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.email.routing.rule.update" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing.rules.catch-alls", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/email/routing/rules/{rule_identifier}": { "delete": { "operationId": "email-routing-routing-rules-delete-routing-rule", "summary": "Delete routing rule", "description": "Delete a specific routing rule.", "parameters": [ { "name": "rule_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_rule_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "responses": { "200": { "description": "Delete routing rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_rule_response_single" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing routing rules" ], "x-api-token-group": [ "Email Routing Rules Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.email.routing.rule.delete" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing.rules", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "email-routing-routing-rules-get-routing-rule", "summary": "Get routing rule", "description": "Get information for a specific routing rule already created.", "parameters": [ { "name": "rule_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_rule_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "responses": { "200": { "description": "Get routing rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_rule_response_single" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing routing rules" ], "x-api-token-group": [ "Email Routing Rules Write", "Email Routing Rules Read" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.email.routing.rule.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing.rules", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "email-routing-routing-rules-update-routing-rule", "summary": "Update routing rule", "description": "Update actions and matches, or enable/disable specific routing rules. Forward actions require exactly one verified destination address.", "parameters": [ { "name": "rule_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_rule_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_update_rule_properties" } } } }, "responses": { "200": { "description": "Update routing rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_rule_response_single" } } } }, "400": { "description": "Error 2054: Destination address is not verified. A forward action destination address must be verified before it can be used in a rule." }, "422": { "description": "Error 2007: Invalid Input. Forward actions must contain exactly one destination address." } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing routing rules" ], "x-api-token-group": [ "Email Routing Rules Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.email.routing.rule.update" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing.rules", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/email/routing/suppression": { "get": { "operationId": "get_publicListSuppressionZoneRouting", "summary": "List zone email suppressions", "description": "Lists email suppressions for the specified zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "type": "string", "example": "88228822" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 0 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 1000, "minimum": 0 } }, { "name": "order", "in": "query", "schema": { "type": "string", "default": "created_at", "enum": [ "email", "expires_at", "created_at" ] } }, { "name": "direction", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Returns suppressed emails.", "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer", "example": 0 }, "per_page": { "type": "integer", "example": 100 }, "result": { "type": "array", "items": { "properties": { "created_at": { "type": "string", "format": "date-time" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "example": "hard_bounce" }, "zones": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "id", "email", "reason", "created_at", "expires_at" ], "type": "object" } }, "total": { "type": "integer", "example": 1 } }, "required": [ "page", "per_page", "total", "result" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } }, "success": { "type": "boolean", "example": false } }, "required": [ "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing suppressions" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "email.suppressions", "x-fern-sdk-method-name": "listByZone", "x-forge-hidden": true }, "post": { "operationId": "post_publicNewSuppressionZoneRouting", "summary": "Create zone email suppression", "description": "Creates a new email suppression for the specified zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "type": "string", "example": "88228822" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Returns suppression.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] } }, "required": [ "result" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } }, "success": { "type": "boolean", "example": false } }, "required": [ "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing suppressions" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "email.suppressions", "x-fern-sdk-method-name": "createByZone", "x-forge-hidden": true } }, "/zones/{zone_id}/email/routing/suppression/{suppression_id}": { "delete": { "operationId": "delete_publicDeleteSuppressionZoneRouting", "summary": "Delete zone email suppression", "description": "Deletes an email suppression for the specified zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "type": "string", "example": "88228822" } }, { "name": "suppression_id", "in": "path", "required": true, "schema": { "type": "string", "example": "396a5436-d4b0-42a6-b3fc-48e8fa522321" } } ], "responses": { "200": { "description": "Deletes suppression.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "404": { "description": "Suppression not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "success": { "type": "boolean", "example": false } }, "required": [ "success", "error" ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing suppressions" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "email.suppressions", "x-fern-sdk-method-name": "deleteByZone", "x-forge-hidden": true }, "get": { "operationId": "get_publicGetSuppressionZoneRouting", "summary": "Get zone email suppression", "description": "Retrieves a single email suppression for the specified zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "type": "string", "example": "88228822" } }, { "name": "suppression_id", "in": "path", "required": true, "schema": { "type": "string", "example": "396a5436-d4b0-42a6-b3fc-48e8fa522321" } } ], "responses": { "200": { "description": "Returns suppression.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "example": "hard_bounce" }, "zones": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "id", "email", "reason", "created_at", "expires_at" ] } }, "required": [ "result" ] } } } }, "404": { "description": "Suppression not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "success": { "type": "boolean", "example": false } }, "required": [ "success", "error" ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing suppressions" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "email.suppressions", "x-fern-sdk-method-name": "getByZone", "x-forge-hidden": true } }, "/zones/{zone_id}/email/routing/unlock": { "post": { "operationId": "email-routing-settings-unlock-email-routing", "summary": "Unlock Email Routing", "description": "Unlock MX records previously locked by Email Routing. Deprecated - use PATCH /zones/{zone_id}/email/routing/dns instead.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_email_setting_dns_request_body" } } } }, "responses": { "200": { "description": "Unlock Email Routing response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_email_settings_response_single" } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Routing settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.email.routing.config.update" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-routing", "x-fern-sdk-method-name": "unlock", "x-forge-hidden": true } }, "/zones/{zone_id}/email/sending/subdomains": { "get": { "operationId": "email-sending-subdomains-list-sending-subdomains", "summary": "List sending subdomains", "description": "Lists all sending-enabled subdomains for the zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "responses": { "200": { "description": "List sending subdomains response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_sending_subdomains_response_collection" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Sending subdomains" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.email.sending.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-sending.subdomains", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "email-sending-subdomains-create-sending-subdomain", "summary": "Create a sending subdomain", "description": "Creates a new sending subdomain or re-enables sending on an existing subdomain that had it disabled. If zone-level Email Sending has not been enabled yet, the zone flag is automatically set when the entitlement is present. A leftmost wildcard such as `*.example.com` is accepted only for accounts with wildcard Email Sending enabled. Wildcard senders share the base domain's DKIM signing identity and `cf-bounce.` return path.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_create_sending_subdomain_properties" } } } }, "responses": { "200": { "description": "Create a sending subdomain response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_sending_subdomain_response_single" } } } }, "403": { "description": "Error 2067: Wildcard Email Sending is not enabled for this account." } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Sending subdomains" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.email.sending.create" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-sending.subdomains", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/email/sending/subdomains/preview": { "post": { "operationId": "email-sending-subdomains-preview-sending-subdomain", "summary": "Preview sending subdomain DNS", "description": "Returns the DNS records that would be created for a sending subdomain, flags which records are missing, and reports any conflicts with existing DNS records. This is a read-only dry-run — no records are created or modified. Use before or after creating a subdomain to check DNS status. A leftmost wildcard requires wildcard Email Sending to be enabled for the account and previews base-scoped DKIM and return-path records.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_create_sending_subdomain_properties" } } } }, "responses": { "200": { "description": "Preview sending subdomain DNS response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_sending_subdomain_preview_response" } } } }, "403": { "description": "Error 2067: Wildcard Email Sending is not enabled for this account." } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Sending subdomains" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.email.sending.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-sending.subdomains", "x-fern-sdk-method-name": "preview", "x-forge-hidden": true } }, "/zones/{zone_id}/email/sending/subdomains/{subdomain_id}": { "delete": { "operationId": "email-sending-subdomains-delete-sending-subdomain", "summary": "Delete a sending subdomain", "description": "Disables sending on a subdomain and removes its DNS records. If routing is still active on the subdomain, only sending is disabled.", "parameters": [ { "name": "subdomain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_sending_subdomain_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "responses": { "200": { "description": "Delete a sending subdomain response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_api-response-single" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Sending subdomains" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.email.sending.delete" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-sending.subdomains", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "email-sending-subdomains-get-sending-subdomain", "summary": "Get a sending subdomain", "description": "Gets information for a specific sending subdomain.", "parameters": [ { "name": "subdomain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_sending_subdomain_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "responses": { "200": { "description": "Get a sending subdomain response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_sending_subdomain_response_single" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Sending subdomains" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.email.sending.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-sending.subdomains", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "email-sending-subdomains-update-sending-subdomain", "summary": "Update a sending subdomain", "description": "Updates the activity-log preview preference for a sending subdomain.", "parameters": [ { "name": "subdomain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_sending_subdomain_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_update_sending_subdomain_properties" } } } }, "responses": { "200": { "description": "Update a sending subdomain response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_sending_subdomain_response_single" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Sending subdomains" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.email.sending.update" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-sending.subdomains", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/email/sending/subdomains/{subdomain_id}/dns": { "get": { "operationId": "email-sending-subdomains-get-sending-subdomain-dns", "summary": "Get sending subdomain DNS records", "description": "Returns the expected DNS records for a sending subdomain.", "parameters": [ { "name": "subdomain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_sending_subdomain_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "responses": { "200": { "description": "Get sending subdomain DNS records response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_dns_settings_response_collection" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Sending subdomains" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.email.sending.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-sending.subdomains.dns", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "email-sending-subdomains-fix-sending-subdomain-dns", "summary": "Fix sending subdomain DNS records", "description": "Idempotently re-applies the sending DNS records (creates missing records, re-applies the email_routing lock on records whose lock has been cleared). Refuses with a 409 if foreign MX, multiple SPF, multiple DMARC, or multiple DKIM records exist at the relevant DNS names — those require manual cleanup.", "parameters": [ { "name": "subdomain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_sending_subdomain_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "responses": { "200": { "description": "Fix sending subdomain DNS records response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_sending_subdomain_dns_status_response" } } } }, "400": { "description": "Error 2028: subdomain_id is not a valid UUID." }, "403": { "description": "Error 2043: zone is admin-locked and cannot be mutated." }, "404": { "description": "Error 2033: sending subdomain not found." }, "409": { "description": "Conflict — manual DNS cleanup required. Errors 2008 (foreign MX), 2026 (multiple SPF), 2027 (multiple DMARC), or a multi-DKIM error." } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Sending subdomains" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.email.sending.create" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-sending.subdomains.dns", "x-fern-sdk-method-name": "fix", "x-forge-hidden": true } }, "/zones/{zone_id}/email/sending/subdomains/{subdomain_id}/dns/status": { "get": { "operationId": "email-sending-subdomains-get-sending-subdomain-dns-status", "summary": "Get sending subdomain DNS status", "description": "Returns the desired DNS records for a sending subdomain along with a live diff against actual DNS state. Use this to detect missing, unlocked, foreign, or multi-record conflicts before deciding whether to call the fix endpoint. For wildcard sending rows, each call also rechecks the governing organizational-domain DMARC policy and reports policy drift that DNS Fix cannot repair.", "parameters": [ { "name": "subdomain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_sending_subdomain_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } } ], "responses": { "200": { "description": "Get sending subdomain DNS status response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_sending_subdomain_dns_status_response" } } } }, "400": { "description": "Error 2028: subdomain_id is not a valid UUID." }, "404": { "description": "Error 2033: sending subdomain not found." } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Sending subdomains" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.email.sending.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-sending.subdomains.dns", "x-fern-sdk-method-name": "get-status", "x-forge-hidden": true } }, "/zones/{zone_id}/email/sending/subdomains/{subdomain_id}/reputation/complaints": { "get": { "operationId": "email-sending-subdomains-get-sending-subdomain-reputation-complaints", "summary": "Get sending subdomain complaint count", "description": "Returns the matched complaint count for a sending subdomain in a half-open time window of up to seven days.", "parameters": [ { "name": "subdomain_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_sending_subdomain_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/email_identifier" } }, { "name": "start_at", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "end_at", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Sending subdomain complaint count response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email_sending_subdomain_reputation_complaints_response" } } } }, "400": { "description": "Error 2028: subdomain_id is not a valid UUID." }, "404": { "description": "Error 2033: sending subdomain not found." }, "422": { "description": "Error 2011: invalid time window." }, "502": { "description": "Error 2045: complaint data is unavailable." } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Email Sending subdomains" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.email.sending.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "email-sending.subdomains.reputation", "x-fern-sdk-method-name": "get-complaints", "x-forge-hidden": true } }, "/zones/{zone_id}/email/sending/suppression": { "get": { "operationId": "get_publicListSuppressionZoneSending", "summary": "List zone email suppressions", "description": "Lists email suppressions for the specified zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "type": "string", "example": "88228822" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 0 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 1000, "minimum": 0 } }, { "name": "order", "in": "query", "schema": { "type": "string", "default": "created_at", "enum": [ "email", "expires_at", "created_at" ] } }, { "name": "direction", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Returns suppressed emails.", "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer", "example": 0 }, "per_page": { "type": "integer", "example": 100 }, "result": { "type": "array", "items": { "properties": { "created_at": { "type": "string", "format": "date-time" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "example": "hard_bounce" }, "zones": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "id", "email", "reason", "created_at", "expires_at" ], "type": "object" } }, "total": { "type": "integer", "example": 1 } }, "required": [ "page", "per_page", "total", "result" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } }, "success": { "type": "boolean", "example": false } }, "required": [ "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Email Sending suppressions" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "email.suppressions", "x-fern-sdk-method-name": "listByZone", "x-forge-hidden": true }, "post": { "operationId": "post_publicNewSuppressionZoneSending", "summary": "Create zone email suppression", "description": "Creates a new email suppression for the specified zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "type": "string", "example": "88228822" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Returns suppression.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] } }, "required": [ "result" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } }, "success": { "type": "boolean", "example": false } }, "required": [ "success", "errors" ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Email Sending suppressions" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "email.suppressions", "x-fern-sdk-method-name": "createByZone", "x-forge-hidden": true } }, "/zones/{zone_id}/email/sending/suppression/{suppression_id}": { "delete": { "operationId": "delete_publicDeleteSuppressionZoneSending", "summary": "Delete zone email suppression", "description": "Deletes an email suppression for the specified zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "type": "string", "example": "88228822" } }, { "name": "suppression_id", "in": "path", "required": true, "schema": { "type": "string", "example": "396a5436-d4b0-42a6-b3fc-48e8fa522321" } } ], "responses": { "200": { "description": "Deletes suppression.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "404": { "description": "Suppression not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "success": { "type": "boolean", "example": false } }, "required": [ "success", "error" ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Email Sending suppressions" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "email.suppressions", "x-fern-sdk-method-name": "deleteByZone", "x-forge-hidden": true }, "get": { "operationId": "get_publicGetSuppressionZoneSending", "summary": "Get zone email suppression", "description": "Retrieves a single email suppression for the specified zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "type": "string", "example": "88228822" } }, { "name": "suppression_id", "in": "path", "required": true, "schema": { "type": "string", "example": "396a5436-d4b0-42a6-b3fc-48e8fa522321" } } ], "responses": { "200": { "description": "Returns suppression.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "example": "hard_bounce" }, "zones": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "id", "email", "reason", "created_at", "expires_at" ] } }, "required": [ "result" ] } } } }, "404": { "description": "Suppression not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "success": { "type": "boolean", "example": false } }, "required": [ "success", "error" ] } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Email Sending suppressions" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "email.suppressions", "x-fern-sdk-method-name": "getByZone", "x-forge-hidden": true } }, "/zones/{zone_id}/entitlements": { "get": { "operationId": "entitlements-get-zone-entitlements", "summary": "Get Zone Entitlements", "description": "Returns the list of entitlements (features and their allocations) for a given zone. Each entitlement describes a product feature the zone is permitted to use and the allocation value (boolean, count, range, enum, or string) that governs its behaviour.\n", "parameters": [ { "name": "zone_id", "in": "path", "description": "Identifier of the zone.", "required": true, "schema": { "$ref": "#/components/schemas/entitlements_identifier" } } ], "responses": { "200": { "description": "List of entitlements for the zone.", "content": { "application/json": { "examples": { "success": { "summary": "Zone entitlements with mixed allocation types", "value": { "errors": [], "messages": [], "result": [ { "allocation": { "type": "max_count", "value": 3 }, "created_date": "2021-09-17T20:33:36.000000", "deleted_date": "", "edited_date": "2021-09-17T20:34:01.000000", "feature": { "feature_set": "page_rules", "id": 1, "key": "page_rules", "name": "Page Rules" }, "id": "page_rules" }, { "allocation": { "type": "bool", "value": true }, "created_date": "2021-09-17T20:39:02.000000", "deleted_date": "", "edited_date": "2021-09-17T20:39:11.000000", "feature": { "feature_set": "argo", "id": 38, "key": "argo.allow_tiered_caching", "name": "Argo Tiered Cache" }, "id": "argo.allow_tiered_caching" }, { "allocation": { "type": "enum_number", "value": [ 10, 60, 600, 3600 ] }, "created_date": "2021-09-17T20:47:36.000000", "deleted_date": "", "edited_date": "2021-09-17T20:47:43.000000", "feature": { "feature_set": "rate_limiting", "id": 32, "key": "rate_limiting.sampling_period_secs", "name": "rate_limiting.sampling_period_secs" }, "id": "rate_limiting.sampling_period_secs" } ], "success": true } } }, "schema": { "$ref": "#/components/schemas/entitlements_entitlements_response" } } } }, "204": { "description": "Request canceled by the client before the upstream could respond. No response body.\n" }, "400": { "description": "Bad request — invalid zone identifier or object type.", "content": { "application/json": { "examples": { "invalid_object_type": { "summary": "Invalid object type", "value": { "errors": [ { "code": 2005, "message": "failed to fetch entitlements: invalid object type" } ], "messages": [], "result": null, "success": false } } }, "schema": { "$ref": "#/components/schemas/entitlements_api_response_failure" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/entitlements_api_response_failure" } } } }, "403": { "description": "Insufficient permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/entitlements_api_response_failure" } } } }, "404": { "description": "Zone not found or unknown route.", "content": { "application/json": { "examples": { "not_found": { "summary": "Unknown route", "value": { "errors": [ { "code": 2004, "message": "failed to fetch entitlements: unknown route" } ], "messages": [], "result": null, "success": false } } }, "schema": { "$ref": "#/components/schemas/entitlements_api_response_failure" } } } }, "405": { "description": "HTTP method not allowed.", "content": { "application/json": { "examples": { "method_not_allowed": { "summary": "Method not allowed", "value": { "errors": [ { "code": 2001, "message": "failed to fetch entitlements: method not allowed" } ], "messages": [], "result": null, "success": false } } }, "schema": { "$ref": "#/components/schemas/entitlements_api_response_failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Internal server error", "value": { "errors": [ { "code": 2000, "message": "failed to fetch entitlements: internal server error" } ], "messages": [], "result": null, "success": false } } }, "schema": { "$ref": "#/components/schemas/entitlements_api_response_failure" } } } }, "503": { "description": "Upstream entitlements service unavailable or timed out.", "content": { "application/json": { "examples": { "timeout": { "summary": "Upstream timeout", "value": { "errors": [ { "code": 2003, "message": "failed to fetch entitlements: timeout occurred" } ], "messages": [], "result": null, "success": false } } }, "schema": { "$ref": "#/components/schemas/entitlements_api_response_failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Entitlements" ], "x-api-token-group": [ "Zone Read" ] } }, "/zones/{zone_id}/environments": { "get": { "operationId": "zonesEnvironmentsList", "summary": "List zone environments", "description": "Lists configured environments for a zone.", "responses": { "200": { "description": "Successfully listed zone environments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/kamino_environments_response" } } } }, "4XX": { "$ref": "#/components/responses/kamino_client_error" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Environments" ], "x-api-token-group": [ "Zone Versioning Write", "Zone Versioning Read" ], "x-fern-availability": "generally-available", "x-fern-ignore": true, "x-fern-sdk-group-name": "zones.environments", "x-fern-sdk-method-name": "list" }, "parameters": [ { "$ref": "#/components/parameters/kamino_zone_id" } ], "patch": { "operationId": "zonesEnvironmentsEdit", "summary": "Partially update zone environments", "description": "Applies partial updates to zone environments.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/kamino_environments_request" } } } }, "responses": { "200": { "description": "Successfully updated zone environments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/kamino_environments_response" } } } }, "4XX": { "$ref": "#/components/responses/kamino_client_error" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Environments" ], "x-api-token-group": [ "Zone Versioning Write" ], "x-fern-availability": "generally-available", "x-fern-ignore": true, "x-fern-sdk-group-name": "zones.environments", "x-fern-sdk-method-name": "edit" }, "post": { "operationId": "zonesEnvironmentsCreate", "summary": "Create zone environments", "description": "Creates environments for a zone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/kamino_environments_request" } } } }, "responses": { "200": { "description": "Successfully created zone environments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/kamino_environments_response" } } } }, "4XX": { "$ref": "#/components/responses/kamino_client_error" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Environments" ], "x-api-token-group": [ "Zone Versioning Write" ], "x-fern-availability": "generally-available", "x-fern-ignore": true, "x-fern-sdk-group-name": "zones.environments", "x-fern-sdk-method-name": "create" }, "put": { "operationId": "zonesEnvironmentsUpdate", "summary": "Upsert zone environments", "description": "Replaces the full environment configuration for a zone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/kamino_environments_request" } } } }, "responses": { "200": { "description": "Successfully upserted zone environments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/kamino_environments_response" } } } }, "4XX": { "$ref": "#/components/responses/kamino_client_error" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Environments" ], "x-api-token-group": [ "Zone Versioning Write" ], "x-fern-availability": "generally-available", "x-fern-ignore": true, "x-fern-sdk-group-name": "zones.environments", "x-fern-sdk-method-name": "update" } }, "/zones/{zone_id}/environments/{environment_id}": { "delete": { "operationId": "zonesEnvironmentsDelete", "summary": "Delete zone environment", "description": "Deletes a zone environment by reference identifier.", "responses": { "200": { "description": "Successfully deleted zone environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/kamino_environments_response" } } } }, "4XX": { "$ref": "#/components/responses/kamino_client_error" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Environments" ], "x-api-token-group": [ "Zone Versioning Write" ], "x-fern-availability": "generally-available", "x-fern-ignore": true, "x-fern-sdk-group-name": "zones.environments", "x-fern-sdk-method-name": "delete" }, "parameters": [ { "$ref": "#/components/parameters/kamino_zone_id" }, { "$ref": "#/components/parameters/kamino_environment_id" } ] }, "/zones/{zone_id}/environments/{environment_id}/purge_cache": { "post": { "operationId": "zone-environment-purge", "summary": "Purge Cached Content by Environment", "description": "Purge cached content scoped to a specific environment. Supports the same purge types as the zone-level endpoint (purge everything, by URL, by tag, host, or prefix).\n\n### Availability and limits\nPlease refer to [purge cache availability and limits documentation page](https://developers.cloudflare.com/cache/how-to/purge-cache/#availability-and-limits).\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-purge_identifier" } }, { "name": "environment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-purge_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "Flex Purge with Hosts": { "summary": "Flex purge example with hosts list", "value": { "hosts": [ "www.example.com", "images.example.com" ] } }, "Flex Purge with Prefixes": { "summary": "Flex purge example with prefixes list", "value": { "prefixes": [ "www.example.com/foo", "images.example.com/bar/baz" ] } }, "Flex Purge with Tags": { "summary": "Flex purge example with tags list", "value": { "tags": [ "a-cache-tag", "another-cache-tag" ] } }, "Purge Everything": { "summary": "Purge everything example", "value": { "purge_everything": true } }, "Single File Purge": { "summary": "Single file purge example with files list", "value": { "files": [ "http://www.example.com/css/styles.css", "http://www.example.com/js/index.js" ] } }, "Single File Purge with UrlAndHeaders": { "summary": "Single file purge example with url and headers list", "value": { "files": [ { "headers": { "Accept-Language": "zh-CN", "CF-Device-Type": "desktop", "CF-IPCountry": "US" }, "url": "http://www.example.com/cat_picture.jpg" }, { "headers": { "Accept-Language": "en-US", "CF-Device-Type": "mobile", "CF-IPCountry": "EU" }, "url": "http://www.example.com/dog_picture.jpg" } ] } } }, "schema": { "anyOf": [ { "$ref": "#/components/schemas/cache-purge_FlexPurgeByTags" }, { "$ref": "#/components/schemas/cache-purge_FlexPurgeByHostnames" }, { "$ref": "#/components/schemas/cache-purge_FlexPurgeByPrefixes" }, { "$ref": "#/components/schemas/cache-purge_Everything" }, { "$ref": "#/components/schemas/cache-purge_SingleFile" }, { "$ref": "#/components/schemas/cache-purge_SingleFileWithUrlAndHeaders" } ] } } } }, "responses": { "200": { "description": "Request to purge cached content successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-purge_api-response-single-id" } } } }, "4XX": { "description": "Request to purge cached content failed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-purge_api-response-single-id" }, { "$ref": "#/components/schemas/cache-purge_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone" ], "x-api-token-group": [ "Cache Purge" ], "x-cfPermissionsRequired": { "enum": [ "#cache_purge:edit" ] }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "cache", "x-fern-sdk-method-name": "purge-environment", "x-forge-hidden": true, "x-forge-require-confirmation": "Are you sure you want to purge cache for this environment?" } }, "/zones/{zone_id}/environments/{environment_id}/rollback": { "parameters": [ { "$ref": "#/components/parameters/kamino_zone_id" }, { "$ref": "#/components/parameters/kamino_environment_id" } ], "post": { "operationId": "zonesEnvironmentsRollback", "summary": "Roll back zone environment", "description": "Rolls a zone environment back to its previous version.", "responses": { "200": { "description": "Successfully rolled back zone environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/kamino_environments_response" } } } }, "4XX": { "$ref": "#/components/responses/kamino_client_error" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Environments" ], "x-api-token-group": [ "Zone Versioning Write" ], "x-fern-availability": "generally-available", "x-fern-ignore": true, "x-fern-sdk-group-name": "zones.environments", "x-fern-sdk-method-name": "rollback" } }, "/zones/{zone_id}/filters": { "delete": { "operationId": "filters-delete-filters", "summary": "Delete filters", "description": "Deletes one or more existing filters.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } }, { "name": "id", "in": "query", "required": true, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/firewall_filters_components-schemas-id" } } } ], "responses": { "200": { "description": "Delete filters response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_filter-delete-response-collection" } } } }, "4XX": { "description": "Delete filters response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-delete-response-collection" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Filters" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.filters", "x-fern-sdk-method-name": "bulk-delete", "x-forge-hidden": true }, "get": { "operationId": "filters-list-filters", "summary": "List filters", "description": "Fetches filters in a zone. You can filter the results using several optional parameters.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } }, { "name": "paused", "in": "query", "schema": { "oneOf": [ { "$ref": "#/components/schemas/firewall_filters_components-schemas-paused" } ] } }, { "name": "expression", "in": "query", "schema": { "description": "A case-insensitive string to find in the expression.", "type": "string", "example": "php" } }, { "name": "description", "in": "query", "schema": { "description": "A case-insensitive string to find in the description.", "type": "string", "example": "browsers" } }, { "name": "ref", "in": "query", "schema": { "description": "The filter ref (a short reference tag) to search for. Must be an exact match.", "type": "string", "example": "FIL-100" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of filters per page.", "type": "number", "default": 25, "maximum": 100, "minimum": 5 } }, { "name": "id", "in": "query", "schema": { "description": "The unique identifier of the filter.", "type": "string", "example": "372e67954025e0ba6aaa6d586b9e0b61", "maxLength": 32, "minLength": 32, "readOnly": true } } ], "responses": { "200": { "description": "List filters response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_filter-response-collection" } } } }, "4XX": { "description": "List filters response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-response-collection" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Filters" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.filters", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "filters-create-filters", "summary": "Create filters", "description": "Creates one or more filters.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/firewall_filter" } } } } }, "responses": { "200": { "description": "Create filters response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-response-collection" } ] } } } }, "4XX": { "description": "Create filters response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-response-collection" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Filters" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.filters", "x-fern-sdk-method-name": "create", "x-forge-hidden": true }, "put": { "operationId": "filters-update-filters", "summary": "Update filters", "description": "Updates one or more existing filters.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/firewall_filter-rule-update-request" } } } } }, "responses": { "200": { "description": "Update filters response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_filter-response-collection" } } } }, "4XX": { "description": "Update filters response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-response-collection" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Filters" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.filters", "x-fern-sdk-method-name": "bulk-update", "x-forge-hidden": true } }, "/zones/{zone_id}/filters/{filter_id}": { "delete": { "operationId": "filters-delete-a-filter", "summary": "Delete a filter", "description": "Deletes an existing filter.", "parameters": [ { "name": "filter_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_filters_components-schemas-id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "responses": { "200": { "description": "Delete a filter response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_filter-delete-response-single" } } } }, "4XX": { "description": "Delete a filter response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-delete-response-single" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Filters" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.filters", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "filters-get-a-filter", "summary": "Get a filter", "description": "Fetches the details of a filter.", "parameters": [ { "name": "filter_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_filters_components-schemas-id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "responses": { "200": { "description": "Get a filter response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_filter-response-single" } } } }, "4XX": { "description": "Get a filter response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-response-single" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Filters" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.filters", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "filters-update-a-filter", "summary": "Update a filter", "description": "Updates an existing filter.", "parameters": [ { "name": "filter_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_filters_components-schemas-id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_filter" } } } }, "responses": { "200": { "description": "Update a filter response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_filter-response-single" } } } }, "4XX": { "description": "Update a filter response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-response-single" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Filters" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.filters", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/firewall/access_rules/rules": { "get": { "operationId": "ip-access-rules-for-a-zone-list-ip-access-rules", "summary": "List IP Access rules", "description": "Fetches IP Access rules of a zone. You can filter the results using several optional parameters.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } }, { "name": "mode", "in": "query", "schema": { "$ref": "#/components/schemas/firewall_schemas-mode" } }, { "name": "configuration.target", "in": "query", "schema": { "description": "The target to search in existing rules.", "type": "string", "example": "ip", "enum": [ "ip", "ip_range", "asn", "country" ] } }, { "name": "configuration.value", "in": "query", "schema": { "description": "The target value to search for in existing rules: an IP address, an IP address range, or a country code, depending on the provided `configuration.target`.\nNotes: You can search for a single IPv4 address, an IP address range with a subnet of '/16' or '/24', or a two-letter ISO-3166-1 alpha-2 country code.", "type": "string", "example": "198.51.100.4" } }, { "name": "notes", "in": "query", "schema": { "description": "The string to search for in the notes of existing IP Access rules.\nNotes: For example, the string 'attack' would match IP Access rules with notes 'Attack 26/02' and 'Attack 27/02'. The search is case insensitive.", "type": "string", "example": "my note" } }, { "name": "match", "in": "query", "schema": { "description": "When set to `all`, all the search requirements must match. When set to `any`, only one of the search requirements has to match.", "type": "string", "default": "all", "enum": [ "any", "all" ] } }, { "name": "page", "in": "query", "schema": { "description": "Requested page within paginated list of results.", "type": "number", "example": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Maximum number of results requested.", "type": "number", "example": 20 } }, { "name": "order", "in": "query", "schema": { "description": "The field used to sort returned rules.", "type": "string", "example": "mode", "enum": [ "configuration.target", "configuration.value", "mode" ] } }, { "name": "direction", "in": "query", "schema": { "description": "The direction used to sort returned rules.", "type": "string", "example": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "List IP Access rules response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_rule_collection_response" } } } }, "4XX": { "description": "List IP Access rules response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_rule_collection_response" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "IP Access rules for a zone" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.zone-access-rules", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "ip-access-rules-for-a-zone-create-an-ip-access-rule", "summary": "Create an IP Access rule", "description": "Creates a new IP Access rule for a zone.\n\nNote: To create an IP Access rule that applies to multiple zones, refer to [IP Access rules for a user](#ip-access-rules-for-a-user) or [IP Access rules for an account](#ip-access-rules-for-an-account) as appropriate.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "configuration": { "$ref": "#/components/schemas/firewall_configuration" }, "mode": { "$ref": "#/components/schemas/firewall_schemas-mode" }, "notes": { "default": "", "anyOf": [ { "$ref": "#/components/schemas/firewall_notes" } ] } }, "required": [ "mode", "configuration" ] } } } }, "responses": { "200": { "description": "Create an IP Access rule response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_rule_single_response" } } } }, "4XX": { "description": "Create an IP Access rule response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_rule_single_response" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "IP Access rules for a zone" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.zone-access-rules", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/firewall/access_rules/rules/{rule_id}": { "delete": { "operationId": "ip-access-rules-for-a-zone-delete-an-ip-access-rule", "summary": "Delete an IP Access rule", "description": "Deletes an IP Access rule defined at the zone level.\n\nOptionally, you can use the `cascade` property to specify that you wish to delete similar rules in other zones managed by the same zone owner.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } }, { "name": "rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_rule_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cascade": { "description": "The level to attempt to delete similar rules defined for other zones with the same owner. The default value is `none`, which will only delete the current rule. Using `basic` will delete rules that match the same action (mode) and configuration, while using `aggressive` will delete rules that match the same configuration.", "type": "string", "default": "none", "enum": [ "none", "basic", "aggressive" ] } } } } } }, "responses": { "200": { "description": "Delete an IP Access rule response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_rule_single_id_response" } } } }, "4XX": { "description": "Delete an IP Access rule response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_rule_single_id_response" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "IP Access rules for a zone" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.zone-access-rules", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes the zone-level IP Access Rule. If cascade is enabled, similar rules in other zones may also be deleted." }, "patch": { "operationId": "ip-access-rules-for-a-zone-update-an-ip-access-rule", "summary": "Update an IP Access rule", "description": "Updates an IP Access rule defined at the zone level. You can only update the rule action (`mode` parameter) and notes.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } }, { "name": "rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_rule_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/firewall_schemas-mode" }, "notes": { "$ref": "#/components/schemas/firewall_notes" } } } } } }, "responses": { "200": { "description": "Update an IP Access rule response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_rule_single_response" } } } }, "4XX": { "description": "Update an IP Access rule response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_rule_single_response" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "IP Access rules for a zone" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.zone-access-rules", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/firewall/lockdowns": { "get": { "operationId": "zone-lockdown-list-zone-lockdown-rules", "summary": "List Zone Lockdown rules", "description": "Fetches Zone Lockdown rules. You can filter the results using several optional parameters.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "description", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_schemas-description_search" } ] } }, { "name": "modified_on", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_modified_on" } ] } }, { "name": "ip", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_ip_search" } ] } }, { "name": "priority", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_schemas-priority" } ] } }, { "name": "uri_search", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_uri_search" } ] } }, { "name": "ip_range_search", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_ip_range_search" } ] } }, { "name": "per_page", "in": "query", "schema": { "description": "The maximum number of results per page. You can only set the value to `1` or to a multiple of 5 such as `5`, `10`, `15`, or `20`.", "type": "number", "default": 20, "maximum": 1000, "minimum": 1 } }, { "name": "created_on", "in": "query", "schema": { "description": "The timestamp of when the rule was created.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true } }, { "name": "description_search", "in": "query", "schema": { "description": "A string to search for in the description of existing rules.", "type": "string", "example": "endpoints" } }, { "name": "ip_search", "in": "query", "schema": { "description": "A single IP address to search for in existing rules.", "type": "string", "example": "1.2.3.4" } } ], "responses": { "200": { "description": "List Zone Lockdown rules response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_zonelockdown_response_collection" } } } }, "4XX": { "description": "List Zone Lockdown rules response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_zonelockdown_response_collection" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Lockdown" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.lockdowns", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "zone-lockdown-create-a-zone-lockdown-rule", "summary": "Create a Zone Lockdown rule", "description": "Creates a new Zone Lockdown rule.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "configurations": { "$ref": "#/components/schemas/firewall_configurations" }, "description": { "$ref": "#/components/schemas/firewall_description" }, "paused": { "$ref": "#/components/schemas/firewall_schemas-paused" }, "priority": { "$ref": "#/components/schemas/firewall_schemas-priority" }, "urls": { "$ref": "#/components/schemas/firewall_urls" } }, "required": [ "urls", "configurations" ] } } } }, "responses": { "200": { "description": "Create a Zone Lockdown rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_zonelockdown_response_single" } } } }, "4XX": { "description": "Create a Zone Lockdown rule response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_zonelockdown_response_single" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Lockdown" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.lockdowns", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/firewall/lockdowns/{lock_downs_id}": { "delete": { "operationId": "zone-lockdown-delete-a-zone-lockdown-rule", "summary": "Delete a Zone Lockdown rule", "description": "Deletes an existing Zone Lockdown rule.", "parameters": [ { "name": "lock_downs_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_lockdowns_components-schemas-id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "responses": { "200": { "description": "Delete a Zone Lockdown rule response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/firewall_lockdowns_components-schemas-id" } } } } } } } }, "4XX": { "description": "Delete a Zone Lockdown rule response failure", "content": { "application/json": { "schema": { "allOf": [ { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/firewall_lockdowns_components-schemas-id" } } } }, "type": "object" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Lockdown" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.lockdowns", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes the Zone Lockdown rule from the zone." }, "get": { "operationId": "zone-lockdown-get-a-zone-lockdown-rule", "summary": "Get a Zone Lockdown rule", "description": "Fetches the details of a Zone Lockdown rule.", "parameters": [ { "name": "lock_downs_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_lockdowns_components-schemas-id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "responses": { "200": { "description": "Get a Zone Lockdown rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_zonelockdown_response_single" } } } }, "4XX": { "description": "Get a Zone Lockdown rule response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_zonelockdown_response_single" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Lockdown" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.lockdowns", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "zone-lockdown-update-a-zone-lockdown-rule", "summary": "Update a Zone Lockdown rule", "description": "Updates an existing Zone Lockdown rule.", "parameters": [ { "name": "lock_downs_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_lockdowns_components-schemas-id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "configurations": { "$ref": "#/components/schemas/firewall_configurations" }, "urls": { "$ref": "#/components/schemas/firewall_urls" } }, "required": [ "urls", "configurations" ] } } } }, "responses": { "200": { "description": "Update a Zone Lockdown rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_zonelockdown_response_single" } } } }, "4XX": { "description": "Update a Zone Lockdown rule response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_zonelockdown_response_single" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Lockdown" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.lockdowns", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/firewall/rules": { "delete": { "operationId": "firewall-rules-delete-firewall-rules", "summary": "Delete firewall rules", "description": "**This endpoint has been deprecated and returns 410 Gone. Please use the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/) instead.**\n\nDeletes existing firewall rules.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/firewall_firewall-rules_components-schemas-id" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Delete firewall rules response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_filter-rules-response-collection-delete" } } } }, "4XX": { "description": "Delete firewall rules response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-rules-response-collection-delete" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Firewall rules" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "firewall.rules", "x-fern-sdk-method-name": "bulk-delete", "x-forge-hidden": true }, "get": { "operationId": "firewall-rules-list-firewall-rules", "summary": "List firewall rules", "description": "**This endpoint has been deprecated and returns 410 Gone. Please use the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/) instead.**\n\nFetches firewall rules in a zone. You can filter the results using several optional parameters.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } }, { "name": "description", "in": "query", "schema": { "description": "A case-insensitive string to find in the description.", "type": "string", "example": "mir" } }, { "name": "action", "in": "query", "schema": { "description": "The action to search for. Must be an exact match.", "type": "string", "example": "block" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of firewall rules per page.", "type": "number", "default": 25, "maximum": 100, "minimum": 5 } }, { "name": "id", "in": "query", "schema": { "description": "The unique identifier of the firewall rule.", "type": "string", "example": "372e67954025e0ba6aaa6d586b9e0b60", "maxLength": 32, "readOnly": true } }, { "name": "paused", "in": "query", "schema": { "description": "When true, indicates that the firewall rule is currently paused.", "type": "boolean", "example": false } } ], "responses": { "200": { "description": "List firewall rules response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_filter-rules-response-collection" } } } }, "4XX": { "description": "List firewall rules response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-rules-response-collection" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Firewall rules" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "firewall.rules", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "patch": { "operationId": "firewall-rules-update-priority-of-firewall-rules", "summary": "Update priority of firewall rules", "description": "**This endpoint has been deprecated and returns 410 Gone. Please use the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/) instead.**\n\nUpdates the priority of existing firewall rules.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id" ] } } } }, "responses": { "200": { "description": "Update priority of firewall rules response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_filter-rules-response-collection" } } } }, "4XX": { "description": "Update priority of firewall rules response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-rules-response-collection" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Firewall rules" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "firewall.rules", "x-fern-sdk-method-name": "bulk-edit", "x-forge-hidden": true }, "post": { "operationId": "firewall-rules-create-firewall-rules", "summary": "Create firewall rules", "description": "**This endpoint has been deprecated and returns 410 Gone. Please use the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/) instead.**\n\nCreate one or more firewall rules.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/firewall_action" }, "filter": { "$ref": "#/components/schemas/firewall_filter" } }, "required": [ "filter", "action" ] } } } }, "responses": { "200": { "description": "Create firewall rules response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_filter-rules-response-collection" } } } }, "4XX": { "description": "Create firewall rules response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-rules-response-collection" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Firewall rules" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "firewall.rules", "x-fern-sdk-method-name": "create", "x-forge-hidden": true }, "put": { "operationId": "firewall-rules-update-firewall-rules", "summary": "Update firewall rules", "description": "**This endpoint has been deprecated and returns 410 Gone. Please use the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/) instead.**\n\nUpdates one or more existing firewall rules.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "id" ] } } } }, "responses": { "200": { "description": "Update firewall rules response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_filter-rules-response-collection" } } } }, "4XX": { "description": "Update firewall rules response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-rules-response-collection" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Firewall rules" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "firewall.rules", "x-fern-sdk-method-name": "bulk-update", "x-forge-hidden": true } }, "/zones/{zone_id}/firewall/rules/{rule_id}": { "delete": { "operationId": "firewall-rules-delete-a-firewall-rule", "summary": "Delete a firewall rule", "description": "**This endpoint has been deprecated and returns 410 Gone. Please use the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/) instead.**\n\nDeletes an existing firewall rule.\n", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_firewall-rules_components-schemas-id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "delete_filter_if_unused": { "$ref": "#/components/schemas/firewall_delete_filter_if_unused" } } } } } }, "responses": { "200": { "description": "Delete a firewall rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_filter-rules-single-response-delete" } } } }, "4XX": { "description": "Delete a firewall rule response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-rules-single-response-delete" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Firewall rules" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "firewall.rules", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "firewall-rules-get-a-firewall-rule", "summary": "Get a firewall rule", "description": "**This endpoint has been deprecated and returns 410 Gone. Please use the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/) instead.**\n\nFetches the details of a firewall rule.\n", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_firewall-rules_components-schemas-id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } }, { "name": "id", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_firewall-rules_components-schemas-id" } ] } } ], "responses": { "200": { "description": "Get a firewall rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_filter-rules-single-response" } } } }, "4XX": { "description": "Get a firewall rule response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-rules-single-response" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Firewall rules" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "firewall.rules", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "firewall-rules-update-priority-of-a-firewall-rule", "summary": "Update priority of a firewall rule", "description": "**This endpoint has been deprecated and returns 410 Gone. Please use the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/) instead.**\n\nUpdates the priority of an existing firewall rule.\n", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_firewall-rules_components-schemas-id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/firewall_components-schemas-identifier" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Update priority of a firewall rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_filter-rules-response-collection" } } } }, "4XX": { "description": "Update priority of a firewall rule response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-rules-response-collection" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Firewall rules" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "firewall.rules", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "firewall-rules-update-a-firewall-rule", "summary": "Update a firewall rule", "description": "**This endpoint has been deprecated and returns 410 Gone. Please use the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/) instead.**\n\nUpdates an existing firewall rule.\n", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_firewall-rules_components-schemas-id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/firewall_action" }, "filter": { "$ref": "#/components/schemas/firewall_filter" }, "id": { "$ref": "#/components/schemas/firewall_components-schemas-identifier" } }, "required": [ "id", "filter", "action" ] } } } }, "responses": { "200": { "description": "Update a firewall rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_filter-rules-single-response" } } } }, "4XX": { "description": "Update a firewall rule response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter-rules-single-response" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Firewall rules" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "firewall.rules", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/firewall/ua_rules": { "get": { "operationId": "user-agent-blocking-rules-list-user-agent-blocking-rules", "summary": "List User Agent Blocking rules", "description": "Fetches User Agent Blocking rules in a zone. You can filter the results using several optional parameters.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "description", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_description_search" } ] } }, { "name": "per_page", "in": "query", "schema": { "description": "The maximum number of results per page. You can only set the value to `1` or to a multiple of 5 such as `5`, `10`, `15`, or `20`.", "type": "number", "default": 20, "maximum": 1000, "minimum": 1 } }, { "name": "user_agent", "in": "query", "schema": { "description": "A string to search for in the user agent values of existing rules.", "type": "string", "example": "Safari" } }, { "name": "paused", "in": "query", "schema": { "description": "When true, indicates that the rule is currently paused.", "type": "boolean", "example": false } } ], "responses": { "200": { "description": "List User Agent Blocking rules response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_firewalluablock_response_collection" } } } }, "4XX": { "description": "List User Agent Blocking rules response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_firewalluablock_response_collection" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "User Agent Blocking rules" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.ua-rules", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "user-agent-blocking-rules-create-a-user-agent-blocking-rule", "summary": "Create a User Agent Blocking rule", "description": "Creates a new User Agent Blocking rule in a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "configuration": { "$ref": "#/components/schemas/firewall_ua_configuration" }, "description": { "$ref": "#/components/schemas/firewall_description" }, "mode": { "$ref": "#/components/schemas/firewall_schemas-mode" }, "paused": { "$ref": "#/components/schemas/firewall_schemas-paused" } }, "required": [ "mode", "configuration" ] } } } }, "responses": { "200": { "description": "Create a User Agent Blocking rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_firewalluablock_response_single" } } } }, "4XX": { "description": "Create a User Agent Blocking rule response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_firewalluablock_response_single" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "User Agent Blocking rules" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.ua-rules", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/firewall/ua_rules/{ua_rule_id}": { "delete": { "operationId": "user-agent-blocking-rules-delete-a-user-agent-blocking-rule", "summary": "Delete a User Agent Blocking rule", "description": "Deletes an existing User Agent Blocking rule.", "parameters": [ { "name": "ua_rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_components-ua-rule-id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "responses": { "200": { "description": "Delete a User Agent Blocking rule response", "content": { "application/json": { "schema": { "allOf": [ { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/firewall_components-ua-rule-id" } } } }, "type": "object" }, { "$ref": "#/components/schemas/firewall_firewalluablock_response_single" } ] } } } }, "4XX": { "description": "Delete a User Agent Blocking rule response failure", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/firewall_firewalluablock_response_single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/firewall_components-ua-rule-id" } } } }, "type": "object" } ] }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "User Agent Blocking rules" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.ua-rules", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes the User Agent Blocking rule from the zone." }, "get": { "operationId": "user-agent-blocking-rules-get-a-user-agent-blocking-rule", "summary": "Get a User Agent Blocking rule", "description": "Fetches the details of a User Agent Blocking rule.", "parameters": [ { "name": "ua_rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_components-ua-rule-id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "responses": { "200": { "description": "Get a User Agent Blocking rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_firewalluablock_response_single" } } } }, "4XX": { "description": "Get a User Agent Blocking rule response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_firewalluablock_response_single" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "User Agent Blocking rules" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.ua-rules", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "user-agent-blocking-rules-update-a-user-agent-blocking-rule", "summary": "Update a User Agent Blocking rule", "description": "Updates an existing User Agent Blocking rule.", "parameters": [ { "name": "ua_rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_components-ua-rule-id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "configuration": { "$ref": "#/components/schemas/firewall_configuration" }, "description": { "$ref": "#/components/schemas/firewall_description" }, "id": { "$ref": "#/components/schemas/firewall_components-schemas-identifier" }, "mode": { "$ref": "#/components/schemas/firewall_schemas-mode" }, "paused": { "$ref": "#/components/schemas/firewall_schemas-paused" } }, "required": [ "id", "mode", "configuration" ] } } } }, "responses": { "200": { "description": "Update a User Agent Blocking rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_firewalluablock_response_single" } } } }, "4XX": { "description": "Update a User Agent Blocking rule response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_firewalluablock_response_single" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "User Agent Blocking rules" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.ua-rules", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/firewall/waf/overrides": { "get": { "operationId": "waf-overrides-list-waf-overrides", "summary": "List WAF overrides", "description": "**This endpoint has been deprecated and returns 410 Gone. Please use the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/) instead.**\n\nPreviously fetched the URI-based WAF overrides in a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } }, { "name": "page", "in": "query", "schema": { "description": "The page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "The number of WAF overrides per page.", "type": "number", "default": 50, "maximum": 100, "minimum": 5 } } ], "responses": { "200": { "description": "List WAF overrides response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_override_response_collection" } } } }, "4XX": { "description": "List WAF overrides response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_override_response_collection" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "WAF overrides" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.waf.overrides", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "waf-overrides-create-a-waf-override", "summary": "Create a WAF override", "description": "**This endpoint has been deprecated and returns 410 Gone. Please use the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/) instead.**\n\nPreviously created a URI-based WAF override for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "urls": { "$ref": "#/components/schemas/firewall_urls" } }, "required": [ "urls" ] } } } }, "responses": { "200": { "description": "Create a WAF override response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_override_response_single" } } } }, "4XX": { "description": "Create a WAF override response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_override_response_single" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "WAF overrides" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.waf.overrides", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/firewall/waf/overrides/{overrides_id}": { "delete": { "operationId": "waf-overrides-delete-a-waf-override", "summary": "Delete a WAF override", "description": "**This endpoint has been deprecated and returns 410 Gone. Please use the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/) instead.**\n\nPreviously deleted an existing URI-based WAF override.", "parameters": [ { "name": "overrides_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_overrides-id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "responses": { "200": { "description": "Delete a WAF override response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/firewall_overrides-id" } } } } } } } }, "4XX": { "description": "Delete a WAF override response failure", "content": { "application/json": { "schema": { "allOf": [ { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/firewall_overrides-id" } } } }, "type": "object" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "WAF overrides" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.waf.overrides", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "waf-overrides-get-a-waf-override", "summary": "Get a WAF override", "description": "**This endpoint has been deprecated and returns 410 Gone. Please use the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/) instead.**\n\nPreviously fetched the details of a URI-based WAF override.", "parameters": [ { "name": "overrides_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_overrides-id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "responses": { "200": { "description": "Get a WAF override response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_override_response_single" } } } }, "4XX": { "description": "Get a WAF override response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_override_response_single" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "WAF overrides" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.waf.overrides", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "waf-overrides-update-waf-override", "summary": "Update WAF override", "description": "**This endpoint has been deprecated and returns 410 Gone. Please use the [Rulesets API](https://developers.cloudflare.com/ruleset-engine/) instead.**\n\nPreviously updated an existing URI-based WAF override.", "parameters": [ { "name": "overrides_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_overrides-id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/firewall_identifier" }, "rewrite_action": { "$ref": "#/components/schemas/firewall_rewrite_action" }, "rules": { "$ref": "#/components/schemas/firewall_rules" }, "urls": { "$ref": "#/components/schemas/firewall_urls" } }, "required": [ "id", "urls", "rules", "rewrite_action" ] } } } }, "responses": { "200": { "description": "Update WAF override response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_override_response_single" } } } }, "4XX": { "description": "Update WAF override response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_override_response_single" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "WAF overrides" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.waf.overrides", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/firewall/waf/packages": { "get": { "operationId": "waf-packages-list-waf-packages", "summary": "List WAF packages", "description": "Fetches WAF packages for a zone.\n\n**Note:** Applies only to the [previous version of WAF managed rules](https://developers.cloudflare.com/support/firewall/managed-rules-web-application-firewall-waf/understanding-waf-managed-rules-web-application-firewall/).", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } }, { "name": "page", "in": "query", "schema": { "description": "The page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "The number of packages per page.", "type": "number", "default": 50, "maximum": 100, "minimum": 5 } }, { "name": "order", "in": "query", "schema": { "description": "The field used to sort returned packages.", "type": "string", "example": "name", "enum": [ "name" ] } }, { "name": "direction", "in": "query", "schema": { "description": "The direction used to sort returned packages.", "type": "string", "example": "desc", "enum": [ "asc", "desc" ] } }, { "name": "match", "in": "query", "schema": { "description": "When set to `all`, all the search requirements must match. When set to `any`, only one of the search requirements has to match.", "type": "string", "default": "all", "enum": [ "any", "all" ] } }, { "name": "name", "in": "query", "schema": { "description": "The name of the WAF package.", "type": "string", "example": "USER", "readOnly": true } } ], "responses": { "200": { "description": "List WAF packages response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_package_response_collection" } } } }, "4XX": { "description": "List WAF packages response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_package_response_collection" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "WAF packages" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.waf.packages", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/zones/{zone_id}/firewall/waf/packages/{package_id}": { "get": { "operationId": "waf-packages-get-a-waf-package", "summary": "Get a WAF package", "description": "Fetches the details of a WAF package.\n\n**Note:** Applies only to the [previous version of WAF managed rules](https://developers.cloudflare.com/support/firewall/managed-rules-web-application-firewall-waf/understanding-waf-managed-rules-web-application-firewall/).", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_package_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "responses": { "200": { "description": "Get a WAF package response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_package_response_single" } } } }, "4XX": { "description": "Get a WAF package response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_package_response_single" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "WAF packages" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "firewall.waf.packages", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "waf-packages-update-a-waf-package", "summary": "Update a WAF package", "description": "Updates a WAF package. You can update the sensitivity and the action of an anomaly detection WAF package.\n\n**Note:** Applies only to the [previous version of WAF managed rules](https://developers.cloudflare.com/support/firewall/managed-rules-web-application-firewall-waf/understanding-waf-managed-rules-web-application-firewall/).", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_package_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action_mode": { "$ref": "#/components/schemas/firewall_action_mode" }, "sensitivity": { "$ref": "#/components/schemas/firewall_sensitivity" } } } } } }, "responses": { "200": { "description": "Update a WAF package response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_package_response_single" }, { "properties": { "result": { "$ref": "#/components/schemas/firewall_anomaly_package" } }, "type": "object" } ] } } } }, "4XX": { "description": "Update a WAF package response failure", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/firewall_package_response_single" }, { "properties": { "result": { "$ref": "#/components/schemas/firewall_anomaly_package" } }, "type": "object" } ] }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "WAF packages" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "firewall.waf.packages", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" } } }, "/zones/{zone_id}/firewall/waf/packages/{package_id}/groups": { "get": { "operationId": "waf-rule-groups-list-waf-rule-groups", "summary": "List WAF rule groups", "description": "Fetches the WAF rule groups in a WAF package.\n\n**Note:** Applies only to the [previous version of WAF managed rules](https://developers.cloudflare.com/support/firewall/managed-rules-web-application-firewall-waf/understanding-waf-managed-rules-web-application-firewall/).", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-managed-rules_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-managed-rules_schemas-identifier" } }, { "name": "mode", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_mode" } ] } }, { "name": "page", "in": "query", "schema": { "description": "Defines the page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Defines the number of rule groups per page.", "type": "number", "default": 50, "maximum": 100, "minimum": 5 } }, { "name": "order", "in": "query", "schema": { "description": "Defines the field used to sort returned rule groups.", "type": "string", "example": "mode", "enum": [ "mode", "rules_count" ] } }, { "name": "direction", "in": "query", "schema": { "description": "Defines the direction used to sort returned rule groups.", "type": "string", "example": "desc", "enum": [ "asc", "desc" ] } }, { "name": "match", "in": "query", "schema": { "description": "Defines the condition for search requirements. When set to `all`, all the search requirements must match. When set to `any`, only one of the search requirements has to match.", "type": "string", "default": "all", "enum": [ "any", "all" ] } }, { "name": "name", "in": "query", "schema": { "description": "Defines the name of the rule group.", "type": "string", "example": "Project Honey Pot", "readOnly": true } }, { "name": "rules_count", "in": "query", "schema": { "description": "Defines the number of rules in the current rule group.", "type": "number", "example": 10, "default": 0, "readOnly": true } } ], "responses": { "200": { "description": "Defines the list WAF rule groups response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-managed-rules_rule_group_response_collection" } } } }, "4XX": { "description": "Defines the list WAF rule groups response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_rule_group_response_collection" }, { "$ref": "#/components/schemas/waf-managed-rules_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "WAF rule groups" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "firewall.waf.packages.groups", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/zones/{zone_id}/firewall/waf/packages/{package_id}/groups/{group_id}": { "get": { "operationId": "waf-rule-groups-get-a-waf-rule-group", "summary": "Get a WAF rule group", "description": "Fetches the details of a WAF rule group.\n\n**Note:** Applies only to the [previous version of WAF managed rules](https://developers.cloudflare.com/support/firewall/managed-rules-web-application-firewall-waf/understanding-waf-managed-rules-web-application-firewall/).", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-managed-rules_identifier" } }, { "name": "package_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-managed-rules_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-managed-rules_schemas-identifier" } } ], "responses": { "200": { "description": "Get a WAF rule group response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-managed-rules_rule_group_response_single" } } } }, "4XX": { "description": "Get a WAF rule group response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_rule_group_response_single" }, { "$ref": "#/components/schemas/waf-managed-rules_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "WAF rule groups" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "firewall.waf.packages.groups", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "waf-rule-groups-update-a-waf-rule-group", "summary": "Update a WAF rule group", "description": "Updates a WAF rule group. You can update the state (`mode` parameter) of a rule group.\n\n**Note:** Applies only to the [previous version of WAF managed rules](https://developers.cloudflare.com/support/firewall/managed-rules-web-application-firewall-waf/understanding-waf-managed-rules-web-application-firewall/).", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-managed-rules_identifier" } }, { "name": "package_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-managed-rules_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-managed-rules_schemas-identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/waf-managed-rules_mode" } } } } } }, "responses": { "200": { "description": "Update a WAF rule group response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-managed-rules_rule_group_response_single" } } } }, "4XX": { "description": "Update a WAF rule group response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_rule_group_response_single" }, { "$ref": "#/components/schemas/waf-managed-rules_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "WAF rule groups" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "firewall.waf.packages.groups", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/firewall/waf/packages/{package_id}/rules": { "get": { "operationId": "waf-rules-list-waf-rules", "summary": "List WAF rules", "description": "Fetches WAF rules in a WAF package.\n\n**Note:** Applies only to the [previous version of WAF managed rules](https://developers.cloudflare.com/support/firewall/managed-rules-web-application-firewall-waf/understanding-waf-managed-rules-web-application-firewall/).", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-managed-rules_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-managed-rules_schemas-identifier" } }, { "name": "mode", "in": "query", "schema": { "description": "Defines the action/mode a rule has been overridden to perform.", "type": "string", "example": "CHL", "enum": [ "DIS", "CHL", "BLK", "SIM" ] } }, { "name": "group_id", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_components-schemas-identifier" } ] } }, { "name": "page", "in": "query", "schema": { "description": "Defines the page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Defines the number of rules per page.", "type": "number", "default": 50, "maximum": 100, "minimum": 5 } }, { "name": "order", "in": "query", "schema": { "description": "Defines the field used to sort returned rules.", "type": "string", "example": "status", "enum": [ "priority", "group_id", "description" ] } }, { "name": "direction", "in": "query", "schema": { "description": "Defines the direction used to sort returned rules.", "type": "string", "example": "desc", "enum": [ "asc", "desc" ] } }, { "name": "match", "in": "query", "schema": { "description": "Defines the search requirements. When set to `all`, all the search requirements must match. When set to `any`, only one of the search requirements has to match.", "type": "string", "default": "all", "enum": [ "any", "all" ] } }, { "name": "description", "in": "query", "schema": { "description": "Defines the public description of the WAF rule.", "type": "string", "example": "SQL injection prevention for SELECT statements", "readOnly": true } }, { "name": "priority", "in": "query", "schema": { "description": "Defines the order in which the individual WAF rule is executed within its rule group.", "type": "string", "readOnly": true } } ], "responses": { "200": { "description": "List WAF rules response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-managed-rules_rule_response_collection" } } } }, "4XX": { "description": "List WAF rules response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_rule_response_collection" }, { "$ref": "#/components/schemas/waf-managed-rules_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "WAF rules" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "firewall.waf.packages.rules", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/zones/{zone_id}/firewall/waf/packages/{package_id}/rules/{rule_id}": { "get": { "operationId": "waf-rules-get-a-waf-rule", "summary": "Get a WAF rule", "description": "Fetches the details of a WAF rule in a WAF package.\n\n**Note:** Applies only to the [previous version of WAF managed rules](https://developers.cloudflare.com/support/firewall/managed-rules-web-application-firewall-waf/understanding-waf-managed-rules-web-application-firewall/).", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-managed-rules_identifier" } }, { "name": "package_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-managed-rules_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-managed-rules_schemas-identifier" } } ], "responses": { "200": { "description": "Get a WAF rule response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-managed-rules_rule_response_single" } } } }, "4XX": { "description": "Get a WAF rule response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_rule_response_single" }, { "$ref": "#/components/schemas/waf-managed-rules_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "WAF rules" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "firewall.waf.packages.rules", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "waf-rules-update-a-waf-rule", "summary": "Update a WAF rule", "description": "Updates a WAF rule. You can only update the mode/action of the rule.\n\n**Note:** Applies only to the [previous version of WAF managed rules](https://developers.cloudflare.com/support/firewall/managed-rules-web-application-firewall-waf/understanding-waf-managed-rules-web-application-firewall/).", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-managed-rules_identifier" } }, { "name": "package_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-managed-rules_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-managed-rules_schemas-identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "description": "Defines the mode/action of the rule when triggered. You must use a value from the `allowed_modes` array of the current rule.", "type": "string", "example": "on", "enum": [ "default", "disable", "simulate", "block", "challenge", "on", "off" ] } } } } } }, "responses": { "200": { "description": "Update a WAF rule response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_rule_response_single" }, { "properties": { "result": { "oneOf": [ { "$ref": "#/components/schemas/waf-managed-rules_anomaly_rule" }, { "$ref": "#/components/schemas/waf-managed-rules_traditional_deny_rule" }, { "$ref": "#/components/schemas/waf-managed-rules_traditional_allow_rule" } ] } }, "type": "object" } ] } } } }, "4XX": { "description": "Update a WAF rule response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_rule_response_single" }, { "properties": { "result": { "oneOf": [ { "$ref": "#/components/schemas/waf-managed-rules_anomaly_rule" }, { "$ref": "#/components/schemas/waf-managed-rules_traditional_deny_rule" }, { "$ref": "#/components/schemas/waf-managed-rules_traditional_allow_rule" } ] } }, "type": "object" }, { "$ref": "#/components/schemas/waf-managed-rules_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "WAF rules" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "firewall.waf.packages.rules", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/fraud_detection/settings": { "get": { "operationId": "fraud-detection-zone-get-settings", "summary": "Get Fraud Detection Settings", "description": "Retrieve Fraud Detection settings for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/fraud_identifier" } } ], "responses": { "200": { "description": "Fraud Detection settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/fraud_fraud_settings_response_body" } } } }, "4XX": { "description": "Fraud Detection settings response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/fraud_fraud_settings_response_body" }, { "$ref": "#/components/schemas/fraud_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Fraud Detection" ], "x-api-token-group": [ "Fraud Detection Read", "Fraud Detection Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "fraud", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "fraud-detection-zone-update-settings", "summary": "Update Fraud Detection Settings", "description": "Update Fraud Detection settings for a zone.\n\nNotes on `username_expressions` behavior:\n- If omitted or set to null, expressions are not modified.\n- If provided as an empty array `[]`, all expressions will be cleared.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/fraud_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "clear_expressions": { "summary": "Leave user_profiles unchanged, clear expressions only", "value": { "username_expressions": [] } }, "configure_auth_status": { "summary": "Configure authentication status codes", "value": { "authentication_settings": { "failure_criteria": { "kind": "status_code", "status_codes": [ 401, 403 ] }, "success_criteria": { "kind": "status_code", "status_codes": [ 200, 201 ] } } } }, "enable_user_profiles": { "summary": "Enable user profiles and set two username extraction expressions", "value": { "user_profiles": "enabled", "username_expressions": [ "http.request.body.form[\"username\"][0]", "lookup_json_string(http.request.body.raw, \"username\")" ] } }, "partial_update_auth_status": { "summary": "Update only success codes, leave failure codes unchanged", "value": { "authentication_settings": { "success_criteria": { "kind": "status_code", "status_codes": [ 200 ] } } } } }, "schema": { "$ref": "#/components/schemas/fraud_fraud_settings" } } } }, "responses": { "200": { "description": "Updated Fraud Detection settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/fraud_fraud_settings_response_body" } } } }, "4XX": { "description": "Update Fraud Detection settings failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/fraud_fraud_settings_response_body" }, { "$ref": "#/components/schemas/fraud_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Fraud Detection" ], "x-api-token-group": [ "Fraud Detection Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "fraud", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/healthchecks": { "get": { "operationId": "health-checks-list-health-checks", "summary": "List Health Checks", "description": "List configured health checks.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/healthchecks_identifier" } }, { "$ref": "#/components/parameters/healthchecks_page" }, { "$ref": "#/components/parameters/healthchecks_per_page" } ], "responses": { "200": { "description": "List Health Checks response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/healthchecks_response_collection" } } } }, "4XX": { "description": "List Health Checks response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/healthchecks_response_collection" }, { "$ref": "#/components/schemas/healthchecks_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Health Checks" ], "x-api-token-group": [ "Health Checks Write", "Health Checks Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "healthchecks", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "health-checks-create-health-check", "summary": "Create Health Check", "description": "Create a new health check.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/healthchecks_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/healthchecks_query_healthcheck" } } } }, "responses": { "200": { "description": "Create Health Check response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/healthchecks_single_response" } } } }, "4XX": { "description": "Create Health Check response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/healthchecks_single_response" }, { "$ref": "#/components/schemas/healthchecks_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Health Checks" ], "x-api-token-group": [ "Health Checks Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "healthchecks", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/healthchecks/preview": { "post": { "operationId": "health-checks-create-preview-health-check", "summary": "Create Preview Health Check", "description": "Create a new preview health check.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/healthchecks_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/healthchecks_query_healthcheck" } } } }, "responses": { "200": { "description": "Create Preview Health Check response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/healthchecks_single_response" } } } }, "4XX": { "description": "Create Preview Health Check response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/healthchecks_single_response" }, { "$ref": "#/components/schemas/healthchecks_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Health Checks" ], "x-api-token-group": [ "Health Checks Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "healthchecks.previews", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/healthchecks/preview/{healthcheck_id}": { "delete": { "operationId": "health-checks-delete-preview-health-check", "summary": "Delete Preview Health Check", "description": "Delete a health check.", "parameters": [ { "name": "healthcheck_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/healthchecks_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/healthchecks_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": {} } }, "responses": { "200": { "description": "Delete Preview Health Check response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/healthchecks_id_response" } } } }, "4XX": { "description": "Delete Preview Health Check response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/healthchecks_id_response" }, { "$ref": "#/components/schemas/healthchecks_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Health Checks" ], "x-api-token-group": [ "Health Checks Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "healthchecks.previews", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "health-checks-health-check-preview-details", "summary": "Health Check Preview Details", "description": "Fetch a single configured health check preview.", "parameters": [ { "name": "healthcheck_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/healthchecks_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/healthchecks_identifier" } } ], "responses": { "200": { "description": "Health Check Preview Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/healthchecks_single_response" } } } }, "4XX": { "description": "Health Check Preview Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/healthchecks_single_response" }, { "$ref": "#/components/schemas/healthchecks_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Health Checks" ], "x-api-token-group": [ "Health Checks Write", "Health Checks Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "healthchecks.previews", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/healthchecks/{healthcheck_id}": { "delete": { "operationId": "health-checks-delete-health-check", "summary": "Delete Health Check", "description": "Delete a health check.", "parameters": [ { "name": "healthcheck_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/healthchecks_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/healthchecks_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": {} } }, "responses": { "200": { "description": "Delete Health Check response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/healthchecks_id_response" } } } }, "4XX": { "description": "Delete Health Check response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/healthchecks_id_response" }, { "$ref": "#/components/schemas/healthchecks_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Health Checks" ], "x-api-token-group": [ "Health Checks Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "healthchecks", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "health-checks-health-check-details", "summary": "Health Check Details", "description": "Fetch a single configured health check.", "parameters": [ { "name": "healthcheck_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/healthchecks_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/healthchecks_identifier" } } ], "responses": { "200": { "description": "Health Check Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/healthchecks_single_response" } } } }, "4XX": { "description": "Health Check Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/healthchecks_single_response" }, { "$ref": "#/components/schemas/healthchecks_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Health Checks" ], "x-api-token-group": [ "Health Checks Write", "Health Checks Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "healthchecks", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "health-checks-patch-health-check", "summary": "Patch Health Check", "description": "Patch a configured health check.", "parameters": [ { "name": "healthcheck_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/healthchecks_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/healthchecks_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/healthchecks_query_healthcheck" } } } }, "responses": { "200": { "description": "Patch Health Check response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/healthchecks_single_response" } } } }, "4XX": { "description": "Patch Health Check response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/healthchecks_single_response" }, { "$ref": "#/components/schemas/healthchecks_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Health Checks" ], "x-api-token-group": [ "Health Checks Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "healthchecks", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "health-checks-update-health-check", "summary": "Update Health Check", "description": "Update a configured health check.", "parameters": [ { "name": "healthcheck_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/healthchecks_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/healthchecks_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/healthchecks_query_healthcheck" } } } }, "responses": { "200": { "description": "Update Health Check response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/healthchecks_single_response" } } } }, "4XX": { "description": "Update Health Check response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/healthchecks_single_response" }, { "$ref": "#/components/schemas/healthchecks_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Health Checks" ], "x-api-token-group": [ "Health Checks Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "healthchecks", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/hold": { "delete": { "operationId": "zones-0-hold-delete", "summary": "Remove Zone Hold", "description": "Stop enforcement of a zone hold on the zone, permanently or temporarily, allowing the\ncreation and activation of zones with this zone's hostname.\nExisting zone holds can be removed from CDN-only zones when `hold_after` is not provided.\nActive holds are automatically disabled when a zone transitions to CDN-only mode.", "parameters": [ { "name": "zone_id", "in": "path", "description": "Zone ID", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier-2" } }, { "name": "hold_after", "in": "query", "description": "If `hold_after` is provided, the hold will be temporarily disabled,\nthen automatically re-enabled by the system at the time specified\nin this RFC3339-formatted timestamp. Otherwise, the hold will be\ndisabled indefinitely. `hold_after` cannot be provided for CDN-only zones.", "schema": { "type": "string" }, "example": "2023-01-31T15:56:36Z" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-single-2" }, { "properties": { "result": { "type": "object", "properties": { "hold": { "type": "boolean", "example": false }, "hold_after": { "type": "string" }, "include_subdomains": { "type": "string", "example": false } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Client Error", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common-failure-2" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Holds" ], "x-api-token-group": [ "Zone Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.holds", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "zones-0-hold-get", "summary": "Get Zone Hold", "description": "Retrieve whether the zone is subject to a zone hold, and metadata about the hold.", "parameters": [ { "name": "zone_id", "in": "path", "description": "Zone ID", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier-2" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-single-2" }, { "properties": { "result": { "type": "object", "properties": { "hold": { "type": "boolean", "example": true }, "hold_after": { "type": "string", "example": "2023-01-31T15:56:36Z" }, "include_subdomains": { "type": "string", "example": false } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Client Error", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common-failure-2" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Holds" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read", "Zero Trust: PII Read", "Zaraz Edit", "Zaraz Read", "Zaraz Admin", "Access: Apps and Policies Revoke", "Access: Apps and Policies Write", "Access: Apps and Policies Read", "Access: Apps and Policies Revoke", "Access: Mutual TLS Certificates Write", "Access: Organizations, Identity Providers, and Groups Write", "Zone Settings Write", "Zone Settings Read", "Zone Read", "DNS Read", "Workers Scripts Write", "Workers Scripts Read", "Zone Write", "Workers Routes Write", "Workers Routes Read", "Stream Write", "Stream Read", "SSL and Certificates Write", "SSL and Certificates Read", "Logs Write", "Logs Read", "Cache Purge", "Page Rules Write", "Page Rules Read", "Load Balancers Write", "Load Balancers Read", "Firewall Services Write", "Firewall Services Read", "DNS Write", "Apps Write", "Analytics Read", "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.holds", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "zones-0-hold-patch", "summary": "Update Zone Hold", "description": "Update the `hold_after` and/or `include_subdomains` values on an existing zone hold.\nThe hold is enabled if the `hold_after` date-time value is in the past.\nExisting zone holds can be removed from CDN-only zones by setting `hold_after` to `null`.\nOther zone hold updates cannot be made on CDN-only zones.\nActive holds are automatically disabled when a zone transitions to CDN-only mode.", "parameters": [ { "name": "zone_id", "in": "path", "description": "Zone ID", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier-2" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hold_after": { "description": "If `hold_after` is provided and future-dated, the hold will be temporarily disabled,\nthen automatically re-enabled by the system at the time specified\nin this RFC3339-formatted timestamp. A past-dated `hold_after` value will have\nno effect on an existing, enabled hold. Providing an empty string will set its value\nto the current time. Providing `null` will disable the hold indefinitely.", "type": "string", "example": "2023-01-31T15:56:36Z", "default": "", "nullable": true }, "include_subdomains": { "description": "If `true`, the zone hold will extend to block any subdomain of the given zone, as well\nas SSL4SaaS Custom Hostnames. For example, a zone hold on a zone with the hostname\n'example.com' and include_subdomains=true will block 'example.com',\n'staging.example.com', 'api.staging.example.com', etc.", "type": "boolean", "example": true, "default": false } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-single-2" }, { "properties": { "result": { "type": "object", "properties": { "hold": { "type": "boolean", "example": false }, "hold_after": { "type": "string" }, "include_subdomains": { "type": "string", "example": false } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Client Error", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common-failure-2" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Holds" ], "x-api-token-group": [ "Zone Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.holds", "x-fern-sdk-method-name": "edit", "x-forge-params": { "hold_after": { "default": null }, "include_subdomains": { "default": null } } }, "post": { "operationId": "zones-0-hold-post", "summary": "Create Zone Hold", "description": "Enforce a zone hold on the zone, blocking the creation and activation of zones with this zone's hostname.\nZone holds cannot be enabled on CDN-only zones.", "parameters": [ { "name": "zone_id", "in": "path", "description": "Zone ID", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier-2" } }, { "name": "include_subdomains", "in": "query", "description": "If provided, the zone hold will extend to block any subdomain of the given zone, as well\nas SSL4SaaS Custom Hostnames. For example, a zone hold on a zone with the hostname\n'example.com' and include_subdomains=true will block 'example.com',\n'staging.example.com', 'api.staging.example.com', etc.", "schema": { "type": "boolean" }, "example": true } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-single-2" }, { "properties": { "result": { "type": "object", "properties": { "hold": { "type": "boolean", "example": true }, "hold_after": { "type": "string", "example": "2023-01-31T15:56:36Z" }, "include_subdomains": { "type": "string", "example": true } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Client Error", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common-failure-2" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Holds" ], "x-api-token-group": [ "Zone Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.holds", "x-fern-sdk-method-name": "create" } }, "/zones/{zone_id}/hold/{zone_name}": { "get": { "operationId": "zones-0-hold-zone-name-get", "summary": "Get Zone Hold by Zone Name", "description": "Retrieve whether a given hostname is subject to a zone hold, and metadata about the hold.\nThis endpoint checks whether the given hostname (or any of its ancestor domains) is blocked\nby an active zone hold. If a hold with `include_subdomains` is active on an ancestor domain,\nthat hold is returned. This endpoint is used internally by SSL/COMS to check hold status\nduring zone activation.", "parameters": [ { "name": "zone_id", "in": "path", "description": "Zone identifier. Consumed by the API gateway for routing; the backend\nhandler does not use this value directly.", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier-2" } }, { "name": "zone_name", "in": "path", "description": "The hostname to check for a zone hold. May be a subdomain (e.g. `subdomain.example.com`)\nor an apex domain (e.g. `example.com`). The service checks the hostname and its ancestor\ndomains for active holds with `include_subdomains` enabled.", "required": true, "schema": { "type": "string", "example": "subdomain.example.com", "maxLength": 253, "pattern": "^([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z]{2,}$" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "hold": { "description": "Whether the hostname is currently subject to a zone hold.", "type": "boolean", "example": true }, "hold_after": { "description": "The RFC3339-formatted timestamp at which the hold will be automatically\nre-enabled, if the hold was temporarily disabled. Null if the hold is\npermanently enabled or not set.", "type": "string", "format": "date-time", "example": "2023-01-31T15:56:36Z", "nullable": true }, "include_subdomains": { "description": "Whether the hold extends to block subdomains of the held zone.", "type": "boolean", "example": false } } } } } }, "4XX": { "description": "Client Error", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common-failure-2" } ] } } } } }, "security": [], "tags": [ "Zone Holds" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read", "Zero Trust: PII Read", "Zaraz Edit", "Zaraz Read", "Zaraz Admin", "Access: Apps and Policies Revoke", "Access: Apps and Policies Write", "Access: Apps and Policies Read", "Access: Apps and Policies Revoke", "Access: Mutual TLS Certificates Write", "Access: Organizations, Identity Providers, and Groups Write", "Zone Settings Write", "Zone Settings Read", "Zone Read", "DNS Read", "Workers Scripts Write", "Workers Scripts Read", "Zone Write", "Workers Routes Write", "Workers Routes Read", "Stream Write", "Stream Read", "SSL and Certificates Write", "SSL and Certificates Read", "Logs Write", "Logs Read", "Cache Purge", "Page Rules Write", "Page Rules Read", "Load Balancers Write", "Load Balancers Read", "Firewall Services Write", "Firewall Services Read", "DNS Write", "Apps Write", "Analytics Read", "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-ignore": true, "x-fern-sdk-group-name": "zones.holds", "x-fern-sdk-method-name": "getByName", "x-forge-hidden": true } }, "/zones/{zone_id}/hostnames/settings/{setting_id}": { "get": { "operationId": "per-hostname-tls-settings-list", "summary": "List TLS setting for hostnames", "description": "List the requested TLS setting for the hostnames under this zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "setting_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_setting_id" } } ], "responses": { "200": { "description": "List per-hostname TLS settings response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_per_hostname_settings_response_collection" } } } }, "4XX": { "description": "List per-hostname TLS settings response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_per_hostname_settings_response_collection" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Per-Hostname TLS Settings" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "hostnames.settings.tls", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/hostnames/settings/{setting_id}/{hostname}": { "delete": { "operationId": "per-hostname-tls-settings-delete", "summary": "Delete TLS setting for hostname", "description": "Delete the tls setting value for the hostname.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "setting_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_setting_id" } }, { "name": "hostname", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname-3" } } ], "responses": { "200": { "description": "Delete TLS setting for hostname response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_per_hostname_settings_response_delete" } } } }, "4XX": { "description": "Delete TLS setting for hostname response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_per_hostname_settings_response_delete" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Per-Hostname TLS Settings" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "hostnames.settings.tls", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "per-hostname-tls-settings-get", "summary": "Get TLS setting for hostname", "description": "Get the requested TLS setting for the hostname.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "setting_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_setting_id" } }, { "name": "hostname", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname-3" } } ], "responses": { "200": { "description": "Get TLS setting for hostname response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_per_hostname_settings_response" } } } }, "4XX": { "description": "Get TLS setting for hostname response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_per_hostname_settings_response" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Per-Hostname TLS Settings" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "hostnames.settings.tls-single", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "per-hostname-tls-settings-put", "summary": "Edit TLS setting for hostname", "description": "Update the tls setting value for the hostname.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "setting_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_setting_id" } }, { "name": "hostname", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname-3" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Edit TLS setting for hostname response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_per_hostname_settings_response" } } } }, "4XX": { "description": "Edit TLS setting for hostname response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_per_hostname_settings_response" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Per-Hostname TLS Settings" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "hostnames.settings.tls", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/intel/sinkholes/{sinkhole_id}/ingresses": { "post": { "operationId": "sinkhole-config-create-ingress", "summary": "Create an ingress rule", "description": "Create a new ingress rule for the specified sinkhole. The CIDR block must be a Cloudflare BYOIP associated with your account. The zone_id must be a zone with the ability to create Spectrum Apps. The sinkhole must belong to the same account as the zone.", "parameters": [ { "$ref": "#/components/parameters/intel-sinkholes_zone_id" }, { "$ref": "#/components/parameters/intel-sinkholes_sinkhole_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/intel-sinkholes_ingress_create_params" } } } }, "responses": { "201": { "description": "Ingress created.", "headers": { "Location": { "description": "URI of the created ingress.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/intel-sinkholes_ingress_single_response" } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/intel-sinkholes_api_response_common_failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Sinkhole Config" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "intel.sinkholes.ingresses", "x-fern-sdk-method-name": "create" } }, "/zones/{zone_id}/intel/sinkholes/{sinkhole_id}/ingresses/{ingress_id}": { "delete": { "operationId": "sinkhole-config-delete-ingress", "summary": "Delete an ingress rule", "description": "Delete the specified ingress rule. The sinkhole must belong to the same account as the zone.", "parameters": [ { "$ref": "#/components/parameters/intel-sinkholes_zone_id" }, { "$ref": "#/components/parameters/intel-sinkholes_sinkhole_id" }, { "$ref": "#/components/parameters/intel-sinkholes_ingress_id" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/intel-sinkholes_api_response_single_empty" } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/intel-sinkholes_api_response_common_failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Sinkhole Config" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "intel.sinkholes.ingresses", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "sinkhole-config-get-ingress", "summary": "Get an ingress rule", "description": "Get the specified ingress rule associated with a sinkhole. The sinkhole must belong to the same account as the zone.", "parameters": [ { "$ref": "#/components/parameters/intel-sinkholes_zone_id" }, { "$ref": "#/components/parameters/intel-sinkholes_sinkhole_id" }, { "$ref": "#/components/parameters/intel-sinkholes_ingress_id" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/intel-sinkholes_ingress_single_response" } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/intel-sinkholes_api_response_common_failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Sinkhole Config" ], "x-api-token-group": [ "Intel Write", "Intel Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "intel.sinkholes.ingresses", "x-fern-sdk-method-name": "get" }, "put": { "operationId": "sinkhole-config-update-ingress", "summary": "Update an ingress rule", "description": "Replaces the specified ingress rule. The sinkhole must belong to the same account as the zone.", "parameters": [ { "$ref": "#/components/parameters/intel-sinkholes_zone_id" }, { "$ref": "#/components/parameters/intel-sinkholes_sinkhole_id" }, { "$ref": "#/components/parameters/intel-sinkholes_ingress_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/intel-sinkholes_ingress_create_params" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/intel-sinkholes_api_response_single_empty" } } } }, "4XX": { "description": "Error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/intel-sinkholes_api_response_common_failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Sinkhole Config" ], "x-api-token-group": [ "Intel Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "intel.sinkholes.ingresses", "x-fern-sdk-method-name": "update" } }, "/zones/{zone_id}/keyless_certificates": { "get": { "operationId": "keyless-ssl-for-a-zone-list-keyless-ssl-configurations", "summary": "List Keyless SSL Configurations", "description": "List all Keyless SSL configurations for a given zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "List Keyless SSL Configurations response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless_response_collection" } } } }, "4XX": { "description": "List Keyless SSL Configurations response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless_response_collection" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Keyless SSL for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "keyless-certificates", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "keyless-ssl-for-a-zone-create-keyless-ssl-configuration", "summary": "Create Keyless SSL Configuration", "description": "Creates a Keyless SSL configuration that allows SSL/TLS termination without exposing private keys to Cloudflare. Keys remain on your infrastructure.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle_method": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_bundle_method" }, "certificate": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate-2" }, "host": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_host" }, "name": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_name_write" }, "port": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_port" }, "tunnel": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless_tunnel" } }, "required": [ "host", "port", "certificate" ] } } } }, "responses": { "200": { "description": "Create Keyless SSL Configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless_response_single" } } } }, "4XX": { "description": "Create Keyless SSL Configuration response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Keyless SSL for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "keyless-certificates", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/keyless_certificates/{keyless_certificate_id}": { "delete": { "operationId": "keyless-ssl-for-a-zone-delete-keyless-ssl-configuration", "summary": "Delete Keyless SSL Configuration", "description": "Removes a Keyless SSL configuration. SSL connections will no longer use the keyless server for cryptographic operations.", "parameters": [ { "name": "keyless_certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Delete Keyless SSL Configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless_response_single_id" } } } }, "4XX": { "description": "Delete Keyless SSL Configuration response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless_response_single_id" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Keyless SSL for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "keyless-certificates", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "keyless-ssl-for-a-zone-get-keyless-ssl-configuration", "summary": "Get Keyless SSL Configuration", "description": "Get details for one Keyless SSL configuration.", "parameters": [ { "name": "keyless_certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Get Keyless SSL Configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless_response_single" } } } }, "4XX": { "description": "Get Keyless SSL Configuration response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Keyless SSL for a Zone" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read", "Zero Trust: PII Read", "Zaraz Edit", "Zaraz Read", "Zaraz Admin", "Access: Apps and Policies Revoke", "Access: Apps and Policies Write", "Access: Apps and Policies Read", "Access: Apps and Policies Revoke", "Access: Mutual TLS Certificates Write", "Access: Organizations, Identity Providers, and Groups Write", "Zone Settings Write", "Zone Settings Read", "Zone Read", "DNS Read", "Workers Scripts Write", "Workers Scripts Read", "Zone Write", "Workers Routes Write", "Workers Routes Read", "Stream Write", "Stream Read", "SSL and Certificates Write", "SSL and Certificates Read", "Logs Write", "Logs Read", "Cache Purge", "Page Rules Write", "Page Rules Read", "Load Balancers Write", "Load Balancers Read", "Firewall Services Write", "Firewall Services Read", "DNS Write", "Apps Write", "Analytics Read", "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "keyless-certificates", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "keyless-ssl-for-a-zone-edit-keyless-ssl-configuration", "summary": "Edit Keyless SSL Configuration", "description": "This will update attributes of a Keyless SSL. Consists of one or more of the following: host,name,port.", "parameters": [ { "name": "keyless_certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_enabled_write" }, "host": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_host" }, "name": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_name_write" }, "port": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_port" }, "tunnel": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless_tunnel" } } } } } }, "responses": { "200": { "description": "Edit Keyless SSL Configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless_response_single" } } } }, "4XX": { "description": "Edit Keyless SSL Configuration response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Keyless SSL for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "keyless-certificates", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/leaked-credential-checks": { "get": { "operationId": "waf-product-api-leaked-credentials-get-status", "summary": "Get the Leaked Credential Checks status for a zone.", "description": "Get the current Leaked Credential Checks status for the zone. While enabled, Cloudflare scans incoming requests for usernames and passwords that were exposed in known data breaches.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } } ], "responses": { "200": { "description": "Get Leaked Credential Checks status response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_response-status" } } } }, "4XX": { "description": "Get Leaked Credential Checks status failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_response-status" }, { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Leaked Credential Checks" ], "x-api-token-group": [ "Zone WAF Write", "Zone WAF Read", "Account WAF Write", "Account WAF Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "leaked-credential-checks", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "waf-product-api-leaked-credentials-set-status", "summary": "Update the Leaked Credential Checks status for a zone.", "description": "Update the Leaked Credential Checks status for the zone, enabling or disabling the detection. While enabled, the detection populates the `cf.waf.credential_check.*` fields, which you can reference in custom rules and rate limiting rules to challenge or block requests carrying compromised credentials.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_status" } } } }, "responses": { "200": { "description": "Update Leaked Credential Checks status response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_response-status" } } } }, "4XX": { "description": "Update Leaked Credential Checks status failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_response-status" }, { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Leaked Credential Checks" ], "x-api-token-group": [ "Zone WAF Write", "Account WAF Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "leaked-credential-checks", "x-fern-sdk-method-name": "update", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation toggles Leaked Credential Checks for a zone." } }, "/zones/{zone_id}/leaked-credential-checks/detections": { "get": { "operationId": "waf-product-api-leaked-credentials-list-detections", "summary": "List the custom detection locations of a zone.", "description": "List the user-defined detection locations configured for Leaked Credential Checks, each with its own identifier. A custom detection location tells the WAF where to find the username and password in requests to your application.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } } ], "responses": { "200": { "description": "List Leaked Credential Checks custom detection locations response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-detection-collection" } } } }, "4XX": { "description": "List Leaked Credential Checks custom detection locations failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-detection-collection" }, { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Leaked Credential Checks" ], "x-api-token-group": [ "Zone WAF Write", "Zone WAF Read", "Account WAF Write", "Account WAF Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "leaked-credential-checks.detections", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "waf-product-api-leaked-credentials-create-detection", "summary": "Create a custom detection location for a zone.", "description": "Create a detection location for credentials that the default scan locations do not cover, using Rules language expressions such as `lookup_json_string(http.request.body.raw, \"user\")`. Only the username expression is required, and Leaked Credential Checks must be enabled on the zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_custom-detection" } } } }, "responses": { "200": { "description": "Create Leaked Credential Checks custom detection location response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-detection" } } } }, "4XX": { "description": "Create Leaked Credential Checks custom detection location failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-detection" }, { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Leaked Credential Checks" ], "x-api-token-group": [ "Zone WAF Write", "Account WAF Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "leaked-credential-checks.detections", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/leaked-credential-checks/detections/{detection_id}": { "delete": { "operationId": "waf-product-api-leaked-credentials-delete-detection", "summary": "Delete a custom detection location from a zone.", "description": "Delete a user-defined detection location, identified by its detection ID. Incoming requests are then scanned using only the default scan locations and the detection locations that remain.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } }, { "name": "detection_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_detection-id" } } ], "responses": { "200": { "description": "Delete Leaked Credential Checks custom detection location response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common" } } } }, "4XX": { "description": "Delete Leaked Credential Checks custom detection location failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Leaked Credential Checks" ], "x-api-token-group": [ "Zone WAF Write", "Account WAF Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "leaked-credential-checks.detections", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes a Leaked Credential Checks custom detection location." }, "get": { "operationId": "waf-product-api-leaked-credentials-get-detection", "summary": "Get a custom detection location of a zone.", "description": "Get the username and password expressions of a single user-defined detection location, identified by its detection ID.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } }, { "name": "detection_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_detection-id" } } ], "responses": { "200": { "description": "Get Leaked Credential Checks custom detection location response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-detection" } } } }, "4XX": { "description": "Get Leaked Credential Checks custom detection location failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-detection" }, { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Leaked Credential Checks" ], "x-api-token-group": [ "Zone WAF Write", "Zone WAF Read", "Account WAF Write", "Account WAF Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "leaked-credential-checks.detections", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "waf-product-api-leaked-credentials-update-detection", "summary": "Update a custom detection location of a zone.", "description": "Update the username and password expressions of an existing detection location, identified by its detection ID. Both expressions are overwritten, so omitting the password expression clears it.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } }, { "name": "detection_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_detection-id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_custom-detection" } } } }, "responses": { "200": { "description": "Update Leaked Credential Checks custom detection location response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-detection" } } } }, "4XX": { "description": "Update Leaked Credential Checks custom detection location failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_response-custom-detection" }, { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Leaked Credential Checks" ], "x-api-token-group": [ "Zone WAF Write", "Account WAF Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "leaked-credential-checks.detections", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/load_balancers": { "get": { "operationId": "load-balancers-list-load-balancers", "summary": "List Load Balancers", "description": "List configured load balancers.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-identifier" } } ], "responses": { "200": { "description": "List Load Balancers response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-response_collection" } } } }, "4XX": { "description": "List Load Balancers response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-response_collection" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancers" ], "x-api-token-group": [ "Load Balancers Write", "Load Balancers Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "load-balancers", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "load-balancers-create-load-balancer", "summary": "Create Load Balancer", "description": "Create a new load balancer.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "adaptive_routing": { "$ref": "#/components/schemas/load-balancing_adaptive_routing" }, "country_pools": { "$ref": "#/components/schemas/load-balancing_country_pools" }, "default_pools": { "$ref": "#/components/schemas/load-balancing_default_pools" }, "description": { "$ref": "#/components/schemas/load-balancing_components-schemas-description" }, "fallback_pool": { "$ref": "#/components/schemas/load-balancing_fallback_pool" }, "location_strategy": { "$ref": "#/components/schemas/load-balancing_location_strategy" }, "name": { "$ref": "#/components/schemas/load-balancing_components-schemas-name" }, "networks": { "$ref": "#/components/schemas/load-balancing_networks" }, "pop_pools": { "$ref": "#/components/schemas/load-balancing_pop_pools" }, "proxied": { "$ref": "#/components/schemas/load-balancing_proxied" }, "random_steering": { "$ref": "#/components/schemas/load-balancing_random_steering" }, "region_pools": { "$ref": "#/components/schemas/load-balancing_region_pools" }, "rules": { "$ref": "#/components/schemas/load-balancing_rules" }, "session_affinity": { "$ref": "#/components/schemas/load-balancing_session_affinity" }, "session_affinity_attributes": { "$ref": "#/components/schemas/load-balancing_session_affinity_attributes" }, "session_affinity_ttl": { "$ref": "#/components/schemas/load-balancing_session_affinity_ttl" }, "steering_policy": { "$ref": "#/components/schemas/load-balancing_steering_policy" }, "ttl": { "$ref": "#/components/schemas/load-balancing_ttl" } }, "required": [ "name", "default_pools", "fallback_pool" ] } } } }, "responses": { "200": { "description": "Create Load Balancer response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-single_response" } } } }, "4XX": { "description": "Create Load Balancer response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-single_response" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancers" ], "x-api-token-group": [ "Load Balancers Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "load-balancers", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/load_balancers/{load_balancer_id}": { "delete": { "operationId": "load-balancers-delete-load-balancer", "summary": "Delete Load Balancer", "description": "Delete a configured load balancer.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-identifier" } }, { "name": "load_balancer_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-identifier" } } ], "responses": { "200": { "description": "Delete Load Balancer response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_components-schemas-id_response" } } } }, "4XX": { "description": "Delete Load Balancer response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_components-schemas-id_response" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancers" ], "x-api-token-group": [ "Load Balancers Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "load-balancers", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "load-balancers-load-balancer-details", "summary": "Load Balancer Details", "description": "Fetch a single configured load balancer.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-identifier" } }, { "name": "load_balancer_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-identifier" } } ], "responses": { "200": { "description": "Load Balancer Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-single_response" } } } }, "4XX": { "description": "Load Balancer Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-single_response" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancers" ], "x-api-token-group": [ "Load Balancers Write", "Load Balancers Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "load-balancers", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "load-balancers-patch-load-balancer", "summary": "Patch Load Balancer", "description": "Apply changes to an existing load balancer, overwriting the supplied properties.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-identifier" } }, { "name": "load_balancer_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "adaptive_routing": { "$ref": "#/components/schemas/load-balancing_adaptive_routing" }, "country_pools": { "$ref": "#/components/schemas/load-balancing_country_pools" }, "default_pools": { "$ref": "#/components/schemas/load-balancing_default_pools" }, "description": { "$ref": "#/components/schemas/load-balancing_components-schemas-description" }, "enabled": { "$ref": "#/components/schemas/load-balancing_components-schemas-enabled" }, "fallback_pool": { "$ref": "#/components/schemas/load-balancing_fallback_pool" }, "location_strategy": { "$ref": "#/components/schemas/load-balancing_location_strategy" }, "name": { "$ref": "#/components/schemas/load-balancing_components-schemas-name" }, "pop_pools": { "$ref": "#/components/schemas/load-balancing_pop_pools" }, "proxied": { "$ref": "#/components/schemas/load-balancing_proxied" }, "random_steering": { "$ref": "#/components/schemas/load-balancing_random_steering" }, "region_pools": { "$ref": "#/components/schemas/load-balancing_region_pools" }, "rules": { "$ref": "#/components/schemas/load-balancing_rules" }, "session_affinity": { "$ref": "#/components/schemas/load-balancing_session_affinity" }, "session_affinity_attributes": { "$ref": "#/components/schemas/load-balancing_session_affinity_attributes" }, "session_affinity_ttl": { "$ref": "#/components/schemas/load-balancing_session_affinity_ttl" }, "steering_policy": { "$ref": "#/components/schemas/load-balancing_steering_policy" }, "ttl": { "$ref": "#/components/schemas/load-balancing_ttl" } } } } } }, "responses": { "200": { "description": "Patch Load Balancer response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-single_response" } } } }, "4XX": { "description": "Patch Load Balancer response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-single_response" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancers" ], "x-api-token-group": [ "Load Balancers Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "load-balancers", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "load-balancers-update-load-balancer", "summary": "Update Load Balancer", "description": "Update a configured load balancer.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-identifier" } }, { "name": "load_balancer_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "adaptive_routing": { "$ref": "#/components/schemas/load-balancing_adaptive_routing" }, "country_pools": { "$ref": "#/components/schemas/load-balancing_country_pools" }, "default_pools": { "$ref": "#/components/schemas/load-balancing_default_pools" }, "description": { "$ref": "#/components/schemas/load-balancing_components-schemas-description" }, "enabled": { "$ref": "#/components/schemas/load-balancing_components-schemas-enabled" }, "fallback_pool": { "$ref": "#/components/schemas/load-balancing_fallback_pool" }, "location_strategy": { "$ref": "#/components/schemas/load-balancing_location_strategy" }, "name": { "$ref": "#/components/schemas/load-balancing_components-schemas-name" }, "networks": { "$ref": "#/components/schemas/load-balancing_networks" }, "pop_pools": { "$ref": "#/components/schemas/load-balancing_pop_pools" }, "proxied": { "$ref": "#/components/schemas/load-balancing_proxied" }, "random_steering": { "$ref": "#/components/schemas/load-balancing_random_steering" }, "region_pools": { "$ref": "#/components/schemas/load-balancing_region_pools" }, "rules": { "$ref": "#/components/schemas/load-balancing_rules" }, "session_affinity": { "$ref": "#/components/schemas/load-balancing_session_affinity" }, "session_affinity_attributes": { "$ref": "#/components/schemas/load-balancing_session_affinity_attributes" }, "session_affinity_ttl": { "$ref": "#/components/schemas/load-balancing_session_affinity_ttl" }, "steering_policy": { "$ref": "#/components/schemas/load-balancing_steering_policy" }, "ttl": { "$ref": "#/components/schemas/load-balancing_ttl" } }, "required": [ "name", "default_pools", "fallback_pool" ] } } } }, "responses": { "200": { "description": "Update Load Balancer response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-single_response" } } } }, "4XX": { "description": "Update Load Balancer response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-single_response" }, { "$ref": "#/components/schemas/load-balancing_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Load Balancers" ], "x-api-token-group": [ "Load Balancers Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "load-balancers", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/logpush/datasets/{dataset_id}/fields": { "get": { "operationId": "get-zones-zone_id-logpush-datasets-dataset_id-fields", "summary": "List fields", "description": "Lists all fields available for a dataset. The response result is. an object with key-value pairs, where keys are field names, and values are descriptions.", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_dataset" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_identifier" } } ], "responses": { "200": { "description": "List fields response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/logpush_logpush_field_response_collection" } } } }, "4XX": { "description": "List fields response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logpush jobs for a zone" ], "x-api-token-group": [ "Logs Read" ], "x-cfPermissionsRequired": { "enum": [ "#logs:read" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logpush.datasets.fields", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/logpush/datasets/{dataset_id}/jobs": { "get": { "operationId": "get-zones-zone_id-logpush-datasets-dataset_id-jobs", "summary": "List Logpush jobs for a dataset", "description": "Lists Logpush jobs for a zone for a dataset.", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_dataset" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_identifier" } } ], "responses": { "200": { "description": "List Logpush jobs for a dataset response.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": [ { "dataset": "http_requests", "destination_conf": "s3://mybucket/logs?region=us-west-2", "enabled": false, "error_message": null, "filter": "{\"where\":{\"and\":[{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/static\"},{\"key\":\"ClientRequestHost\",\"operator\":\"eq\",\"value\":\"example.com\"}]}}", "id": 1, "kind": "", "last_complete": null, "last_error": null, "max_upload_bytes": 5000000, "max_upload_interval_seconds": 30, "max_upload_records": 1000, "name": "example.com", "output_options": { "CVE-2021-44228": false, "batch_prefix": "", "batch_suffix": "", "field_delimiter": ",", "field_names": [ "Datetime", "DstIP", "SrcIP" ], "output_type": "ndjson", "record_delimiter": "", "record_prefix": "{", "record_suffix": "}\n", "sample_rate": 1, "timestamp_format": "unixnano" } } ], "success": true }, "schema": { "$ref": "#/components/schemas/logpush_logpush_job_response_collection" } } } }, "4XX": { "description": "List Logpush jobs for a dataset response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logpush jobs for a zone" ], "x-api-token-group": [ "Logs Write" ], "x-cfPermissionsRequired": { "enum": [ "#logs:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logpush.datasets.jobs", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/logpush/edge/jobs": { "get": { "operationId": "get-zones-zone_id-logpush-edge-jobs", "summary": "List Instant Logs jobs", "description": "Lists Instant Logs jobs for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_identifier" } } ], "responses": { "200": { "description": "List Instant Logs jobs response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/logpush_instant_logs_job_response_collection" } } } }, "4XX": { "description": "List Instant Logs jobs response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logpush_instant_logs_job_response_collection" }, { "$ref": "#/components/schemas/logpush_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Instant Logs jobs for a zone" ], "x-api-token-group": [ "Logs Read" ], "x-cfPermissionsRequired": { "enum": [ "#logs:read" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logpush.edge", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "post-zones-zone_id-logpush-edge-jobs", "summary": "Create Instant Logs job", "description": "Creates a new Instant Logs job for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "$ref": "#/components/schemas/logpush_fields" }, "filter": { "$ref": "#/components/schemas/logpush_filter-2" }, "sample": { "$ref": "#/components/schemas/logpush_sample" } } } } } }, "responses": { "200": { "description": "Create Instant Logs job response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/logpush_instant_logs_job_response_single" } } } }, "4XX": { "description": "Create Instant Logs job response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logpush_instant_logs_job_response_single" }, { "$ref": "#/components/schemas/logpush_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Instant Logs jobs for a zone" ], "x-api-token-group": [ "Logs Read" ], "x-cfPermissionsRequired": { "enum": [ "#logs:read" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logpush.edge", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/logpush/jobs": { "get": { "operationId": "get-zones-zone_id-logpush-jobs", "summary": "List Logpush jobs", "description": "Lists Logpush jobs for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_identifier" } } ], "responses": { "200": { "description": "List Logpush jobs response.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": [ { "dataset": "http_requests", "destination_conf": "s3://mybucket/logs?region=us-west-2", "enabled": false, "error_message": null, "filter": "{\"where\":{\"and\":[{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/static\"},{\"key\":\"ClientRequestHost\",\"operator\":\"eq\",\"value\":\"example.com\"}]}}", "id": 1, "kind": "", "last_complete": null, "last_error": null, "max_upload_bytes": 5000000, "max_upload_interval_seconds": 30, "max_upload_records": 1000, "name": "example.com", "output_options": { "CVE-2021-44228": false, "batch_prefix": "", "batch_suffix": "", "field_delimiter": ",", "field_names": [ "Datetime", "DstIP", "SrcIP" ], "output_type": "ndjson", "record_delimiter": "", "record_prefix": "{", "record_suffix": "}\n", "sample_rate": 1, "timestamp_format": "unixnano" } } ], "success": true }, "schema": { "$ref": "#/components/schemas/logpush_logpush_job_response_collection" } } } }, "4XX": { "description": "List Logpush jobs response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logpush jobs for a zone" ], "x-api-token-group": [ "Logs Write" ], "x-cfPermissionsRequired": { "enum": [ "#logs:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logpush.jobs", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "post-zones-zone_id-logpush-jobs", "summary": "Create Logpush job", "description": "Creates a new Logpush job for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "dataset": "http_requests", "destination_conf": "s3://mybucket/logs?region=us-west-2", "enabled": false, "filter": "{\"where\":{\"and\":[{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/static\"},{\"key\":\"ClientRequestHost\",\"operator\":\"eq\",\"value\":\"example.com\"}]}}", "kind": "", "max_upload_bytes": 5000000, "max_upload_interval_seconds": 30, "max_upload_records": 1000, "name": "example.com", "output_options": { "CVE-2021-44228": false, "batch_prefix": "", "batch_suffix": "", "field_delimiter": ",", "field_names": [ "RayID", "ClientIP", "EdgeStartTimestamp" ], "output_type": "ndjson", "record_delimiter": "", "record_prefix": "{", "record_suffix": "}\n", "sample_rate": 1, "timestamp_format": "unixnano" }, "ownership_challenge": "00000000000000000000" }, "schema": { "type": "object", "properties": { "dataset": { "$ref": "#/components/schemas/logpush_dataset" }, "destination_conf": { "$ref": "#/components/schemas/logpush_destination_conf" }, "enabled": { "$ref": "#/components/schemas/logpush_enabled" }, "filter": { "$ref": "#/components/schemas/logpush_filter" }, "filter_attack_traffic": { "$ref": "#/components/schemas/logpush_filter_attack_traffic" }, "frequency": { "$ref": "#/components/schemas/logpush_frequency" }, "kind": { "$ref": "#/components/schemas/logpush_kind" }, "logpull_options": { "$ref": "#/components/schemas/logpush_logpull_options" }, "max_upload_bytes": { "$ref": "#/components/schemas/logpush_max_upload_bytes" }, "max_upload_interval_seconds": { "$ref": "#/components/schemas/logpush_max_upload_interval_seconds" }, "max_upload_records": { "$ref": "#/components/schemas/logpush_max_upload_records" }, "name": { "$ref": "#/components/schemas/logpush_name" }, "output_options": { "$ref": "#/components/schemas/logpush_output_options" }, "ownership_challenge": { "$ref": "#/components/schemas/logpush_ownership_challenge" } }, "required": [ "destination_conf" ] } } } }, "responses": { "200": { "description": "Create Logpush job response.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": { "dataset": "http_requests", "destination_conf": "s3://mybucket/logs?region=us-west-2", "enabled": false, "error_message": null, "filter": "{\"where\":{\"and\":[{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/static\"},{\"key\":\"ClientRequestHost\",\"operator\":\"eq\",\"value\":\"example.com\"}]}}", "id": 1, "kind": "", "last_complete": null, "last_error": null, "max_upload_bytes": 5000000, "max_upload_interval_seconds": 30, "max_upload_records": 1000, "name": "example.com", "output_options": { "CVE-2021-44228": false, "batch_prefix": "", "batch_suffix": "", "field_delimiter": ",", "field_names": [ "Datetime", "DstIP", "SrcIP" ], "output_type": "ndjson", "record_delimiter": "", "record_prefix": "{", "record_suffix": "}\n", "sample_rate": 1, "timestamp_format": "unixnano" } }, "success": true }, "schema": { "$ref": "#/components/schemas/logpush_logpush_job_response_single" } } } }, "4XX": { "description": "Create Logpush job response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logpush jobs for a zone" ], "x-api-token-group": [ "Logs Write" ], "x-cfPermissionsRequired": { "enum": [ "#logs:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logpush.jobs", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/logpush/jobs/{job_id}": { "delete": { "operationId": "delete-zones-zone_id-logpush-jobs-job_id", "summary": "Delete Logpush job", "description": "Deletes a Logpush job.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_identifier" } } ], "responses": { "200": { "description": "Delete Logpush job response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/logpush_id" } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Delete Logpush job response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logpush jobs for a zone" ], "x-api-token-group": [ "Logs Write" ], "x-cfPermissionsRequired": { "enum": [ "#logs:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logpush.jobs", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes the Logpush job." }, "get": { "operationId": "get-zones-zone_id-logpush-jobs-job_id", "summary": "Get Logpush job details", "description": "Gets the details of a Logpush job.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_identifier" } } ], "responses": { "200": { "description": "Get Logpush job details response.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": { "dataset": "http_requests", "destination_conf": "s3://mybucket/logs?region=us-west-2", "enabled": false, "error_message": null, "filter": "{\"where\":{\"and\":[{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/static\"},{\"key\":\"ClientRequestHost\",\"operator\":\"eq\",\"value\":\"example.com\"}]}}", "id": 1, "kind": "", "last_complete": null, "last_error": null, "max_upload_bytes": 5000000, "max_upload_interval_seconds": 30, "max_upload_records": 1000, "name": "example.com", "output_options": { "CVE-2021-44228": false, "batch_prefix": "", "batch_suffix": "", "field_delimiter": ",", "field_names": [ "Datetime", "DstIP", "SrcIP" ], "output_type": "ndjson", "record_delimiter": "", "record_prefix": "{", "record_suffix": "}\n", "sample_rate": 1, "timestamp_format": "unixnano" } }, "success": true }, "schema": { "$ref": "#/components/schemas/logpush_logpush_job_response_single" } } } }, "4XX": { "description": "Get Logpush job details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logpush jobs for a zone" ], "x-api-token-group": [ "Logs Write" ], "x-cfPermissionsRequired": { "enum": [ "#logs:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logpush.jobs", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "put-zones-zone_id-logpush-jobs-job_id", "summary": "Update Logpush job", "description": "Updates a Logpush job.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "destination_conf": "s3://mybucket/logs?region=us-west-2", "enabled": false, "filter": "{\"where\":{\"and\":[{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/static\"},{\"key\":\"ClientRequestHost\",\"operator\":\"eq\",\"value\":\"example.com\"}]}}", "kind": "", "max_upload_bytes": 5000000, "max_upload_interval_seconds": 30, "max_upload_records": 1000, "output_options": { "CVE-2021-44228": false, "batch_prefix": "", "batch_suffix": "", "field_delimiter": ",", "field_names": [ "RayID", "ClientIP", "EdgeStartTimestamp" ], "output_type": "ndjson", "record_delimiter": "", "record_prefix": "{", "record_suffix": "}\n", "sample_rate": 1, "timestamp_format": "unixnano" }, "ownership_challenge": "00000000000000000000" }, "schema": { "type": "object", "properties": { "destination_conf": { "$ref": "#/components/schemas/logpush_destination_conf" }, "enabled": { "$ref": "#/components/schemas/logpush_enabled" }, "filter": { "$ref": "#/components/schemas/logpush_filter" }, "filter_attack_traffic": { "$ref": "#/components/schemas/logpush_filter_attack_traffic" }, "frequency": { "$ref": "#/components/schemas/logpush_frequency" }, "kind": { "$ref": "#/components/schemas/logpush_kind" }, "logpull_options": { "$ref": "#/components/schemas/logpush_logpull_options" }, "max_upload_bytes": { "$ref": "#/components/schemas/logpush_max_upload_bytes" }, "max_upload_interval_seconds": { "$ref": "#/components/schemas/logpush_max_upload_interval_seconds" }, "max_upload_records": { "$ref": "#/components/schemas/logpush_max_upload_records" }, "name": { "$ref": "#/components/schemas/logpush_name" }, "output_options": { "$ref": "#/components/schemas/logpush_output_options" }, "ownership_challenge": { "$ref": "#/components/schemas/logpush_ownership_challenge" } } } } } }, "responses": { "200": { "description": "Update Logpush job response.", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": { "dataset": "http_requests", "destination_conf": "s3://mybucket/logs?region=us-west-2", "enabled": false, "error_message": null, "filter": "{\"where\":{\"and\":[{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/static\"},{\"key\":\"ClientRequestHost\",\"operator\":\"eq\",\"value\":\"example.com\"}]}}", "id": 1, "kind": "", "last_complete": null, "last_error": null, "max_upload_bytes": 5000000, "max_upload_interval_seconds": 30, "max_upload_records": 1000, "name": "example.com", "output_options": { "CVE-2021-44228": false, "batch_prefix": "", "batch_suffix": "", "field_delimiter": ",", "field_names": [ "Datetime", "DstIP", "SrcIP" ], "output_type": "ndjson", "record_delimiter": "", "record_prefix": "{", "record_suffix": "}\n", "sample_rate": 1, "timestamp_format": "unixnano" } }, "success": true }, "schema": { "$ref": "#/components/schemas/logpush_logpush_job_response_single" } } } }, "4XX": { "description": "Update Logpush job response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logpush jobs for a zone" ], "x-api-token-group": [ "Logs Write" ], "x-cfPermissionsRequired": { "enum": [ "#logs:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logpush.jobs", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/logpush/ownership": { "post": { "operationId": "post-zones-zone_id-logpush-ownership", "summary": "Get ownership challenge", "description": "Gets a new ownership challenge sent to your destination.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destination_conf": { "$ref": "#/components/schemas/logpush_destination_conf" } }, "required": [ "destination_conf" ] } } } }, "responses": { "200": { "description": "Get ownership challenge response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/logpush_get_ownership_response" } } } }, "4XX": { "description": "Get ownership challenge response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logpush jobs for a zone" ], "x-api-token-group": [ "Logs Write" ], "x-cfPermissionsRequired": { "enum": [ "#logs:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logpush.ownership", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/logpush/ownership/validate": { "post": { "operationId": "post-zones-zone_id-logpush-ownership-validate", "summary": "Validate ownership challenge", "description": "Validates ownership challenge of the destination.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destination_conf": { "$ref": "#/components/schemas/logpush_destination_conf" }, "ownership_challenge": { "$ref": "#/components/schemas/logpush_ownership_challenge" } }, "required": [ "destination_conf", "ownership_challenge" ] } } } }, "responses": { "200": { "description": "Validate ownership challenge response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/logpush_validate_ownership_response" } } } }, "4XX": { "description": "Validate ownership challenge response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logpush jobs for a zone" ], "x-api-token-group": [ "Logs Write" ], "x-cfPermissionsRequired": { "enum": [ "#logs:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logpush.ownership", "x-fern-sdk-method-name": "validate", "x-forge-hidden": true } }, "/zones/{zone_id}/logpush/validate/destination": { "post": { "operationId": "post-zones-zone_id-logpush-validate-destination", "summary": "Validate destination", "description": "Validates destination.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destination_conf": { "$ref": "#/components/schemas/logpush_destination_conf" } }, "required": [ "destination_conf" ] } } } }, "responses": { "200": { "description": "Validate destination response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/logpush_validate_response" } } } }, "4XX": { "description": "Validate destination response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logpush jobs for a zone" ], "x-api-token-group": [ "Logs Write" ], "x-cfPermissionsRequired": { "enum": [ "#logs:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logpush.validate", "x-fern-sdk-method-name": "destination", "x-forge-hidden": true } }, "/zones/{zone_id}/logpush/validate/destination/exists": { "post": { "operationId": "post-zones-zone_id-logpush-validate-destination-exists", "summary": "Check destination exists", "description": "Checks if there is an existing job with a destination.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destination_conf": { "$ref": "#/components/schemas/logpush_destination_conf" } }, "required": [ "destination_conf" ] } } } }, "responses": { "200": { "description": "Check destination exists response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/logpush_destination_exists_response" } } } }, "4XX": { "description": "Check destination exists response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logpush jobs for a zone" ], "x-api-token-group": [ "Logs Write" ], "x-cfPermissionsRequired": { "enum": [ "#logs:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logpush.validate", "x-fern-sdk-method-name": "destination-exists", "x-forge-hidden": true } }, "/zones/{zone_id}/logpush/validate/origin": { "post": { "operationId": "post-zones-zone_id-logpush-validate-origin", "summary": "Validate origin", "description": "Validates logpull origin with logpull_options.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logpush_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "logpull_options": { "$ref": "#/components/schemas/logpush_logpull_options" } }, "required": [ "logpull_options" ] } } } }, "responses": { "200": { "description": "Validate origin response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/logpush_validate_response" } } } }, "4XX": { "description": "Validate origin response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logpush jobs for a zone" ], "x-api-token-group": [ "Logs Write" ], "x-cfPermissionsRequired": { "enum": [ "#logs:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logpush.validate", "x-fern-sdk-method-name": "origin", "x-forge-hidden": true } }, "/zones/{zone_id}/logs/control/retention/flag": { "get": { "operationId": "get-zones-zone_id-logs-control-retention-flag", "summary": "Get log retention flag", "description": "Gets log retention flag for Logpull API.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logcontrol_identifier" } } ], "responses": { "200": { "description": "Get log retention flag response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/logcontrol_retention_flag_response_single" } } } }, "4XX": { "description": "Get log retention flag response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logcontrol_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logs Received" ], "x-api-token-group": [ "Logs Write", "Logs Read" ], "x-cfPermissionsRequired": { "enum": [ "#logs:read", "#analytics:read" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logs.control.retention", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "post-zones-zone_id-logs-control-retention-flag", "summary": "Update log retention flag", "description": "Updates log retention flag for Logpull API.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logcontrol_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/logcontrol_retention_flag" } } } }, "responses": { "200": { "description": "Update log retention flag response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/logcontrol_retention_flag_response_single" } } } }, "4XX": { "description": "Update log retention flag response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logcontrol_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logs Received" ], "x-api-token-group": [ "Logs Write" ], "x-cfPermissionsRequired": { "enum": [ "#logs:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logs.control.retention", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/logs/explorer/datasets": { "get": { "operationId": "zones-logs-explorer-datasets-list", "summary": "List zone datasets", "description": "Returns all Log Explorer datasets configured for the zone.\n\nList responses omit the `fields` property; use the single-dataset\nendpoint to retrieve field configuration.\n", "parameters": [ { "$ref": "#/components/parameters/lex_ZoneID" } ], "responses": { "200": { "description": "The datasets the zone has configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_DatasetSummaryListResponse" } } } }, "400": { "$ref": "#/components/responses/lex_BadRequest-2" }, "403": { "$ref": "#/components/responses/lex_Forbidden-2" }, "404": { "$ref": "#/components/responses/lex_NotFound-2" } }, "security": [ { "api_token": [] } ], "tags": [ "Log Explorer Datasets" ], "x-api-token-group": [ "Logs Write", "Logs Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logexplorer.zone.datasets", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "zones-logs-explorer-datasets-create", "summary": "Create a zone dataset", "description": "Create a new Log Explorer dataset for the zone.\n\nList available zone datasets to see the dataset types and fields you\ncan use.\n\nThe `fields` property is optional. If not specified, all available fields\nwill be enabled.\n\nFor dataset field definitions, see: https://developers.cloudflare.com/logs/logpush/logpush-job/datasets/\n", "parameters": [ { "$ref": "#/components/parameters/lex_ZoneID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_CreateDatasetRequest" } } } }, "responses": { "201": { "description": "Dataset created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_DatasetDetailResponse" } } } }, "400": { "$ref": "#/components/responses/lex_BadRequest-2" }, "403": { "$ref": "#/components/responses/lex_Forbidden-2" }, "404": { "$ref": "#/components/responses/lex_NotFound-2" }, "409": { "$ref": "#/components/responses/lex_Conflict" } }, "security": [ { "api_token": [] } ], "tags": [ "Log Explorer Datasets" ], "x-api-token-group": [ "Logs Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logexplorer.zone.datasets", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/logs/explorer/datasets/available": { "get": { "operationId": "zones-logs-explorer-datasets-available-list", "summary": "List available zone datasets", "description": "Returns all dataset types that this zone can create. Each entry includes\nthe dataset schema and timestamp field.\n\nThe schema shows all possible fields for a dataset. However, not all\nfields may be available for your account. When creating or updating a\ndataset, only fields available to your account can be enabled. If you\nrequest a field that is not available, you will receive an error.\n", "parameters": [ { "$ref": "#/components/parameters/lex_ZoneID" } ], "responses": { "200": { "description": "List of dataset types available to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_AvailableDestinationListResponse" } } } }, "400": { "$ref": "#/components/responses/lex_BadRequest-2" }, "403": { "$ref": "#/components/responses/lex_Forbidden-2" }, "404": { "$ref": "#/components/responses/lex_NotFound-2" } }, "security": [ { "api_token": [] } ], "tags": [ "Log Explorer Datasets" ], "x-api-token-group": [ "Logs Write", "Logs Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logexplorer.zone.datasets", "x-fern-sdk-method-name": "available", "x-forge-hidden": true } }, "/zones/{zone_id}/logs/explorer/datasets/{dataset_id}": { "delete": { "operationId": "zones-logs-explorer-datasets-delete", "summary": "Delete a zone dataset", "description": "Deletes a Log Explorer dataset for the zone. Dataset deletion must not\nbe protected.\n", "parameters": [ { "$ref": "#/components/parameters/lex_ZoneID" }, { "$ref": "#/components/parameters/lex_DatasetID" } ], "responses": { "202": { "description": "Dataset deletion accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_DatasetDetailResponse" } } } }, "400": { "$ref": "#/components/responses/lex_BadRequest-2" }, "403": { "$ref": "#/components/responses/lex_Forbidden-2" }, "404": { "$ref": "#/components/responses/lex_NotFound-2" }, "409": { "$ref": "#/components/responses/lex_Conflict" } }, "security": [ { "api_token": [] } ], "tags": [ "Log Explorer Datasets" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logexplorer.zone.datasets", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes a Log Explorer dataset for the zone." }, "get": { "operationId": "zones-logs-explorer-datasets-get", "summary": "Get a zone dataset", "description": "Retrieve a single Log Explorer dataset by ID for the zone.", "parameters": [ { "$ref": "#/components/parameters/lex_ZoneID" }, { "$ref": "#/components/parameters/lex_DatasetID" } ], "responses": { "200": { "description": "Dataset details, including the fields active for ingestion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_DatasetDetailResponse" } } } }, "400": { "$ref": "#/components/responses/lex_BadRequest-2" }, "403": { "$ref": "#/components/responses/lex_Forbidden-2" }, "404": { "$ref": "#/components/responses/lex_NotFound-2" } }, "security": [ { "api_token": [] } ], "tags": [ "Log Explorer Datasets" ], "x-api-token-group": [ "Logs Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logexplorer.zone.datasets", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "zones-logs-explorer-datasets-update", "summary": "Update a zone dataset", "description": "Updates the enabled state and/or field configuration of a zone dataset.", "parameters": [ { "$ref": "#/components/parameters/lex_ZoneID" }, { "$ref": "#/components/parameters/lex_DatasetID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_UpdateDatasetRequest" } } } }, "responses": { "200": { "description": "The dataset after the update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_DatasetDetailResponse" } } } }, "400": { "$ref": "#/components/responses/lex_BadRequest-2" }, "403": { "$ref": "#/components/responses/lex_Forbidden-2" }, "404": { "$ref": "#/components/responses/lex_NotFound-2" } }, "security": [ { "api_token": [] } ], "tags": [ "Log Explorer Datasets" ], "x-api-token-group": [ "Logs Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logexplorer.zone.datasets", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/logs/explorer/query/sql": { "get": { "operationId": "zones-logs-explorer-query-get", "summary": "Run a log query", "description": "Run a SQL query against zone-level datasets. The SQL query is passed as the `query` query parameter. Because the query appears in the URL, it is subject to gateway and proxy URL-length limits and may be recorded in access logs. This endpoint is deprecated in favour of the POST variant which sends the query in the request body.", "parameters": [ { "$ref": "#/components/parameters/lex_ZoneID" }, { "name": "query", "in": "query", "description": "SQL query to execute.", "required": true, "schema": { "type": "string", "maxLength": 4096 } } ], "responses": { "200": { "description": "Query results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_QueryResponse" } } } }, "400": { "$ref": "#/components/responses/lex_BadRequest" }, "403": { "$ref": "#/components/responses/lex_Forbidden" }, "404": { "$ref": "#/components/responses/lex_NotFound" }, "507": { "$ref": "#/components/responses/lex_ResourcesExhausted" } }, "deprecated": true, "security": [ { "api_token": [] } ], "tags": [ "Log Explorer Queries" ], "x-api-token-group": [ "Logs Write", "Logs Read" ], "x-auditable": false, "x-fern-ignore": true, "x-fern-sdk-group-name": "logexplorer.zone", "x-fern-sdk-method-name": "query-get" }, "post": { "operationId": "zones-logs-explorer-query-post", "summary": "Run a log query", "description": "Run a SQL query against zone-level datasets.\n\nTimestamp fields are RFC3339 strings. Filter with:\n WHERE {timestamp_field} >= now() - INTERVAL '30' DAY\n WHERE {timestamp_field} >= '2026-04-01T00:00:00Z'\n WHERE {timestamp_field} BETWEEN '2026-04-01T00:00:00Z' AND '2026-04-30T23:59:59Z'\n\nList configured zone datasets to see enabled zone-level datasets.\nList available zone datasets to inspect their schemas and timestamp fields.\n\nFor more information about the datasets, and the meaning of each field, check out https://developers.cloudflare.com/logs/logpush/logpush-job/datasets/\n", "parameters": [ { "$ref": "#/components/parameters/lex_ZoneID" } ], "requestBody": { "required": true, "content": { "text/plain": { "schema": { "description": "SQL query to execute.", "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Query results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_QueryResponse" } } } }, "400": { "$ref": "#/components/responses/lex_BadRequest" }, "403": { "$ref": "#/components/responses/lex_Forbidden" }, "404": { "$ref": "#/components/responses/lex_NotFound" }, "507": { "$ref": "#/components/responses/lex_ResourcesExhausted" } }, "security": [ { "api_token": [] } ], "tags": [ "Log Explorer Queries" ], "x-api-token-group": [ "Logs Write", "Logs Read" ], "x-auditable": false, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logexplorer.zone", "x-fern-sdk-method-name": "query", "x-forge-hidden": true, "x-stability": "beta" } }, "/zones/{zone_id}/logs/rayids/{ray_id}": { "get": { "operationId": "get-zones-zone_id-logs-rayids-ray_id", "summary": "Get logs RayIDs", "description": "The `/rayids` api route allows lookups by specific rayid. The rayids route will return zero, one, or more records (ray ids are not unique).", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logshare_identifier" } }, { "name": "ray_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logshare_ray_identifier" } }, { "name": "fields", "in": "query", "schema": { "$ref": "#/components/schemas/logshare_fields" } }, { "name": "timestamps", "in": "query", "schema": { "$ref": "#/components/schemas/logshare_timestamps" } } ], "responses": { "200": { "description": "Get logs RayIDs response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/logshare_logs_response_json_lines" } } } }, "4XX": { "description": "Get logs RayIDs response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logshare_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logs Received" ], "x-api-token-group": [ "Logs Write", "Logs Read" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logs.rayid", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/logs/received": { "get": { "operationId": "get-zones-zone_id-logs-received", "summary": "Get logs received", "description": "The `/received` api route allows customers to retrieve their edge HTTP logs. The basic access pattern is \"give me all the logs for zone Z for minute M\", where the minute M refers to the time records were received at Cloudflare's central data center. `start` is inclusive, and `end` is exclusive. Because of that, to get all data, at minutely cadence, starting at 10AM, the proper values are: `start=2018-05-20T10:00:00Z&end=2018-05-20T10:01:00Z`, then `start=2018-05-20T10:01:00Z&end=2018-05-20T10:02:00Z` and so on; the overlap will be handled properly.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logshare_identifier" } }, { "name": "start", "in": "query", "schema": { "$ref": "#/components/schemas/logshare_start" } }, { "name": "end", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/logshare_end" } }, { "name": "fields", "in": "query", "schema": { "$ref": "#/components/schemas/logshare_fields" } }, { "name": "sample", "in": "query", "schema": { "$ref": "#/components/schemas/logshare_sample" } }, { "name": "count", "in": "query", "schema": { "$ref": "#/components/schemas/logshare_count" } }, { "name": "timestamps", "in": "query", "schema": { "$ref": "#/components/schemas/logshare_timestamps" } } ], "responses": { "200": { "description": "Get logs received response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/logshare_logs_response_json_lines" } } } }, "4XX": { "description": "Get logs received response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logshare_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logs Received" ], "x-api-token-group": [ "Logs Write", "Logs Read" ], "x-cfPermissionsRequired": { "enum": [ "#logs:read" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logs.received", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/logs/received/fields": { "get": { "operationId": "get-zones-zone_id-logs-received-fields", "summary": "List fields", "description": "Lists all fields available. The response is json object with key-value pairs, where keys are field names, and values are descriptions.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/logshare_identifier" } } ], "responses": { "200": { "description": "List fields response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/logshare_fields_response" } } } }, "4XX": { "description": "List fields response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/logshare_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Logs Received" ], "x-api-token-group": [ "Logs Write", "Logs Read" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "logs.received.fields", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/managed_headers": { "delete": { "operationId": "deleteManagedTransforms", "summary": "Delete Managed Transforms", "description": "Disables all Managed Transforms.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } } ], "responses": { "204": { "$ref": "#/components/responses/rulesets_Empty" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Managed Transforms" ], "x-api-token-group": [ "Response Compression Write", "Config Settings Write", "Dynamic URL Redirects Write", "Cache Settings Write", "Custom Errors Write", "Origin Write", "Managed headers Write", "Zone Transform Rules Write", "Mass URL Redirects Write", "Magic Firewall Write", "L4 DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Write", "Sanitize Write", "Transform Rules Write", "Select Configuration Write", "Bot Management Write", "Zone WAF Write", "Account WAF Write", "Account Rulesets Write", "Logs Write", "Logs Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "managed-transforms", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "listManagedTransforms", "summary": "List Managed Transforms", "description": "Fetches a list of all Managed Transforms.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } } ], "responses": { "200": { "$ref": "#/components/responses/rulesets_ManagedTransforms" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Managed Transforms" ], "x-api-token-group": [ "Response Compression Write", "Response Compression Read", "Config Settings Write", "Config Settings Read", "Dynamic URL Redirects Write", "Dynamic URL Redirects Read", "Cache Settings Write", "Cache Settings Read", "Custom Errors Write", "Custom Errors Read", "Origin Write", "Origin Read", "Managed headers Write", "Managed headers Read", "Zone Transform Rules Write", "Zone Transform Rules Read", "Mass URL Redirects Write", "Mass URL Redirects Read", "Magic Firewall Write", "Magic Firewall Read", "L4 DDoS Managed Ruleset Write", "L4 DDoS Managed Ruleset Read", "HTTP DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Read", "Sanitize Write", "Sanitize Read", "Transform Rules Write", "Transform Rules Read", "Select Configuration Write", "Select Configuration Read", "Bot Management Write", "Bot Management Read", "Zone WAF Write", "Zone WAF Read", "Account WAF Write", "Account WAF Read", "Account Rulesets Read", "Account Rulesets Write", "Logs Write", "Logs Read", "Logs Write", "Logs Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "managed-transforms", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "patch": { "operationId": "updateManagedTransforms", "summary": "Update Managed Transforms", "description": "Updates the status of one or more Managed Transforms.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } } ], "requestBody": { "$ref": "#/components/requestBodies/rulesets_ManagedTransforms" }, "responses": { "200": { "$ref": "#/components/responses/rulesets_ManagedTransforms" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Managed Transforms" ], "x-api-token-group": [ "Response Compression Write", "Config Settings Write", "Dynamic URL Redirects Write", "Cache Settings Write", "Custom Errors Write", "Origin Write", "Managed headers Write", "Zone Transform Rules Write", "Mass URL Redirects Write", "Magic Firewall Write", "L4 DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Write", "Sanitize Write", "Transform Rules Write", "Select Configuration Write", "Bot Management Write", "Zone WAF Write", "Account WAF Write", "Account Rulesets Write", "Logs Write", "Logs Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "managed-transforms", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/media/usage": { "get": { "operationId": "usage-analytics-get-zone-media-usage", "summary": "Get zone Media usage", "description": "Retrieve Media usage analytics for a zone. This endpoint shares the same backend handler as the Stream usage endpoint and returns identical Stream metrics (streamMinutesViewed). The gateway resolves the zone to its owning account and rewrites this path to the shared usage handler.\n", "parameters": [ { "$ref": "#/components/parameters/usage-analytics_zone_id" }, { "$ref": "#/components/parameters/usage-analytics_metrics" }, { "$ref": "#/components/parameters/usage-analytics_since" }, { "$ref": "#/components/parameters/usage-analytics_until" }, { "$ref": "#/components/parameters/usage-analytics_time_delta" }, { "$ref": "#/components/parameters/usage-analytics_limit" }, { "$ref": "#/components/parameters/usage-analytics_filters" } ], "responses": { "200": { "description": "Usage analytics response.", "content": { "application/json": { "examples": { "success": { "summary": "Successful usage retrieval", "value": { "errors": [], "messages": [], "result": [ { "streamMinutesViewed": 12500, "ts": 1693526400 }, { "streamMinutesViewed": 9800, "ts": 1693530000 } ], "success": true } } }, "schema": { "$ref": "#/components/schemas/usage-analytics_stream_usage_response" } } } }, "400": { "$ref": "#/components/responses/usage-analytics_bad_request" }, "401": { "$ref": "#/components/responses/usage-analytics_unauthorized" }, "403": { "$ref": "#/components/responses/usage-analytics_forbidden" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Usage Analytics" ], "x-api-token-group": [ "Images Read" ], "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "media.usage", "x-fern-sdk-method-name": "get" } }, "/zones/{zone_id}/origin/cloud_regions": { "get": { "operationId": "origin-cloud-regions-v2-list", "summary": "List origin cloud region mappings", "description": "Returns all IP-to-cloud-region mappings configured for the zone with pagination support. Each mapping tells Cloudflare which cloud vendor and region hosts the origin at that IP, enabling the edge to route via the nearest Tiered Cache upper-tier co-located with that cloud provider. Returns an empty array when no mappings exist.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } }, { "name": "page", "in": "query", "description": "Page number of paginated results.", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page.", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "List origin cloud region mappings response.", "content": { "application/json": { "examples": { "empty": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_list_empty" }, "two_mappings": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_list" } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_v2_entry" } }, "result_info": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_v2_result_info" } }, "required": [ "result", "result_info" ], "type": "object" } ] } } } }, "4XX": { "description": "List origin cloud region mappings failure.", "content": { "application/json": { "examples": { "invalid_pagination": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_invalid_pagination" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Cloud Regions" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } } }, "/zones/{zone_id}/origin/cloud_regions/batch": { "delete": { "operationId": "origin-cloud-regions-v2-batch-delete", "summary": "Batch delete origin cloud region mappings", "description": "Removes up to 100 IP-to-cloud-region mappings in a single request. Each IP is validated independently — successfully deleted items are returned in the `succeeded` array and IPs that could not be found or are invalid are returned in the `failed` array.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "batch_delete": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_batch_delete_request" } }, "schema": { "type": "array", "items": { "description": "Origin IP address to delete.", "example": "192.0.2.1", "type": "string" }, "maxItems": 100 } } } }, "responses": { "200": { "description": "Batch delete origin cloud region mappings successful.", "content": { "application/json": { "examples": { "batch_deleted": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_batch_delete_response" } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_v2_batch_result" } }, "type": "object" } ] } } } }, "4XX": { "description": "Batch delete origin cloud region mappings failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Cloud Regions" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } }, "put": { "operationId": "origin-cloud-regions-v2-batch-upsert", "summary": "Batch create or replace origin cloud region mappings", "description": "Upserts up to 100 IP-to-cloud-region mappings in a single request. Items in the request body are created or replaced; mappings not included in the request body are preserved unchanged (this is a merge operation, not a full collection replacement). Each item is validated independently — valid items are applied and invalid items are returned in the `failed` array. The vendor and region for every item are validated against the list from `GET /zones/{zone_id}/origin/cloud_regions/supported_regions`.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "batch_put": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_batch_put_request" } }, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_v2_request" }, "maxItems": 100 } } } }, "responses": { "200": { "description": "Batch create or replace origin cloud region mappings successful.", "content": { "application/json": { "examples": { "batch_upserted": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_batch_put_response" } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_v2_batch_result" } }, "type": "object" } ] } } } }, "4XX": { "description": "Batch create or replace origin cloud region mappings failure.", "content": { "application/json": { "examples": { "too_many_mappings": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_too_many_mappings" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Cloud Regions" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } } }, "/zones/{zone_id}/origin/cloud_regions/supported_regions": { "get": { "operationId": "origin-cloud-regions-v2-supported-regions", "summary": "List supported cloud vendors and regions", "description": "Returns the cloud vendors and regions that are valid values for origin cloud region mappings. Each region includes the Tiered Cache upper-tier colocation codes that will be used for cache routing when a mapping targeting that region is active. Requires the zone to have Tiered Cache enabled.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "List supported cloud vendors and regions response.", "content": { "application/json": { "examples": { "vendors": { "$ref": "#/components/examples/cache-rules_supported_cloud_regions" } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_supported_cloud_regions_result" } }, "type": "object" } ] } } } }, "4XX": { "description": "List supported cloud vendors and regions failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Cloud Regions" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } } }, "/zones/{zone_id}/origin/cloud_regions/{origin_ip}": { "delete": { "operationId": "origin-cloud-regions-v2-delete", "summary": "Delete an origin cloud region mapping", "description": "Removes the cloud region mapping for a single origin IP address. The IP path parameter is normalized before lookup. Returns the deleted IP on success. Returns 404 if no mapping exists for the specified IP. When the last mapping for the zone is removed the underlying rule record is also deleted.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } }, { "name": "origin_ip", "in": "path", "description": "Origin IP address whose mapping should be deleted.", "required": true, "schema": { "type": "string", "example": "192.0.2.1" } } ], "responses": { "200": { "description": "Delete origin cloud region mapping response.", "content": { "application/json": { "examples": { "deleted": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_delete" } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_v2_delete_result" } }, "type": "object" } ] } } } }, "4XX": { "description": "Delete origin cloud region mapping failure.", "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_not_found" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Cloud Regions" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } }, "get": { "operationId": "origin-cloud-regions-v2-get", "summary": "Get an origin cloud region mapping", "description": "Returns the cloud region mapping for a single origin IP address. The IP path parameter is normalized before lookup (RFC 5952 for IPv6). Returns 404 if the zone has no mappings or if the specified IP has no mapping.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } }, { "name": "origin_ip", "in": "path", "description": "Origin IP address to look up. IPv4 and IPv6 are supported.", "required": true, "schema": { "type": "string", "example": "192.0.2.1" } } ], "responses": { "200": { "description": "Get origin cloud region mapping response.", "content": { "application/json": { "examples": { "found": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_single" } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_v2_entry" } }, "type": "object" } ] } } } }, "4XX": { "description": "Get origin cloud region mapping failure.", "content": { "application/json": { "examples": { "not_found": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_not_found" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Cloud Regions" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } }, "put": { "operationId": "origin-cloud-regions-v2-upsert", "summary": "Create or replace an origin cloud region mapping", "description": "Creates a new IP-to-cloud-region mapping or replaces the existing mapping for the specified IP. PUT is idempotent — calling it repeatedly with the same body produces the same result. The IP path parameter is normalized to canonical form (RFC 5952 for IPv6) before storage. The vendor and region are validated against the list from `GET /zones/{zone_id}/origin/cloud_regions/supported_regions`. Returns 400 if the `origin_ip` in the body does not match the URL path parameter. Returns 403 (code 1164) when the zone has reached the limit of 3,500 IP mappings.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } }, { "name": "origin_ip", "in": "path", "description": "Origin IP address to create or replace.", "required": true, "schema": { "type": "string", "example": "192.0.2.1" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "aws": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_request_aws" } }, "schema": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_v2_request" } } } }, "responses": { "200": { "description": "Create or replace origin cloud region mapping response.", "content": { "application/json": { "examples": { "upserted": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_single" } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_v2_entry" } }, "type": "object" } ] } } } }, "4XX": { "description": "Create or replace origin cloud region mapping failure.", "content": { "application/json": { "examples": { "invalid_vendor_region": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_invalid_vendor_region" }, "ip_mismatch": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_ip_mismatch" }, "too_many_mappings": { "$ref": "#/components/examples/cache-rules_origin_cloud_region_v2_too_many_mappings" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin Cloud Regions" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } } }, "/zones/{zone_id}/origin_tls_client_auth": { "get": { "operationId": "zone-level-authenticated-origin-pulls-list-certificates", "summary": "List Certificates", "description": "Lists all client certificates configured for zone-level authenticated origin pulls.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "List Certificates response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_collection-3" } } } }, "4XX": { "description": "List Certificates response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_collection-3" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Authenticated Origin Pulls" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-tls-client-auth.zone-certificates", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "zone-level-authenticated-origin-pulls-upload-certificate", "summary": "Upload Certificate", "description": "Upload your own certificate you want Cloudflare to use for edge-to-origin communication to override the shared certificate. Please note that it is important to keep only one certificate active. Also, make sure to enable zone-level authenticated origin pulls by making a PUT call to settings endpoint to see the uploaded certificate in use.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "certificate": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate-5" }, "private_key": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_private_key-2" } }, "required": [ "certificate", "private_key" ] } } } }, "responses": { "200": { "description": "Upload Certificate response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single-3" } } } }, "4XX": { "description": "Upload Certificate response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single-3" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Authenticated Origin Pulls" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-tls-client-auth.zone-certificates", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/origin_tls_client_auth/hostnames": { "get": { "operationId": "per-hostname-authenticated-origin-pull-list-hostname-associations", "summary": "List Hostname Associations", "description": "List certificate ID - hostname associations for the given zone. Shows which hostnames are associated to which certificates for authenticated origin pulls.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of associations per page.", "type": "number", "default": 50, "maximum": 1000, "minimum": 1 } }, { "name": "status", "in": "query", "schema": { "description": "Filter associations by status. Use comma-separated values to filter by multiple statuses, or \"all\" to include every status. Defaults to \"active\" if not provided.", "type": "string", "example": "active", "enum": [ "active", "pending_deployment", "pending_deletion", "deleted", "deployment_timed_out", "deletion_timed_out", "all" ] } } ], "responses": { "200": { "description": "List Hostname Associations response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname_assoc_response_collection" } } } }, "4XX": { "description": "List Hostname Associations response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname_assoc_response_collection" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Per-hostname Authenticated Origin Pull" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-tls-client-auth.hostname-associations", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "put": { "operationId": "per-hostname-authenticated-origin-pull-enable-or-disable-a-hostname-for-client-authentication", "summary": "Enable or Disable a Hostname for Client Authentication", "description": "Associate a hostname to a certificate and enable, disable or invalidate the association. If disabled, client certificate will not be sent to the hostname even if activated at the zone level. 100 maximum associations on a single certificate are allowed. Note: Use a null value for parameter *enabled* to invalidate the association.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_config" } }, "required": [ "config" ] } } } }, "responses": { "200": { "description": "Enable or Disable a Hostname for Client Authentication response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname_aop_response_collection" } } } }, "4XX": { "description": "Enable or Disable a Hostname for Client Authentication response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname_aop_response_collection" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Per-hostname Authenticated Origin Pull" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-tls-client-auth.hostnames", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/origin_tls_client_auth/hostnames/certificates": { "get": { "operationId": "per-hostname-authenticated-origin-pull-list-certificates", "summary": "List Certificates", "description": "Lists all client certificates configured for per-hostname authenticated origin pulls on the zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "List Certificates response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_collection-4" } } } }, "4XX": { "description": "List Certificates response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_collection-4" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Per-hostname Authenticated Origin Pull" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-tls-client-auth.hostname-certificates", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "per-hostname-authenticated-origin-pull-upload-a-hostname-client-certificate", "summary": "Upload a Hostname Client Certificate", "description": "Upload a certificate to be used for client authentication on a hostname. 10 hostname certificates per zone are allowed.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "certificate": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate-6" }, "private_key": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_private_key-3" } }, "required": [ "certificate", "private_key" ] } } } }, "responses": { "200": { "description": "Upload a Hostname Client Certificate response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single-4" } } } }, "4XX": { "description": "Upload a Hostname Client Certificate response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single-4" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Per-hostname Authenticated Origin Pull" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-tls-client-auth.hostname-certificates", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/origin_tls_client_auth/hostnames/certificates/{certificate_id}": { "delete": { "operationId": "per-hostname-authenticated-origin-pull-delete-hostname-client-certificate", "summary": "Delete Hostname Client Certificate", "description": "Removes a client certificate used for authenticated origin pulls on a specific hostname.\nNote: Before deleting the certificate, you must first invalidate the hostname for client authentication by sending a PUT request with `enabled` set to null. After invalidating the association, the certificate can be safely deleted.\n", "parameters": [ { "name": "certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Delete Hostname Client Certificate response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single-4" } } } }, "4XX": { "description": "Delete Hostname Client Certificate response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single-4" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Per-hostname Authenticated Origin Pull" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-tls-client-auth.hostname-certificates", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "per-hostname-authenticated-origin-pull-get-the-hostname-client-certificate", "summary": "Get the Hostname Client Certificate", "description": "Get the certificate by ID to be used for client authentication on a hostname.", "parameters": [ { "name": "certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Get the Hostname Client Certificate response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single-4" } } } }, "4XX": { "description": "Get the Hostname Client Certificate response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single-4" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Per-hostname Authenticated Origin Pull" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-tls-client-auth.hostname-certificates", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/origin_tls_client_auth/hostnames/{hostname}": { "get": { "operationId": "per-hostname-authenticated-origin-pull-get-the-hostname-status-for-client-authentication", "summary": "Get the Hostname Status for Client Authentication", "description": "Retrieves the client certificate authentication status for a specific hostname, showing whether authenticated origin pulls are enabled.", "parameters": [ { "name": "hostname", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname-2" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Get the Hostname Status for Client Authentication response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname_aop_single_response" } } } }, "4XX": { "description": "Get the Hostname Status for Client Authentication response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname_aop_single_response" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Per-hostname Authenticated Origin Pull" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-tls-client-auth.hostnames", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/origin_tls_client_auth/settings": { "get": { "operationId": "zone-level-authenticated-origin-pulls-get-enablement-setting-for-zone", "summary": "Get Enablement Setting for Zone", "description": "Get whether zone-level authenticated origin pulls is enabled or not. It is false by default.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Get Enablement Setting for Zone response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_enabled_response" } } } }, "4XX": { "description": "Get Enablement Setting for Zone response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_enabled_response" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Authenticated Origin Pulls" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-tls-client-auth.settings", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "zone-level-authenticated-origin-pulls-set-enablement-for-zone", "summary": "Set Enablement for Zone", "description": "Enable or disable zone-level authenticated origin pulls. 'enabled' should be set true either before/after the certificate is uploaded to see the certificate in use.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_enabled-4" } }, "required": [ "enabled" ] } } } }, "responses": { "200": { "description": "Set Enablement for Zone response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_enabled_response" } } } }, "4XX": { "description": "Set Enablement for Zone response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_enabled_response" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Authenticated Origin Pulls" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-tls-client-auth.settings", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/origin_tls_client_auth/{certificate_id}": { "delete": { "operationId": "zone-level-authenticated-origin-pulls-delete-certificate", "summary": "Delete Certificate", "description": "Removes a client certificate used for zone-level authenticated origin pulls.", "parameters": [ { "name": "certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Delete Certificate response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single-3" } } } }, "4XX": { "description": "Delete Certificate response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single-3" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Authenticated Origin Pulls" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-tls-client-auth.zone-certificates", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "zone-level-authenticated-origin-pulls-get-certificate-details", "summary": "Get Certificate Details", "description": "Retrieves details for a specific client certificate used in zone-level authenticated origin pulls.", "parameters": [ { "name": "certificate_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Get Certificate Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single-3" } } } }, "4XX": { "description": "Get Certificate Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_response_single-3" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone-Level Authenticated Origin Pulls" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "origin-tls-client-auth.zone-certificates", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/page_shield": { "get": { "operationId": "page-shield-get-settings", "summary": "Get client-side security settings", "description": "Returns the client-side security product enablement status and reporting behaviors.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } } ], "responses": { "200": { "description": "Get Client-Side Security settings response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_api-get-response-collection" }, { "properties": { "result": { "$ref": "#/components/schemas/client-side-security_get-zone-settings-response" } } } ] } } } }, "4XX": { "description": "Get Client-Side Security settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Client-Side Security" ], "x-api-token-group": [ "Page Shield", "Domain Page Shield Read", "Domain Page Shield", "Page Shield Read", "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-side-security.settings", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "page-shield-update-settings", "summary": "Update client-side security settings", "description": "Updates client-side security enablement and reporting behaviors for the zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "enabled": { "$ref": "#/components/schemas/client-side-security_enabled" }, "use_cloudflare_reporting_endpoint": { "$ref": "#/components/schemas/client-side-security_use_cloudflare_reporting_endpoint" }, "use_connection_url_path": { "$ref": "#/components/schemas/client-side-security_use_connection_url_path" } } } } } }, "responses": { "200": { "description": "Update Client-Side Security settings response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_zone_settings_response_single" }, { "properties": { "result": { "$ref": "#/components/schemas/client-side-security_update-zone-settings-response" } } } ] } } } }, "4XX": { "description": "Update Client-Side Security settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Client-Side Security" ], "x-api-token-group": [ "Page Shield", "Domain Page Shield", "Zone Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-side-security.settings", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/page_shield/connections": { "get": { "operationId": "page-shield-list-connections", "summary": "List detected connections", "description": "Lists outbound connections made by webpages in the zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } }, { "name": "exclude_urls", "in": "query", "schema": { "description": "Excludes connections whose URL contains one of the URL-encoded URLs separated by commas.\n", "type": "string", "example": "blog.cloudflare.com,www.example" } }, { "name": "urls", "in": "query", "schema": { "description": "Includes connections whose URL contain one or more URL-encoded URLs separated by commas.\n", "type": "string", "example": "blog.cloudflare.com,www.example" } }, { "name": "hosts", "in": "query", "schema": { "description": "Includes connections that match one or more URL-encoded hostnames separated by commas.\n\nWildcards are supported at the start and end of each hostname to support starts with, ends with\nand contains. If no wildcards are used, results will be filtered by exact match\n", "type": "string", "example": "blog.cloudflare.com,www.example*,*cloudflare.com" } }, { "name": "page", "in": "query", "schema": { "description": "The current page number of the paginated results.\n\nWe additionally support a special value \"all\". When \"all\" is used, the API will return all the connections\nwith the applied filters in a single page. This feature is best-effort and it may only work for zones with\na low number of connections\n", "type": "string", "example": 2 } }, { "name": "per_page", "in": "query", "schema": { "description": "The number of results per page.", "type": "number", "example": 100, "maximum": 100, "minimum": 1 } }, { "name": "order_by", "in": "query", "schema": { "description": "The field used to sort returned connections.", "type": "string", "example": "first_seen_at", "enum": [ "first_seen_at", "last_seen_at" ] } }, { "name": "direction", "in": "query", "schema": { "description": "The direction used to sort returned connections.", "type": "string", "example": "asc", "enum": [ "asc", "desc" ] } }, { "name": "prioritize_malicious", "in": "query", "schema": { "description": "When true, malicious connections appear first in the returned connections.", "type": "boolean", "example": true } }, { "name": "exclude_cdn_cgi", "in": "query", "schema": { "description": "When true, excludes connections seen in a `/cdn-cgi` path from the returned connections. The default value is true.", "type": "boolean", "example": true } }, { "name": "status", "in": "query", "schema": { "description": "Filters the returned connections using a comma-separated list of connection statuses. Accepted values: `active`, `infrequent`, and `inactive`. The default value is `active`.", "type": "string", "example": "active,inactive" } }, { "name": "page_url", "in": "query", "schema": { "description": "Includes connections that match one or more page URLs (separated by commas) where they were last seen\n\nWildcards are supported at the start and end of each page URL to support starts with, ends with\nand contains. If no wildcards are used, results will be filtered by exact match\n", "type": "string", "example": "example.com/page,*/checkout,example.com/*,*checkout*" } }, { "name": "export", "in": "query", "schema": { "description": "Export the list of connections as a file, limited to 50000 entries.", "type": "string", "example": "csv", "enum": [ "csv" ] } } ], "responses": { "200": { "description": "List Client-Side Security connections response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_list-zone-connections-response" } } } }, "4XX": { "description": "List Client-Side Security connections response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Client-Side Security" ], "x-api-token-group": [ "Page Shield", "Domain Page Shield Read", "Domain Page Shield", "Page Shield Read", "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-side-security.connections", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/zones/{zone_id}/page_shield/connections/{connection_id}": { "get": { "operationId": "page-shield-get-connection", "summary": "Get a detected connection", "description": "Returns a webpage connection detected on the zone by connection ID.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } } ], "responses": { "200": { "description": "Get a Client-Side Security connection response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_get-zone-connection-response" } } } }, "4XX": { "description": "Get a Client-Side Security connection response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Client-Side Security" ], "x-api-token-group": [ "Page Shield", "Domain Page Shield Read", "Domain Page Shield", "Page Shield Read", "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-side-security.connections", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/page_shield/cookies": { "get": { "operationId": "page-shield-list-cookies", "summary": "List detected cookies", "description": "Lists cookies detected on the zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } }, { "name": "hosts", "in": "query", "schema": { "description": "Includes cookies that match one or more URL-encoded hostnames separated by commas.\n\nWildcards are supported at the start and end of each hostname to support starts with, ends with\nand contains. If no wildcards are used, results will be filtered by exact match\n", "type": "string", "example": "blog.cloudflare.com,www.example*,*cloudflare.com" } }, { "name": "page", "in": "query", "schema": { "description": "The current page number of the paginated results.\n\nWe additionally support a special value \"all\". When \"all\" is used, the API will return all the cookies\nwith the applied filters in a single page. This feature is best-effort and it may only work for zones with\na low number of cookies\n", "type": "string", "example": 2 } }, { "name": "per_page", "in": "query", "schema": { "description": "The number of results per page.", "type": "number", "example": 100, "maximum": 100, "minimum": 1 } }, { "name": "order_by", "in": "query", "schema": { "description": "The field used to sort returned cookies.", "type": "string", "example": "first_seen_at", "enum": [ "first_seen_at", "last_seen_at" ] } }, { "name": "direction", "in": "query", "schema": { "description": "The direction used to sort returned cookies.'", "type": "string", "example": "asc", "enum": [ "asc", "desc" ] } }, { "name": "page_url", "in": "query", "schema": { "description": "Includes connections that match one or more page URLs (separated by commas) where they were last seen\n\nWildcards are supported at the start and end of each page URL to support starts with, ends with\nand contains. If no wildcards are used, results will be filtered by exact match\n", "type": "string", "example": "example.com/page,*/checkout,example.com/*,*checkout*" } }, { "name": "export", "in": "query", "schema": { "description": "Export the list of cookies as a file, limited to 50000 entries.", "type": "string", "example": "csv", "enum": [ "csv" ] } }, { "name": "name", "in": "query", "schema": { "description": "Filters the returned cookies that match the specified name.\nWildcards are supported at the start and end to support starts with, ends with\nand contains. e.g. session*\n", "type": "string", "example": "session_id", "maxLength": 1024 } }, { "name": "secure", "in": "query", "schema": { "description": "Filters the returned cookies that are set with Secure", "type": "boolean", "example": true } }, { "name": "http_only", "in": "query", "schema": { "description": "Filters the returned cookies that are set with HttpOnly", "type": "boolean", "example": true } }, { "name": "same_site", "in": "query", "schema": { "description": "Filters the returned cookies that match the specified same_site attribute", "type": "string", "example": "strict", "enum": [ "lax", "strict", "none" ] } }, { "name": "type", "in": "query", "schema": { "description": "Filters the returned cookies that match the specified type attribute", "type": "string", "example": "first_party", "enum": [ "first_party", "unknown" ] } }, { "name": "path", "in": "query", "schema": { "description": "Filters the returned cookies that match the specified path attribute", "type": "string", "example": "/", "maxLength": 1024 } }, { "name": "domain", "in": "query", "schema": { "description": "Filters the returned cookies that match the specified domain attribute", "type": "string", "example": "example.com", "maxLength": 1024 } } ], "responses": { "200": { "description": "List Client-Side Security cookies response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_list-zone-cookies-response" } } } }, "4XX": { "description": "List Client-Side Security cookies response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Client-Side Security" ], "x-api-token-group": [ "Page Shield", "Domain Page Shield Read", "Domain Page Shield", "Page Shield Read", "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-side-security.cookies", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/zones/{zone_id}/page_shield/cookies/{cookie_id}": { "get": { "operationId": "page-shield-get-cookie", "summary": "Get a detected cookie", "description": "Returns a cookie detected on the zone by cookie ID.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } }, { "name": "cookie_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } } ], "responses": { "200": { "description": "Get a Client-Side Security cookie response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_get-zone-cookie-response" } } } }, "4XX": { "description": "Get a Client-Side Security cookie response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Client-Side Security" ], "x-api-token-group": [ "Page Shield", "Domain Page Shield Read", "Domain Page Shield", "Page Shield Read", "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-side-security.cookies", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/page_shield/policies": { "get": { "operationId": "page-shield-list-policies", "summary": "List content security rules", "description": "Lists content security rules configured for the zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } } ], "responses": { "200": { "description": "List Client-Side Security policies response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_list-zone-policies-response" } } } }, "4XX": { "description": "List Client-Side Security policies response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Client-Side Security" ], "x-api-token-group": [ "Page Shield", "Domain Page Shield Read", "Domain Page Shield", "Page Shield Read", "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-side-security.policies", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "page-shield-create-policy", "summary": "Create a content security rule", "description": "Creates a rule that applies a client-side security action when its filter expression matches.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_policy" } } } }, "responses": { "200": { "description": "Create a Client-Side Security policy response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_get-zone-policy-response" } } } }, "4XX": { "description": "Create a Client-Side Security policy response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Client-Side Security" ], "x-api-token-group": [ "Page Shield", "Domain Page Shield", "Zone Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-side-security.policies", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/page_shield/policies/{policy_id}": { "delete": { "operationId": "page-shield-delete-policy", "summary": "Delete a content security rule", "description": "Permanently deletes a content security rule by ID.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } } ], "responses": { "204": { "description": "Delete a Client-Side Security policy response" }, "4XX": { "description": "Delete a Client-Side Security policy response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Client-Side Security" ], "x-api-token-group": [ "Page Shield", "Domain Page Shield", "Zone Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-side-security.policies", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation permanently deletes the content security rule from the zone." }, "get": { "operationId": "page-shield-get-policy", "summary": "Get a content security rule", "description": "Returns a content security rule by ID.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } } ], "responses": { "200": { "description": "Get a Client-Side Security policy response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_get-zone-policy-response" } } } }, "4XX": { "description": "Get a Client-Side Security policy response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Client-Side Security" ], "x-api-token-group": [ "Page Shield", "Domain Page Shield Read", "Domain Page Shield", "Page Shield Read", "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-side-security.policies", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "page-shield-update-policy", "summary": "Update a content security rule", "description": "Updates the description, action, expression, enabled state, and policy value for a content security rule.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } }, { "name": "policy_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "action": { "$ref": "#/components/schemas/client-side-security_policy-action" }, "description": { "$ref": "#/components/schemas/client-side-security_policy-description" }, "enabled": { "$ref": "#/components/schemas/client-side-security_policy-enabled" }, "expression": { "$ref": "#/components/schemas/client-side-security_policy-expression" }, "value": { "$ref": "#/components/schemas/client-side-security_policy-value" } } } } } }, "responses": { "200": { "description": "Update a Client-Side Security policy response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_get-zone-policy-response" } } } }, "4XX": { "description": "Update a Client-Side Security policy response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Client-Side Security" ], "x-api-token-group": [ "Page Shield", "Domain Page Shield", "Zone Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-side-security.policies", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/page_shield/scripts": { "get": { "operationId": "page-shield-list-scripts", "summary": "List detected scripts", "description": "Lists scripts detected on webpages in the zone, with filtering and pagination.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } }, { "name": "exclude_urls", "in": "query", "schema": { "description": "Excludes scripts whose URL contains one of the URL-encoded URLs separated by commas.\n", "type": "string", "example": "blog.cloudflare.com,www.example" } }, { "name": "urls", "in": "query", "schema": { "description": "Includes scripts whose URL contain one or more URL-encoded URLs separated by commas.\n", "type": "string", "example": "blog.cloudflare.com,www.example" } }, { "name": "hosts", "in": "query", "schema": { "description": "Includes scripts that match one or more URL-encoded hostnames separated by commas.\n\nWildcards are supported at the start and end of each hostname to support starts with, ends with\nand contains. If no wildcards are used, results will be filtered by exact match\n", "type": "string", "example": "blog.cloudflare.com,www.example*,*cloudflare.com" } }, { "name": "page", "in": "query", "schema": { "description": "The current page number of the paginated results.\n\nWe additionally support a special value \"all\". When \"all\" is used, the API will return all the scripts\nwith the applied filters in a single page. This feature is best-effort and it may only work for zones with\na low number of scripts\n", "type": "string", "example": 2 } }, { "name": "per_page", "in": "query", "schema": { "description": "The number of results per page.", "type": "number", "example": 100, "maximum": 100, "minimum": 1 } }, { "name": "order_by", "in": "query", "schema": { "description": "The field used to sort returned scripts.", "type": "string", "example": "first_seen_at", "enum": [ "first_seen_at", "last_seen_at" ] } }, { "name": "direction", "in": "query", "schema": { "description": "The direction used to sort returned scripts.", "type": "string", "example": "asc", "enum": [ "asc", "desc" ] } }, { "name": "prioritize_malicious", "in": "query", "schema": { "description": "When true, malicious scripts appear first in the returned scripts.", "type": "boolean", "example": true } }, { "name": "exclude_cdn_cgi", "in": "query", "schema": { "description": "When true, excludes scripts seen in a `/cdn-cgi` path from the returned scripts. The default value is true.", "type": "boolean", "example": true, "default": true } }, { "name": "exclude_duplicates", "in": "query", "schema": { "description": "When true, excludes duplicate scripts. We consider a script duplicate of another if their javascript\ncontent matches and they share the same url host and zone hostname. In such case, we return the most\nrecent script for the URL host and zone hostname combination.\n", "type": "boolean", "example": true, "default": true } }, { "name": "status", "in": "query", "schema": { "description": "Filters the returned scripts using a comma-separated list of scripts statuses. Accepted values: `active`, `infrequent`, and `inactive`. The default value is `active`.", "type": "string", "example": "active,inactive" } }, { "name": "page_url", "in": "query", "schema": { "description": "Includes scripts that match one or more page URLs (separated by commas) where they were last seen\n\nWildcards are supported at the start and end of each page URL to support starts with, ends with\nand contains. If no wildcards are used, results will be filtered by exact match\n", "type": "string", "example": "example.com/page,*/checkout,example.com/*,*checkout*" } }, { "name": "export", "in": "query", "schema": { "description": "Export the list of scripts as a file, limited to 50000 entries.", "type": "string", "example": "csv", "enum": [ "csv" ] } } ], "responses": { "200": { "description": "List Client-Side Security scripts response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_list-zone-scripts-response" } } } }, "4XX": { "description": "List Client-Side Security scripts response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Client-Side Security" ], "x-api-token-group": [ "Page Shield", "Domain Page Shield Read", "Domain Page Shield", "Page Shield Read", "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-side-security.scripts", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/zones/{zone_id}/page_shield/scripts/{script_id}": { "get": { "operationId": "page-shield-get-script", "summary": "Get a detected script", "description": "Returns a script detected on the zone by script ID.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } }, { "name": "script_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/client-side-security_id" } } ], "responses": { "200": { "description": "Get a Client-Side Security script response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/client-side-security_get-zone-script-response" } } } }, "4XX": { "description": "Get a Client-Side Security script response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Client-Side Security" ], "x-api-token-group": [ "Page Shield", "Domain Page Shield Read", "Domain Page Shield", "Page Shield Read", "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "client-side-security.scripts", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/pagerules": { "get": { "operationId": "page-rules-list-page-rules", "summary": "List Page Rules", "description": "Fetches Page Rules in a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier-2" }, "example": "023e105f4ecef8ad9ca31a8372d0c353" }, { "name": "order", "in": "query", "schema": { "description": "The field used to sort returned Page Rules.", "type": "string", "example": "status", "default": "priority", "enum": [ "status", "priority" ] } }, { "name": "direction", "in": "query", "schema": { "description": "The direction used to sort returned Page Rules.", "type": "string", "example": "desc", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "match", "in": "query", "schema": { "description": "When set to `all`, all the search requirements must match. When set to `any`, only one of the search requirements has to match.", "type": "string", "default": "all", "enum": [ "any", "all" ] } }, { "name": "status", "in": "query", "schema": { "description": "The status of the Page Rule.", "type": "string", "example": "active", "default": "disabled", "enum": [ "active", "disabled" ] } } ], "responses": { "200": { "description": "List Page Rules response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common-2" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/zones_page_rule" } } } } ] } } } }, "4XX": { "description": "List Page Rules response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-common-failure-2" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Page Rules" ], "x-api-token-group": [ "Zone Read", "Zone Write", "Page Rules Write", "Page Rules Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "page-rules", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "page-rules-create-a-page-rule", "summary": "Create a Page Rule", "description": "Creates a new Page Rule.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier-2" }, "example": "023e105f4ecef8ad9ca31a8372d0c353" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/zones_actions" }, "priority": { "$ref": "#/components/schemas/zones_priority" }, "status": { "$ref": "#/components/schemas/zones_status" }, "targets": { "$ref": "#/components/schemas/zones_targets" } }, "required": [ "targets", "actions" ] } } } }, "responses": { "200": { "description": "Create a Page Rule response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/zones_page_rule" } } } ] } } } }, "4XX": { "description": "Create a Page Rule response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-common-failure-2" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Page Rules" ], "x-api-token-group": [ "Zone Write", "Page Rules Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "page-rules", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/pagerules/settings": { "get": { "operationId": "available-page-rules-settings-list-available-page-rules-settings", "summary": "List available Page Rules settings", "description": "Returns a list of settings (and their details) that Page Rules can apply to matching requests.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier-2" }, "example": "023e105f4ecef8ad9ca31a8372d0c353" } ], "responses": { "200": { "description": "List available Page Rules settings response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common-2" }, { "properties": { "result": { "$ref": "#/components/schemas/zones_settings" } } } ] } } } }, "4XX": { "description": "List available Page Rules settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-common-failure-2" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Available Page Rules settings" ], "x-api-token-group": [ "Zone Read", "Zone Write", "Page Rules Write", "Page Rules Read" ], "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "page-rules.settings", "x-fern-sdk-method-name": "list", "x-forge-hidden": true, "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" } } }, "/zones/{zone_id}/pagerules/{pagerule_id}": { "delete": { "operationId": "page-rules-delete-a-page-rule", "summary": "Delete a Page Rule", "description": "Deletes an existing Page Rule.", "parameters": [ { "name": "pagerule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier-2" }, "example": "023e105f4ecef8ad9ca31a8372d0c353" }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier-2" }, "example": "023e105f4ecef8ad9ca31a8372d0c353" } ], "responses": { "200": { "description": "Delete a Page Rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-single-id-2" } } } }, "4XX": { "description": "Delete a Page Rule response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-common-failure-2" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Page Rules" ], "x-api-token-group": [ "Zone Write", "Page Rules Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "page-rules", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "page-rules-get-a-page-rule", "summary": "Get a Page Rule", "description": "Fetches the details of a Page Rule.", "parameters": [ { "name": "pagerule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier-2" }, "example": "023e105f4ecef8ad9ca31a8372d0c353" }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier-2" }, "example": "023e105f4ecef8ad9ca31a8372d0c353" } ], "responses": { "200": { "description": "Get a Page Rule response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/zones_page_rule" } } } ] } } } }, "4XX": { "description": "Get a Page Rule response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-common-failure-2" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Page Rules" ], "x-api-token-group": [ "Trust and Safety Write", "Trust and Safety Read", "Zero Trust: PII Read", "Zaraz Edit", "Zaraz Read", "Zaraz Admin", "Access: Apps and Policies Revoke", "Access: Apps and Policies Write", "Access: Apps and Policies Read", "Access: Apps and Policies Revoke", "Access: Mutual TLS Certificates Write", "Access: Organizations, Identity Providers, and Groups Write", "Zone Settings Write", "Zone Settings Read", "Zone Read", "DNS Read", "Workers Scripts Write", "Workers Scripts Read", "Zone Write", "Workers Routes Write", "Workers Routes Read", "Stream Write", "Stream Read", "SSL and Certificates Write", "SSL and Certificates Read", "Logs Write", "Logs Read", "Cache Purge", "Page Rules Write", "Page Rules Read", "Load Balancers Write", "Load Balancers Read", "Firewall Services Write", "Firewall Services Read", "DNS Write", "Apps Write", "Analytics Read", "Access: Apps and Policies Write", "Access: Apps and Policies Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "page-rules", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "page-rules-edit-a-page-rule", "summary": "Edit a Page Rule", "description": "Updates one or more fields of an existing Page Rule.", "parameters": [ { "name": "pagerule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier-2" }, "example": "023e105f4ecef8ad9ca31a8372d0c353" }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier-2" }, "example": "023e105f4ecef8ad9ca31a8372d0c353" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/zones_actions" }, "priority": { "$ref": "#/components/schemas/zones_priority" }, "status": { "$ref": "#/components/schemas/zones_status" }, "targets": { "$ref": "#/components/schemas/zones_targets" } } } } } }, "responses": { "200": { "description": "Edit a Page Rule response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/zones_page_rule" } } } ] } } } }, "4XX": { "description": "Edit a Page Rule response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-common-failure-2" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Page Rules" ], "x-api-token-group": [ "Zone Write", "Page Rules Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "page-rules", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "page-rules-update-a-page-rule", "summary": "Update a Page Rule", "description": "Replaces the configuration of an existing Page Rule. The configuration of the updated Page Rule will exactly match the data passed in the API request.", "parameters": [ { "name": "pagerule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier-2" }, "example": "023e105f4ecef8ad9ca31a8372d0c353" }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier-2" }, "example": "023e105f4ecef8ad9ca31a8372d0c353" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/zones_actions" }, "priority": { "$ref": "#/components/schemas/zones_priority" }, "status": { "$ref": "#/components/schemas/zones_status" }, "targets": { "$ref": "#/components/schemas/zones_targets" } }, "required": [ "targets", "actions" ] } } } }, "responses": { "200": { "description": "Update a Page Rule response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/zones_page_rule" } } } ] } } } }, "4XX": { "description": "Update a Page Rule response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-common-failure-2" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Page Rules" ], "x-api-token-group": [ "Zone Write", "Page Rules Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "page-rules", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/pay-per-crawl/can_be_enabled": { "get": { "operationId": "pay-per-crawl.getZoneCanBeEnabled", "summary": "Get pay-per-crawl zone eligibility", "description": "Gets whether pay-per-crawl can be enabled for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "description": "zone id", "required": true, "schema": { "type": "string" }, "x-auditable": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pay-per-crawl_getZoneCanBeEnabledResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pay-per-crawl_apiErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "ppc_config" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-sdk-group-name": "pay-per-crawl.zones", "x-fern-sdk-method-name": "get-can-be-enabled" } }, "/zones/{zone_id}/pay-per-crawl/configuration": { "get": { "operationId": "pay-per-crawl.getConfig", "summary": "Get the pay-per-crawl config", "description": "Gets the pay-per-crawl config for a zone including the bot configuration.", "parameters": [ { "name": "zone_id", "in": "path", "description": "zone id", "required": true, "schema": { "type": "string" }, "x-auditable": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pay-per-crawl_getConfigResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pay-per-crawl_apiErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "ppc_config" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-sdk-group-name": "pay-per-crawl.config", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "pay-per-crawl.patchConfig", "summary": "Changes pay-per-crawl config for a zone", "description": "Changes the pay-per-crawl config for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "description": "zone id", "required": true, "schema": { "type": "string" }, "x-auditable": true } ], "requestBody": { "$ref": "#/components/requestBodies/pay-per-crawl_DaricConfig" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pay-per-crawl_getConfigResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pay-per-crawl_apiErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "ppc_config" ], "x-api-token-group": [ "Zone Settings Write" ], "x-fern-sdk-group-name": "pay-per-crawl.config", "x-fern-sdk-method-name": "edit" }, "post": { "operationId": "pay-per-crawl.createConfig", "summary": "Creates pay-per-crawl config for a zone", "description": "Creates the pay-per-crawl config for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "description": "zone id", "required": true, "schema": { "type": "string" }, "x-auditable": true } ], "requestBody": { "$ref": "#/components/requestBodies/pay-per-crawl_DaricConfig" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pay-per-crawl_getConfigResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pay-per-crawl_apiErrorResponse" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "ppc_config" ], "x-api-token-group": [ "Zone Settings Write" ], "x-fern-sdk-group-name": "pay-per-crawl.config", "x-fern-sdk-method-name": "create" } }, "/zones/{zone_id}/precursor": { "get": { "operationId": "precursor-for-a-zone-get-config", "summary": "Get Zone Precursor Config", "description": "Retrieve a zone's Precursor configuration: the zone-level\n`default_mode` and the ordered list of `enforcement_rules`.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/precursor_identifier" } } ], "responses": { "200": { "description": "Precursor config response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/precursor_precursor_config_response_body" } } } }, "4XX": { "description": "Precursor config response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/precursor_precursor_config_response_body" }, { "$ref": "#/components/schemas/precursor_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Precursor" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.precursor.update", "com.cloudflare.api.account.zone.precursor.read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "precursor", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "precursor-for-a-zone-update-config", "summary": "Update Zone Precursor Config", "description": "Updates the Precursor configuration for a zone.\n\n`default_mode` sets the zone-level enforcement mode. `enforcement_rules`\nis the ordered list of rules that override enforcement for matching\nrequests.\n\nThis is a partial update: only the fields present in the request body\nare changed.\n\n- Sending an empty array (`[]`) clears all enforcement rules.\n- At least one of `default_mode` or `enforcement_rules` must be present;\n an empty body (`{}`) is rejected with `400`.\n- Rule `id` is read-only (assigned by Cloudflare) and ignored on input.\n- Rule `mode` must be `min-friction` or `max-security` (`off` is not a\n valid rule mode; use `default_mode` to disable enforcement).\n- Rule `expression` is limited to 4000 characters. The limit applies to\n each rule individually, not to the combined size of all rules.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/precursor_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "min-friction": { "summary": "Zone-level min-friction enforcement", "value": { "default_mode": "min-friction" } }, "off": { "summary": "Disable precursor for the zone", "value": { "default_mode": "off" } }, "rules-only": { "summary": "Replace rules only, leaving default_mode unchanged", "value": { "enforcement_rules": [ { "description": "Ease friction on the login path", "enabled": true, "expression": "http.request.uri.path eq \"/login\"", "mode": "min-friction" } ] } }, "with-rules": { "summary": "max-security default with a min-friction override rule", "value": { "default_mode": "max-security", "enforcement_rules": [ { "description": "Ease friction on the login path", "enabled": true, "expression": "http.request.uri.path eq \"/login\"", "mode": "min-friction" } ] } } }, "schema": { "$ref": "#/components/schemas/precursor_precursor_config" } } } }, "responses": { "200": { "description": "Update Precursor response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/precursor_precursor_config_response_body" } } } }, "4XX": { "description": "Update Precursor response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/precursor_precursor_config_response_body" }, { "$ref": "#/components/schemas/precursor_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Precursor" ], "x-cfPermissionsRequired": { "enum": [ "com.cloudflare.api.account.zone.precursor.update" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "precursor", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/purge_cache": { "post": { "operationId": "zone-purge", "summary": "Purge Cached Content", "description": "### Purge All Cached Content\nRemoves ALL files from Cloudflare's cache. All tiers can purge everything.\n```\n{\"purge_everything\": true}\n```\n\n### Purge Cached Content by URL\nGranularly removes one or more files from Cloudflare's cache by specifying URLs. All tiers can purge by URL.\n\nTo purge files with custom cache keys, include the headers used to compute the cache key as in the example. If you have a device type or geo in your cache key, you will need to include the CF-Device-Type or CF-IPCountry headers. If you have lang in your cache key, you will need to include the Accept-Language header.\n\n**NB:** When including the Origin header, be sure to include the **scheme** and **hostname**. The port number can be omitted if it is the default port (80 for http, 443 for https), but must be included otherwise.\n\nSingle file purge example with files:\n```\n{\"files\": [\"http://www.example.com/css/styles.css\", \"http://www.example.com/js/index.js\"]}\n```\nSingle file purge example with url and header pairs:\n```\n{\"files\": [{\"url\": \"http://www.example.com/cat_picture.jpg\", \"headers\": {\"CF-IPCountry\": \"US\", \"CF-Device-Type\": \"desktop\", \"Accept-Language\": \"zh-CN\"}}, {\"url\": \"http://www.example.com/dog_picture.jpg\", \"headers\": {\"CF-IPCountry\": \"EU\", \"CF-Device-Type\": \"mobile\", \"Accept-Language\": \"en-US\"}}]}\n```\n\n### Purge Cached Content by Tag, Host or Prefix\nGranularly removes one or more files from Cloudflare's cache either by specifying the host, the associated Cache-Tag, or a Prefix.\n\nFlex purge with tags:\n```\n{\"tags\": [\"a-cache-tag\", \"another-cache-tag\"]}\n```\nFlex purge with hosts:\n```\n{\"hosts\": [\"www.example.com\", \"images.example.com\"]}\n```\nFlex purge with prefixes:\n```\n{\"prefixes\": [\"www.example.com/foo\", \"images.example.com/bar/baz\"]}\n```\n\n### Availability and limits\nPlease refer to [purge cache availability and limits documentation page](https://developers.cloudflare.com/cache/how-to/purge-cache/#availability-and-limits).\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-purge_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "Flex Purge with Hosts": { "summary": "Flex purge example with hosts list", "value": { "hosts": [ "www.example.com", "images.example.com" ] } }, "Flex Purge with Prefixes": { "summary": "Flex purge example with prefixes list", "value": { "prefixes": [ "www.example.com/foo", "images.example.com/bar/baz" ] } }, "Flex Purge with Tags": { "summary": "Flex purge example with tags list", "value": { "tags": [ "a-cache-tag", "another-cache-tag" ] } }, "Purge Everything": { "summary": "Purge everything example", "value": { "purge_everything": true } }, "Single File Purge": { "summary": "Single file purge example with files list", "value": { "files": [ "http://www.example.com/css/styles.css", "http://www.example.com/js/index.js" ] } }, "Single File Purge with UrlAndHeaders": { "summary": "Single file purge example with url and headers list", "value": { "files": [ { "headers": { "Accept-Language": "zh-CN", "CF-Device-Type": "desktop", "CF-IPCountry": "US" }, "url": "http://www.example.com/cat_picture.jpg" }, { "headers": { "Accept-Language": "en-US", "CF-Device-Type": "mobile", "CF-IPCountry": "EU" }, "url": "http://www.example.com/dog_picture.jpg" } ] } } }, "schema": { "anyOf": [ { "$ref": "#/components/schemas/cache-purge_FlexPurgeByTags" }, { "$ref": "#/components/schemas/cache-purge_FlexPurgeByHostnames" }, { "$ref": "#/components/schemas/cache-purge_FlexPurgeByPrefixes" }, { "$ref": "#/components/schemas/cache-purge_Everything" }, { "$ref": "#/components/schemas/cache-purge_SingleFile" }, { "$ref": "#/components/schemas/cache-purge_SingleFileWithUrlAndHeaders" } ] } } } }, "responses": { "200": { "description": "Request to purge cached content successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-purge_api-response-single-id" } } } }, "4XX": { "description": "Request to purge cached content failed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/cache-purge_api-response-single-id" }, { "$ref": "#/components/schemas/cache-purge_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone" ], "x-api-token-group": [ "Cache Purge" ], "x-cfPermissionsRequired": { "enum": [ "#cache_purge:edit" ] }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "cache", "x-fern-sdk-method-name": "purge", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation will delete cached content for the zone." } }, "/zones/{zone_id}/rate_limit_analytics": { "get": { "operationId": "rate-limit-analytics-get-zone-analytics", "summary": "Get Rate Limiting Analytics", "description": "Returns rate limiting analytics for a zone over the specified time period.\nThe time period divides into time segments of a given length. Each segment\ncontains total action counts and action counts broken down by colo.", "parameters": [ { "name": "zone_id", "in": "path", "description": "Identifier of the zone.", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "pattern": "^[0-9a-f]{32}$" } }, { "name": "since", "in": "query", "description": "The start of the queried time period. Time must be rounded to the time\nsegment boundary and formatted as RFC 3339.", "required": true, "schema": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" } }, { "name": "until", "in": "query", "description": "The exclusive end of the queried time period. Time must be rounded to the\ntime segment boundary and formatted as RFC 3339.", "required": true, "schema": { "type": "string", "format": "date-time", "example": "2024-01-02T00:00:00Z" } }, { "name": "time_delta", "in": "query", "description": "Length (in seconds) of each time segment dividing the entire time period.\nAccepted values are 60 (minute), 3600 (hour), 86400 (day), and 2592000 (month).", "required": true, "schema": { "type": "integer", "example": 3600, "enum": [ 60, 3600, 86400, 2592000 ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rlanalytics_rate_limit_analytics" } } } }, "400": { "description": "Bad request. Invalid or missing parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rlanalytics_api-response-common-failure" } } } }, "401": { "description": "Unauthorized. Missing or invalid authentication credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rlanalytics_api-response-common-failure" } } } }, "403": { "description": "Forbidden. Insufficient permissions for the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rlanalytics_api-response-common-failure" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rlanalytics_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Rate Limiting Analytics" ], "x-api-token-group": [ "Analytics Read" ], "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "rate-limit-analytics", "x-fern-sdk-method-name": "get" } }, "/zones/{zone_id}/rate_limits": { "get": { "operationId": "rate-limits-for-a-zone-list-rate-limits", "summary": "List rate limits", "description": "**Deprecated**: This endpoint returns 410 Gone. Please use the Rulesets API instead.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } }, { "name": "page", "in": "query", "schema": { "description": "Defines the page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Defines the maximum number of results per page. You can only set the value to `1` or to a multiple of 5 such as `5`, `10`, `15`, or `20`.", "type": "number", "default": 20, "maximum": 1000, "minimum": 1 } } ], "responses": { "200": { "description": "List rate limits response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_ratelimit_response_collection" } } } }, "4XX": { "description": "List rate limits response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_ratelimit_response_collection" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Rate limits for a zone" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "rate-limits", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "rate-limits-for-a-zone-create-a-rate-limit", "summary": "Create a rate limit", "description": "**Deprecated**: This endpoint returns 410 Gone. Please use the Rulesets API instead.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/firewall_action" }, "match": { "$ref": "#/components/schemas/firewall_match" }, "period": { "$ref": "#/components/schemas/firewall_period" }, "threshold": { "$ref": "#/components/schemas/firewall_threshold" } }, "required": [ "match", "threshold", "period", "action" ] } } } }, "responses": { "200": { "description": "Create a rate limit response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_ratelimit_response_single" } } } }, "4XX": { "description": "Create a rate limit response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_ratelimit_response_single" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Rate limits for a zone" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rate-limits", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/rate_limits/{rate_limit_id}": { "delete": { "operationId": "rate-limits-for-a-zone-delete-a-rate-limit", "summary": "Delete a rate limit", "description": "**Deprecated**: This endpoint returns 410 Gone. Please use the Rulesets API instead.", "parameters": [ { "name": "rate_limit_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_rate_limit_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "responses": { "200": { "description": "Delete a rate limit response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_ratelimit_response_single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/firewall_id" } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Delete a rate limit response failure.", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/firewall_ratelimit_response_single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/firewall_id" } } } }, "type": "object" } ] }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Rate limits for a zone" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rate-limits", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "rate-limits-for-a-zone-get-a-rate-limit", "summary": "Get a rate limit", "description": "**Deprecated**: This endpoint returns 410 Gone. Please use the Rulesets API instead.", "parameters": [ { "name": "rate_limit_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_rate_limit_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "responses": { "200": { "description": "Get a rate limit response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_ratelimit_response_single" } } } }, "4XX": { "description": "Get a rate limit response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_ratelimit_response_single" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Rate limits for a zone" ], "x-api-token-group": [ "Firewall Services Write", "Firewall Services Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rate-limits", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "rate-limits-for-a-zone-update-a-rate-limit", "summary": "Update a rate limit", "description": "**Deprecated**: This endpoint returns 410 Gone. Please use the Rulesets API instead.", "parameters": [ { "name": "rate_limit_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_rate_limit_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/firewall_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/firewall_action" }, "match": { "$ref": "#/components/schemas/firewall_match" }, "period": { "$ref": "#/components/schemas/firewall_period" }, "threshold": { "$ref": "#/components/schemas/firewall_threshold" } }, "required": [ "match", "threshold", "period", "action" ] } } } }, "responses": { "200": { "description": "Update a rate limit response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/firewall_ratelimit_response_single" } } } }, "4XX": { "description": "Update a rate limit response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/firewall_ratelimit_response_single" }, { "$ref": "#/components/schemas/firewall_api-response-common-failure" } ] } } } } }, "deprecated": true, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Rate limits for a zone" ], "x-api-token-group": [ "Firewall Services Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rate-limits", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/rulesets": { "get": { "operationId": "listZoneRulesets", "summary": "List zone rulesets", "description": "Fetches all rulesets at the zone level.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } }, { "name": "cursor", "in": "query", "schema": { "$ref": "#/components/schemas/rulesets_Cursor" } }, { "name": "per_page", "in": "query", "schema": { "$ref": "#/components/schemas/rulesets_PerPage" } } ], "responses": { "200": { "$ref": "#/components/responses/rulesets_Rulesets" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Rulesets" ], "x-api-token-group": [ "Response Compression Write", "Response Compression Read", "Config Settings Write", "Config Settings Read", "Dynamic URL Redirects Write", "Dynamic URL Redirects Read", "Cache Settings Write", "Cache Settings Read", "Custom Errors Write", "Custom Errors Read", "Origin Write", "Origin Read", "Managed headers Write", "Managed headers Read", "Zone Transform Rules Write", "Zone Transform Rules Read", "Mass URL Redirects Write", "Mass URL Redirects Read", "Magic Firewall Write", "Magic Firewall Read", "L4 DDoS Managed Ruleset Write", "L4 DDoS Managed Ruleset Read", "HTTP DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Read", "Sanitize Write", "Sanitize Read", "Transform Rules Write", "Transform Rules Read", "Select Configuration Write", "Select Configuration Read", "Bot Management Write", "Bot Management Read", "Zone WAF Write", "Zone WAF Read", "Account WAF Write", "Account WAF Read", "Account Rulesets Read", "Account Rulesets Write", "Logs Write", "Logs Read", "Logs Write", "Logs Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rulesets", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "createZoneRuleset", "summary": "Create a zone ruleset", "description": "Creates a ruleset at the zone level.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } }, { "$ref": "#/components/parameters/rulesets_DryRun" } ], "requestBody": { "$ref": "#/components/requestBodies/rulesets_CreateRuleset" }, "responses": { "200": { "$ref": "#/components/responses/rulesets_RulesetOrDryRun" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Rulesets" ], "x-api-token-group": [ "Response Compression Write", "Config Settings Write", "Dynamic URL Redirects Write", "Cache Settings Write", "Custom Errors Write", "Origin Write", "Managed headers Write", "Zone Transform Rules Write", "Mass URL Redirects Write", "Magic Firewall Write", "L4 DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Write", "Sanitize Write", "Transform Rules Write", "Select Configuration Write", "Bot Management Write", "Zone WAF Write", "Account WAF Write", "Account Rulesets Write", "Logs Write", "Logs Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rulesets", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/rulesets/phases/{ruleset_phase}/entrypoint": { "get": { "operationId": "getZoneEntrypointRuleset", "summary": "Get a zone entry point ruleset", "description": "Fetches the latest version of the zone entry point ruleset for a given phase.", "parameters": [ { "name": "ruleset_phase", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetPhase" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } } ], "responses": { "200": { "$ref": "#/components/responses/rulesets_Ruleset" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Rulesets" ], "x-api-token-group": [ "Response Compression Write", "Response Compression Read", "Config Settings Write", "Config Settings Read", "Dynamic URL Redirects Write", "Dynamic URL Redirects Read", "Cache Settings Write", "Cache Settings Read", "Custom Errors Write", "Custom Errors Read", "Origin Write", "Origin Read", "Managed headers Write", "Managed headers Read", "Zone Transform Rules Write", "Zone Transform Rules Read", "Mass URL Redirects Write", "Mass URL Redirects Read", "Magic Firewall Write", "Magic Firewall Read", "L4 DDoS Managed Ruleset Write", "L4 DDoS Managed Ruleset Read", "HTTP DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Read", "Sanitize Write", "Sanitize Read", "Transform Rules Write", "Transform Rules Read", "Select Configuration Write", "Select Configuration Read", "Bot Management Write", "Bot Management Read", "Zone WAF Write", "Zone WAF Read", "Account WAF Write", "Account WAF Read", "Account Rulesets Read", "Account Rulesets Write", "Logs Write", "Logs Read", "Logs Write", "Logs Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rulesets.phases", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "updateZoneEntrypointRuleset", "summary": "Update a zone entry point ruleset", "description": "Updates a zone entry point ruleset, creating a new version.", "parameters": [ { "name": "ruleset_phase", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetPhase" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } }, { "$ref": "#/components/parameters/rulesets_DryRun" } ], "requestBody": { "$ref": "#/components/requestBodies/rulesets_UpdateEntrypointRuleset" }, "responses": { "200": { "$ref": "#/components/responses/rulesets_RulesetOrDryRun" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Rulesets" ], "x-api-token-group": [ "Response Compression Write", "Config Settings Write", "Dynamic URL Redirects Write", "Cache Settings Write", "Custom Errors Write", "Origin Write", "Managed headers Write", "Zone Transform Rules Write", "Mass URL Redirects Write", "Magic Firewall Write", "L4 DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Write", "Sanitize Write", "Transform Rules Write", "Select Configuration Write", "Bot Management Write", "Zone WAF Write", "Account WAF Write", "Account Rulesets Write", "Logs Write", "Logs Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rulesets.phases", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/rulesets/phases/{ruleset_phase}/entrypoint/versions": { "get": { "operationId": "listZoneEntrypointRulesetVersions", "summary": "List a zone entry point ruleset's versions", "description": "Fetches the versions of a zone entry point ruleset.", "parameters": [ { "name": "ruleset_phase", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetPhase" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } } ], "responses": { "200": { "$ref": "#/components/responses/rulesets_Rulesets" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Rulesets" ], "x-api-token-group": [ "Response Compression Write", "Response Compression Read", "Config Settings Write", "Config Settings Read", "Dynamic URL Redirects Write", "Dynamic URL Redirects Read", "Cache Settings Write", "Cache Settings Read", "Custom Errors Write", "Custom Errors Read", "Origin Write", "Origin Read", "Managed headers Write", "Managed headers Read", "Zone Transform Rules Write", "Zone Transform Rules Read", "Mass URL Redirects Write", "Mass URL Redirects Read", "Magic Firewall Write", "Magic Firewall Read", "L4 DDoS Managed Ruleset Write", "L4 DDoS Managed Ruleset Read", "HTTP DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Read", "Sanitize Write", "Sanitize Read", "Transform Rules Write", "Transform Rules Read", "Select Configuration Write", "Select Configuration Read", "Bot Management Write", "Bot Management Read", "Zone WAF Write", "Zone WAF Read", "Account WAF Write", "Account WAF Read", "Account Rulesets Read", "Account Rulesets Write", "Logs Write", "Logs Read", "Logs Write", "Logs Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rulesets.phases.versions", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/zones/{zone_id}/rulesets/phases/{ruleset_phase}/entrypoint/versions/{ruleset_version}": { "get": { "operationId": "getZoneEntrypointRulesetVersion", "summary": "Get a zone entry point ruleset version", "description": "Fetches a specific version of a zone entry point ruleset.", "parameters": [ { "name": "ruleset_version", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetVersion" } }, { "name": "ruleset_phase", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetPhase" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } } ], "responses": { "200": { "$ref": "#/components/responses/rulesets_Ruleset" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Rulesets" ], "x-api-token-group": [ "Response Compression Write", "Response Compression Read", "Config Settings Write", "Config Settings Read", "Dynamic URL Redirects Write", "Dynamic URL Redirects Read", "Cache Settings Write", "Cache Settings Read", "Custom Errors Write", "Custom Errors Read", "Origin Write", "Origin Read", "Managed headers Write", "Managed headers Read", "Zone Transform Rules Write", "Zone Transform Rules Read", "Mass URL Redirects Write", "Mass URL Redirects Read", "Magic Firewall Write", "Magic Firewall Read", "L4 DDoS Managed Ruleset Write", "L4 DDoS Managed Ruleset Read", "HTTP DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Read", "Sanitize Write", "Sanitize Read", "Transform Rules Write", "Transform Rules Read", "Select Configuration Write", "Select Configuration Read", "Bot Management Write", "Bot Management Read", "Zone WAF Write", "Zone WAF Read", "Account WAF Write", "Account WAF Read", "Account Rulesets Read", "Account Rulesets Write", "Logs Write", "Logs Read", "Logs Write", "Logs Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rulesets.phases.versions", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/rulesets/{ruleset_id}": { "delete": { "operationId": "deleteZoneRuleset", "summary": "Delete a zone ruleset", "description": "Deletes all versions of an existing zone ruleset.", "parameters": [ { "name": "ruleset_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetId" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } }, { "$ref": "#/components/parameters/rulesets_DryRun" } ], "responses": { "204": { "$ref": "#/components/responses/rulesets_Empty" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Rulesets" ], "x-api-token-group": [ "Response Compression Write", "Config Settings Write", "Dynamic URL Redirects Write", "Cache Settings Write", "Custom Errors Write", "Origin Write", "Managed headers Write", "Zone Transform Rules Write", "Mass URL Redirects Write", "Magic Firewall Write", "L4 DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Write", "Sanitize Write", "Transform Rules Write", "Select Configuration Write", "Bot Management Write", "Zone WAF Write", "Account WAF Write", "Account Rulesets Write", "Logs Write", "Logs Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rulesets", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "getZoneRuleset", "summary": "Get a zone ruleset", "description": "Fetches the latest version of a zone ruleset.", "parameters": [ { "name": "ruleset_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetId" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } } ], "responses": { "200": { "$ref": "#/components/responses/rulesets_Ruleset" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Rulesets" ], "x-api-token-group": [ "Response Compression Write", "Response Compression Read", "Config Settings Write", "Config Settings Read", "Dynamic URL Redirects Write", "Dynamic URL Redirects Read", "Cache Settings Write", "Cache Settings Read", "Custom Errors Write", "Custom Errors Read", "Origin Write", "Origin Read", "Managed headers Write", "Managed headers Read", "Zone Transform Rules Write", "Zone Transform Rules Read", "Mass URL Redirects Write", "Mass URL Redirects Read", "Magic Firewall Write", "Magic Firewall Read", "L4 DDoS Managed Ruleset Write", "L4 DDoS Managed Ruleset Read", "HTTP DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Read", "Sanitize Write", "Sanitize Read", "Transform Rules Write", "Transform Rules Read", "Select Configuration Write", "Select Configuration Read", "Bot Management Write", "Bot Management Read", "Zone WAF Write", "Zone WAF Read", "Account WAF Write", "Account WAF Read", "Account Rulesets Read", "Account Rulesets Write", "Logs Write", "Logs Read", "Logs Write", "Logs Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rulesets", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "updateZoneRuleset", "summary": "Update a zone ruleset", "description": "Updates a zone ruleset, creating a new version.", "parameters": [ { "name": "ruleset_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetId" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } }, { "$ref": "#/components/parameters/rulesets_DryRun" } ], "requestBody": { "$ref": "#/components/requestBodies/rulesets_UpdateRuleset" }, "responses": { "200": { "$ref": "#/components/responses/rulesets_RulesetOrDryRun" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Rulesets" ], "x-api-token-group": [ "Response Compression Write", "Config Settings Write", "Dynamic URL Redirects Write", "Cache Settings Write", "Custom Errors Write", "Origin Write", "Managed headers Write", "Zone Transform Rules Write", "Mass URL Redirects Write", "Magic Firewall Write", "L4 DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Write", "Sanitize Write", "Transform Rules Write", "Select Configuration Write", "Bot Management Write", "Zone WAF Write", "Account WAF Write", "Account Rulesets Write", "Logs Write", "Logs Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rulesets", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/rulesets/{ruleset_id}/rules": { "post": { "operationId": "createZoneRulesetRule", "summary": "Create a zone ruleset rule", "description": "Adds a new rule to a zone ruleset. The rule will be added to the end of the existing list of rules in the ruleset by default.", "parameters": [ { "name": "ruleset_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetId" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } }, { "$ref": "#/components/parameters/rulesets_DryRun" } ], "requestBody": { "$ref": "#/components/requestBodies/rulesets_Rule" }, "responses": { "200": { "$ref": "#/components/responses/rulesets_RulesetOrDryRun" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Rulesets" ], "x-api-token-group": [ "Response Compression Write", "Config Settings Write", "Dynamic URL Redirects Write", "Cache Settings Write", "Custom Errors Write", "Origin Write", "Managed headers Write", "Zone Transform Rules Write", "Mass URL Redirects Write", "Magic Firewall Write", "L4 DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Write", "Sanitize Write", "Transform Rules Write", "Select Configuration Write", "Bot Management Write", "Zone WAF Write", "Account WAF Write", "Account Rulesets Write", "Logs Write", "Logs Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rulesets.rules", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/rulesets/{ruleset_id}/rules/{rule_id}": { "delete": { "operationId": "deleteZoneRulesetRule", "summary": "Delete a zone ruleset rule", "description": "Deletes an existing rule from a zone ruleset.", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RuleId" } }, { "name": "ruleset_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetId" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } }, { "$ref": "#/components/parameters/rulesets_DryRun" } ], "responses": { "200": { "$ref": "#/components/responses/rulesets_RulesetOrDryRun" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Rulesets" ], "x-api-token-group": [ "Response Compression Write", "Config Settings Write", "Dynamic URL Redirects Write", "Cache Settings Write", "Custom Errors Write", "Origin Write", "Managed headers Write", "Zone Transform Rules Write", "Mass URL Redirects Write", "Magic Firewall Write", "L4 DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Write", "Sanitize Write", "Transform Rules Write", "Select Configuration Write", "Bot Management Write", "Zone WAF Write", "Account WAF Write", "Account Rulesets Write", "Logs Write", "Logs Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rulesets.rules", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "patch": { "operationId": "updateZoneRulesetRule", "summary": "Update a zone ruleset rule", "description": "Updates an existing rule in a zone ruleset.", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RuleId" } }, { "name": "ruleset_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetId" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } }, { "$ref": "#/components/parameters/rulesets_DryRun" } ], "requestBody": { "$ref": "#/components/requestBodies/rulesets_Rule" }, "responses": { "200": { "$ref": "#/components/responses/rulesets_RulesetOrDryRun" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Rulesets" ], "x-api-token-group": [ "Response Compression Write", "Config Settings Write", "Dynamic URL Redirects Write", "Cache Settings Write", "Custom Errors Write", "Origin Write", "Managed headers Write", "Zone Transform Rules Write", "Mass URL Redirects Write", "Magic Firewall Write", "L4 DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Write", "Sanitize Write", "Transform Rules Write", "Select Configuration Write", "Bot Management Write", "Zone WAF Write", "Account WAF Write", "Account Rulesets Write", "Logs Write", "Logs Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rulesets.rules", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/rulesets/{ruleset_id}/versions": { "get": { "operationId": "listZoneRulesetVersions", "summary": "List a zone ruleset's versions", "description": "Fetches the versions of a zone ruleset.", "parameters": [ { "name": "ruleset_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetId" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } } ], "responses": { "200": { "$ref": "#/components/responses/rulesets_Rulesets" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Rulesets" ], "x-api-token-group": [ "Response Compression Write", "Response Compression Read", "Config Settings Write", "Config Settings Read", "Dynamic URL Redirects Write", "Dynamic URL Redirects Read", "Cache Settings Write", "Cache Settings Read", "Custom Errors Write", "Custom Errors Read", "Origin Write", "Origin Read", "Managed headers Write", "Managed headers Read", "Zone Transform Rules Write", "Zone Transform Rules Read", "Mass URL Redirects Write", "Mass URL Redirects Read", "Magic Firewall Write", "Magic Firewall Read", "L4 DDoS Managed Ruleset Write", "L4 DDoS Managed Ruleset Read", "HTTP DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Read", "Sanitize Write", "Sanitize Read", "Transform Rules Write", "Transform Rules Read", "Select Configuration Write", "Select Configuration Read", "Bot Management Write", "Bot Management Read", "Zone WAF Write", "Zone WAF Read", "Account WAF Write", "Account WAF Read", "Account Rulesets Read", "Account Rulesets Write", "Logs Write", "Logs Read", "Logs Write", "Logs Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rulesets.versions", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/zones/{zone_id}/rulesets/{ruleset_id}/versions/{ruleset_version}": { "delete": { "operationId": "deleteZoneRulesetVersion", "summary": "Delete a zone ruleset version", "description": "Deletes an existing version of a zone ruleset.", "parameters": [ { "name": "ruleset_version", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetVersion" } }, { "name": "ruleset_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetId" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } }, { "$ref": "#/components/parameters/rulesets_DryRun" } ], "responses": { "204": { "$ref": "#/components/responses/rulesets_Empty" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Rulesets" ], "x-api-token-group": [ "Response Compression Write", "Config Settings Write", "Dynamic URL Redirects Write", "Cache Settings Write", "Custom Errors Write", "Origin Write", "Managed headers Write", "Zone Transform Rules Write", "Mass URL Redirects Write", "Magic Firewall Write", "L4 DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Write", "Sanitize Write", "Transform Rules Write", "Select Configuration Write", "Bot Management Write", "Zone WAF Write", "Account WAF Write", "Account Rulesets Write", "Logs Write", "Logs Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rulesets.versions", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "getZoneRulesetVersion", "summary": "Get a zone ruleset version", "description": "Fetches a specific version of a zone ruleset.", "parameters": [ { "name": "ruleset_version", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetVersion" } }, { "name": "ruleset_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetId" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } } ], "responses": { "200": { "$ref": "#/components/responses/rulesets_Ruleset" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Rulesets" ], "x-api-token-group": [ "Response Compression Write", "Response Compression Read", "Config Settings Write", "Config Settings Read", "Dynamic URL Redirects Write", "Dynamic URL Redirects Read", "Cache Settings Write", "Cache Settings Read", "Custom Errors Write", "Custom Errors Read", "Origin Write", "Origin Read", "Managed headers Write", "Managed headers Read", "Zone Transform Rules Write", "Zone Transform Rules Read", "Mass URL Redirects Write", "Mass URL Redirects Read", "Magic Firewall Write", "Magic Firewall Read", "L4 DDoS Managed Ruleset Write", "L4 DDoS Managed Ruleset Read", "HTTP DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Read", "Sanitize Write", "Sanitize Read", "Transform Rules Write", "Transform Rules Read", "Select Configuration Write", "Select Configuration Read", "Bot Management Write", "Bot Management Read", "Zone WAF Write", "Zone WAF Read", "Account WAF Write", "Account WAF Read", "Account Rulesets Read", "Account Rulesets Write", "Logs Write", "Logs Read", "Logs Write", "Logs Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rulesets.versions", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/rulesets/{ruleset_id}/versions/{ruleset_version}/by_tag/{rule_tag}": { "get": { "operationId": "listZoneRulesetVersionRulesByTag", "summary": "List a zone ruleset version's rules by tag", "description": "Fetches the rules of a managed zone ruleset version for a given tag.", "parameters": [ { "name": "rule_tag", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RuleCategory" } }, { "name": "ruleset_version", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetVersion" } }, { "name": "ruleset_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_RulesetId" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } } ], "responses": { "200": { "$ref": "#/components/responses/rulesets_Ruleset" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Rulesets" ], "x-api-token-group": [ "Response Compression Write", "Response Compression Read", "Config Settings Write", "Config Settings Read", "Dynamic URL Redirects Write", "Dynamic URL Redirects Read", "Cache Settings Write", "Cache Settings Read", "Custom Errors Write", "Custom Errors Read", "Origin Write", "Origin Read", "Managed headers Write", "Managed headers Read", "Zone Transform Rules Write", "Zone Transform Rules Read", "Mass URL Redirects Write", "Mass URL Redirects Read", "Magic Firewall Write", "Magic Firewall Read", "L4 DDoS Managed Ruleset Write", "L4 DDoS Managed Ruleset Read", "HTTP DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Read", "Sanitize Write", "Sanitize Read", "Transform Rules Write", "Transform Rules Read", "Select Configuration Write", "Select Configuration Read", "Bot Management Write", "Bot Management Read", "Zone WAF Write", "Zone WAF Read", "Account WAF Write", "Account WAF Read", "Account Rulesets Read", "Account Rulesets Write", "Logs Write", "Logs Read", "Logs Write", "Logs Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "rulesets.account-rulesets.versions.zone-by-tag", "x-fern-sdk-method-name": "tag", "x-forge-hidden": true } }, "/zones/{zone_id}/schema_validation/schemas": { "get": { "operationId": "schema-validation-list-schemas-paginated", "summary": "List all uploaded schemas", "description": "Lists all OpenAPI schemas uploaded to API Security.", "parameters": [ { "$ref": "#/components/parameters/api-shield_page" }, { "$ref": "#/components/parameters/api-shield_per_page" }, { "$ref": "#/components/parameters/api-shield_omit_source_query" }, { "name": "validation_enabled", "in": "query", "description": "Filter for enabled schemas", "schema": { "description": "Flag whether schema is enabled for validation.", "type": "boolean" } } ], "responses": { "200": { "$ref": "#/components/responses/api-shield_schemas_list_success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Schema Validation" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.schema-validation.schemas", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ], "post": { "operationId": "schema-validation-create-schema", "summary": "Upload a schema", "description": "Uploads an OpenAPI schema that defines expected request formats for API operations.", "requestBody": { "$ref": "#/components/requestBodies/api-shield_schema_create" }, "responses": { "200": { "$ref": "#/components/responses/api-shield_schema_create_success" }, "4XX": { "$ref": "#/components/responses/api-shield_schema_create_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Schema Validation" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.schema-validation.schemas", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/schema_validation/schemas/hosts": { "get": { "operationId": "schema-validation-list-schema-hosts", "summary": "List hosts covered by uploaded schemas", "description": "Lists all unique hosts found in uploaded OpenAPI schemas for the zone.", "parameters": [ { "$ref": "#/components/parameters/api-shield_page" }, { "$ref": "#/components/parameters/api-shield_per_page" } ], "responses": { "200": { "$ref": "#/components/responses/api-shield_schema_hosts_get_success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Schema Validation" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.schema-validation.schemas.hosts", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ] }, "/zones/{zone_id}/schema_validation/schemas/{schema_id}": { "delete": { "operationId": "schema-validation-delete-schema", "summary": "Delete a schema", "description": "Permanently removes an uploaded OpenAPI schema from API Security. Operations using this schema will lose their validation rules.", "responses": { "200": { "$ref": "#/components/responses/api-shield_schema_delete_success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Schema Validation" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.schema-validation.schemas", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation permanently deletes the uploaded schema and removes its validation coverage." }, "get": { "operationId": "schema-validation-get-schema", "summary": "Get details of a schema", "description": "Gets the contents and metadata of a specific OpenAPI schema uploaded to API Security.", "parameters": [ { "$ref": "#/components/parameters/api-shield_omit_source_query" } ], "responses": { "200": { "$ref": "#/components/responses/api-shield_schema_get_success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Schema Validation" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.schema-validation.schemas", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "$ref": "#/components/parameters/api-shield_schema_id_path" } ], "patch": { "operationId": "schema-validation-edit-schema", "summary": "Set schema validation state", "description": "Enables or disables validation for an uploaded OpenAPI schema without changing the schema document.", "requestBody": { "$ref": "#/components/requestBodies/api-shield_schema_edit" }, "responses": { "200": { "$ref": "#/components/responses/api-shield_schema_edit_success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Schema Validation" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.schema-validation.schemas", "x-fern-sdk-method-name": "set-validation", "x-forge-hidden": true } }, "/zones/{zone_id}/schema_validation/schemas/{schema_id}/operations": { "get": { "operationId": "schema-validation-extract-operations-from-schema", "summary": "Retrieve all operations from the schema", "description": "Retrieves all operations from the schema. Operations that already exist in API Shield Endpoint Management will be returned as full operations.", "parameters": [ { "$ref": "#/components/parameters/api-shield_operation_feature_parameter" }, { "$ref": "#/components/parameters/api-shield_host_parameter" }, { "$ref": "#/components/parameters/api-shield_method_parameter" }, { "$ref": "#/components/parameters/api-shield_endpoint_parameter" }, { "$ref": "#/components/parameters/api-shield_page" }, { "$ref": "#/components/parameters/api-shield_per_page" }, { "name": "operation_status", "in": "query", "description": "Filter results by whether operations exist in Web Asset Management or not. `new` will just return operations from the schema that do not exist otherwise. `existing` will just return operations from the schema that already exist.", "schema": { "type": "string", "example": "new", "enum": [ "new", "existing" ] } } ], "responses": { "200": { "$ref": "#/components/responses/api-shield_schemas_extract_operations_get_success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Schema Validation" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.schema-validation.schemas.operations", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "$ref": "#/components/parameters/api-shield_schema_id_path" } ] }, "/zones/{zone_id}/schema_validation/settings": { "get": { "operationId": "schema-validation-get-settings", "summary": "Get global schema validation settings", "description": "Retrieves the current global schema validation settings for a zone.", "responses": { "200": { "$ref": "#/components/responses/api-shield_global_settings_get_success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Schema Validation Settings" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.schema-validation.settings", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ], "patch": { "operationId": "schema-validation-edit-settings", "summary": "Edit global schema validation settings", "description": "Partially updates global schema validation settings for a zone using PATCH semantics.", "requestBody": { "$ref": "#/components/requestBodies/api-shield_global_settings_edit" }, "responses": { "200": { "$ref": "#/components/responses/api-shield_global_settings_edit_success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Schema Validation Settings" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.schema-validation.settings", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "schema-validation-update-settings", "summary": "Update global schema validation settings", "description": "Fully updates global schema validation settings for a zone, replacing existing configuration.", "requestBody": { "$ref": "#/components/requestBodies/api-shield_global_settings_update" }, "responses": { "200": { "$ref": "#/components/responses/api-shield_global_settings_update_success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Schema Validation Settings" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.schema-validation.settings", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/schema_validation/settings/operations": { "get": { "operationId": "schema-validation-list-per-operation-settings", "summary": "List per-operation schema validation settings", "description": "Lists per-operation schema validation settings configured for the zone.", "parameters": [ { "$ref": "#/components/parameters/api-shield_page" }, { "$ref": "#/components/parameters/api-shield_per_page" } ], "responses": { "200": { "$ref": "#/components/responses/api-shield_per_operation_settings_list_success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Schema Validation Settings" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.schema-validation.settings.operations", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ], "patch": { "operationId": "schema-validation-bulk-edit-per-operation-settings", "summary": "Bulk edit per-operation schema validation settings", "description": "Updates schema validation settings for multiple API operations in a single request. Efficient for applying consistent validation rules across endpoints.", "requestBody": { "$ref": "#/components/requestBodies/api-shield_per_operation_settings_bulk_edit" }, "responses": { "200": { "$ref": "#/components/responses/api-shield_per_operation_settings_bulk_edit_success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Schema Validation Settings" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.schema-validation.settings.operations", "x-fern-sdk-method-name": "bulk-edit", "x-forge-hidden": true } }, "/zones/{zone_id}/schema_validation/settings/operations/{operation_id}": { "delete": { "operationId": "schema-validation-delete-per-operation-setting", "summary": "Delete per-operation schema validation setting", "description": "Removes custom schema validation settings for a specific API operation, reverting to zone-level defaults.", "responses": { "200": { "$ref": "#/components/responses/api-shield_per_operation_settings_delete_success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Schema Validation Settings" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.schema-validation.settings.operations", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes the operation-specific schema validation setting and restores the zone default." }, "get": { "operationId": "schema-validation-get-per-operation-setting", "summary": "Get per-operation schema validation setting", "description": "Retrieves the schema validation settings configured for a specific API operation.", "responses": { "200": { "$ref": "#/components/responses/api-shield_per_operation_setting_get_success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Schema Validation Settings" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.schema-validation.settings.operations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "$ref": "#/components/parameters/api-shield_operation_id" } ], "put": { "operationId": "schema-validation-update-per-operation-setting", "summary": "Update per-operation schema validation setting", "description": "Fully updates schema validation settings for a specific API operation.", "requestBody": { "$ref": "#/components/requestBodies/api-shield_per_operation_setting_update" }, "responses": { "200": { "$ref": "#/components/responses/api-shield_per_operation_setting_update_success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Schema Validation Settings" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.schema-validation.settings.operations", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/secondary_dns/force_axfr": { "post": { "operationId": "secondary-dns-(-secondary-zone)-force-axfr", "summary": "Force AXFR", "description": "Sends AXFR zone transfer request to primary nameserver(s).", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/secondary-dns_identifier" } } ], "responses": { "200": { "description": "Force AXFR response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_force_response" } } } }, "4XX": { "description": "Force AXFR response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/secondary-dns_force_response" }, { "$ref": "#/components/schemas/secondary-dns_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Secondary DNS (Secondary Zone)" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write", "DNS Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.zone-transfers.force-axfr", "x-fern-sdk-method-name": "create" } }, "/zones/{zone_id}/secondary_dns/incoming": { "delete": { "operationId": "secondary-dns-(-secondary-zone)-delete-secondary-zone-configuration", "summary": "Delete Secondary Zone Configuration", "description": "Delete secondary zone configuration for incoming zone transfers.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/secondary-dns_identifier" } } ], "responses": { "200": { "description": "Delete Secondary Zone Configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_id_response" } } } }, "4XX": { "description": "Delete Secondary Zone Configuration response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/secondary-dns_id_response" }, { "$ref": "#/components/schemas/secondary-dns_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Secondary DNS (Secondary Zone)" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write", "DNS Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.zone-transfers.incoming", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "secondary-dns-(-secondary-zone)-secondary-zone-configuration-details", "summary": "Secondary Zone Configuration Details", "description": "Get secondary zone configuration for incoming zone transfers.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/secondary-dns_identifier" } } ], "responses": { "200": { "description": "Secondary Zone Configuration Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_single_response_incoming" } } } }, "4XX": { "description": "Secondary Zone Configuration Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/secondary-dns_single_response_incoming" }, { "$ref": "#/components/schemas/secondary-dns_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Secondary DNS (Secondary Zone)" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read", "DNS Read", "Zone Write", "DNS Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.zone-transfers.incoming", "x-fern-sdk-method-name": "get" }, "post": { "operationId": "secondary-dns-(-secondary-zone)-create-secondary-zone-configuration", "summary": "Create Secondary Zone Configuration", "description": "Create secondary zone configuration for incoming zone transfers.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/secondary-dns_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_dns-secondary-secondary-zone" } } } }, "responses": { "200": { "description": "Create Secondary Zone Configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_single_response_incoming" } } } }, "4XX": { "description": "Create Secondary Zone Configuration response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/secondary-dns_single_response_incoming" }, { "$ref": "#/components/schemas/secondary-dns_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Secondary DNS (Secondary Zone)" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write", "DNS Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.zone-transfers.incoming", "x-fern-sdk-method-name": "create" }, "put": { "operationId": "secondary-dns-(-secondary-zone)-update-secondary-zone-configuration", "summary": "Update Secondary Zone Configuration", "description": "Update secondary zone configuration for incoming zone transfers.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/secondary-dns_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_dns-secondary-secondary-zone" } } } }, "responses": { "200": { "description": "Update Secondary Zone Configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_single_response_incoming" } } } }, "4XX": { "description": "Update Secondary Zone Configuration response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/secondary-dns_single_response_incoming" }, { "$ref": "#/components/schemas/secondary-dns_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Secondary DNS (Secondary Zone)" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write", "DNS Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.zone-transfers.incoming", "x-fern-sdk-method-name": "update" } }, "/zones/{zone_id}/secondary_dns/outgoing": { "delete": { "operationId": "secondary-dns-(-primary-zone)-delete-primary-zone-configuration", "summary": "Delete Primary Zone Configuration", "description": "Delete primary zone configuration for outgoing zone transfers.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/secondary-dns_identifier" } } ], "responses": { "200": { "description": "Delete Primary Zone Configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_id_response" } } } }, "4XX": { "description": "Delete Primary Zone Configuration response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/secondary-dns_id_response" }, { "$ref": "#/components/schemas/secondary-dns_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Secondary DNS (Primary Zone)" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write", "DNS Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.zone-transfers.outgoing", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "secondary-dns-(-primary-zone)-primary-zone-configuration-details", "summary": "Primary Zone Configuration Details", "description": "Get primary zone configuration for outgoing zone transfers.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/secondary-dns_identifier" } } ], "responses": { "200": { "description": "Primary Zone Configuration Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_single_response_outgoing" } } } }, "4XX": { "description": "Primary Zone Configuration Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/secondary-dns_single_response_outgoing" }, { "$ref": "#/components/schemas/secondary-dns_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Secondary DNS (Primary Zone)" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read", "DNS Read", "Zone Write", "DNS Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.zone-transfers.outgoing", "x-fern-sdk-method-name": "get" }, "post": { "operationId": "secondary-dns-(-primary-zone)-create-primary-zone-configuration", "summary": "Create Primary Zone Configuration", "description": "Create primary zone configuration for outgoing zone transfers.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/secondary-dns_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_single_request_outgoing" } } } }, "responses": { "200": { "description": "Create Primary Zone Configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_single_response_outgoing" } } } }, "4XX": { "description": "Create Primary Zone Configuration response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/secondary-dns_single_response_outgoing" }, { "$ref": "#/components/schemas/secondary-dns_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Secondary DNS (Primary Zone)" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write", "DNS Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.zone-transfers.outgoing", "x-fern-sdk-method-name": "create" }, "put": { "operationId": "secondary-dns-(-primary-zone)-update-primary-zone-configuration", "summary": "Update Primary Zone Configuration", "description": "Update primary zone configuration for outgoing zone transfers.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/secondary-dns_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_single_request_outgoing" } } } }, "responses": { "200": { "description": "Update Primary Zone Configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_single_response_outgoing" } } } }, "4XX": { "description": "Update Primary Zone Configuration response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/secondary-dns_single_response_outgoing" }, { "$ref": "#/components/schemas/secondary-dns_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Secondary DNS (Primary Zone)" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write", "DNS Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.zone-transfers.outgoing", "x-fern-sdk-method-name": "update" } }, "/zones/{zone_id}/secondary_dns/outgoing/disable": { "post": { "operationId": "secondary-dns-(-primary-zone)-disable-outgoing-zone-transfers", "summary": "Disable Outgoing Zone Transfers", "description": "Disable outgoing zone transfers for primary zone and clears IXFR backlog of primary zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/secondary-dns_identifier" } } ], "responses": { "200": { "description": "Disable Outgoing Zone Transfers response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_disable_transfer_response" } } } }, "4XX": { "description": "Disable Outgoing Zone Transfers response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/secondary-dns_disable_transfer_response" }, { "$ref": "#/components/schemas/secondary-dns_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Secondary DNS (Primary Zone)" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write", "DNS Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.zone-transfers.outgoing", "x-fern-sdk-method-name": "disable", "x-forge-require-confirmation": "This operation turns off outgoing zone transfers for the primary zone, which means secondary zones will stop receiving updates." } }, "/zones/{zone_id}/secondary_dns/outgoing/enable": { "post": { "operationId": "secondary-dns-(-primary-zone)-enable-outgoing-zone-transfers", "summary": "Enable Outgoing Zone Transfers", "description": "Enable outgoing zone transfers for primary zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/secondary-dns_identifier" } } ], "responses": { "200": { "description": "Enable Outgoing Zone Transfers response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_enable_transfer_response" } } } }, "4XX": { "description": "Enable Outgoing Zone Transfers response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/secondary-dns_enable_transfer_response" }, { "$ref": "#/components/schemas/secondary-dns_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Secondary DNS (Primary Zone)" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write", "DNS Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.zone-transfers.outgoing", "x-fern-sdk-method-name": "enable" } }, "/zones/{zone_id}/secondary_dns/outgoing/force_notify": { "post": { "operationId": "secondary-dns-(-primary-zone)-force-dns-notify", "summary": "Force DNS NOTIFY", "description": "Notifies the secondary nameserver(s) and clears IXFR backlog of primary zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/secondary-dns_identifier" } } ], "responses": { "200": { "description": "Force DNS NOTIFY response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_force_response-2" } } } }, "4XX": { "description": "Force DNS NOTIFY response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/secondary-dns_force_response-2" }, { "$ref": "#/components/schemas/secondary-dns_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Secondary DNS (Primary Zone)" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write", "DNS Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.zone-transfers.outgoing", "x-fern-sdk-method-name": "force-notify" } }, "/zones/{zone_id}/secondary_dns/outgoing/status": { "get": { "operationId": "secondary-dns-(-primary-zone)-get-outgoing-zone-transfer-status", "summary": "Get Outgoing Zone Transfer Status", "description": "Get primary zone transfer status.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/secondary-dns_identifier" } } ], "responses": { "200": { "description": "Get Outgoing Zone Transfer Status response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secondary-dns_enable_transfer_response" } } } }, "4XX": { "description": "Get Outgoing Zone Transfer Status response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/secondary-dns_enable_transfer_response" }, { "$ref": "#/components/schemas/secondary-dns_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Secondary DNS (Primary Zone)" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read", "DNS Read", "Zone Write", "DNS Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "dns.zone-transfers.outgoing.status", "x-fern-sdk-method-name": "get" } }, "/zones/{zone_id}/security-center/insights": { "get": { "operationId": "get-zone-security-center-insights", "summary": "Retrieves Zone Security Center Insights", "description": "Lists Security Center insights for a specific zone, showing zone-level security findings.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/security-center_identifier" } }, { "name": "dismissed", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_dismissed" } }, { "name": "issue_class", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_issueClasses" } }, { "name": "issue_type", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_issueTypes" } }, { "name": "product", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_products" } }, { "name": "source", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_sources" } }, { "name": "severity", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_severityQueryParam" } }, { "name": "subject", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_subjects" } }, { "name": "issue_class~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_issueClasses" } }, { "name": "issue_type~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_issueTypes" } }, { "name": "product~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_products" } }, { "name": "severity~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_severityQueryParam" } }, { "name": "subject~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_subjects" } }, { "name": "page", "in": "query", "schema": { "default": 1, "allOf": [ { "$ref": "#/components/schemas/security-center_page" } ] } }, { "name": "per_page", "in": "query", "schema": { "default": 25, "allOf": [ { "$ref": "#/components/schemas/security-center_perPage" } ] } } ], "responses": { "200": { "description": "The request was successful.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/security-center_api-response-common" }, { "properties": { "result": { "anyOf": [ { "properties": { "count": { "$ref": "#/components/schemas/security-center_count" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/security-center_issue" } }, "page": { "$ref": "#/components/schemas/security-center_page" }, "per_page": { "$ref": "#/components/schemas/security-center_perPage" } }, "type": "object" } ] } }, "type": "object" } ] } } } }, "4XX": { "description": "A client error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "Security Center Insights" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "security-center.zone-insights", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/security-center/insights/audit-log": { "get": { "operationId": "get-zone-security-center-audit-log", "summary": "Retrieves Zone Audit Log", "description": "Lists audit log entries for all Security Center insights in a specific zone, showing changes to insight status and classification.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/security-center_identifier" } }, { "$ref": "#/components/parameters/security-center_auditLogPerPage" }, { "$ref": "#/components/parameters/security-center_auditLogCursor" }, { "$ref": "#/components/parameters/security-center_auditLogFieldChanged" }, { "$ref": "#/components/parameters/security-center_auditLogChangedBy" }, { "$ref": "#/components/parameters/security-center_auditLogSince" }, { "$ref": "#/components/parameters/security-center_auditLogBefore" }, { "$ref": "#/components/parameters/security-center_auditLogOrder" } ], "responses": { "200": { "description": "The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_auditLogResponse" } } } }, "4XX": { "description": "A client error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "Security Center Audit Log" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "security-center.zone-audit-logs", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/zones/{zone_id}/security-center/insights/class": { "get": { "operationId": "get-zone-security-center-insight-counts-by-class", "summary": "Retrieves Zone Security Center Insight Counts by Class", "description": "Retrieves zone-specific Security Center insight counts aggregated by classification class.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/security-center_identifier" } }, { "name": "dismissed", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_dismissed" } }, { "name": "issue_class", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_issueClasses" } }, { "name": "issue_type", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_issueTypes" } }, { "name": "product", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_products" } }, { "name": "source", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_sources" } }, { "name": "severity", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_severityQueryParam" } }, { "name": "subject", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_subjects" } }, { "name": "issue_class~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_issueClasses" } }, { "name": "issue_type~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_issueTypes" } }, { "name": "product~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_products" } }, { "name": "severity~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_severityQueryParam" } }, { "name": "subject~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_subjects" } } ], "responses": { "200": { "description": "The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_valueCountsResponse" } } } }, "4XX": { "description": "A client error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "Security Center Insights" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "security-center.zone-insights.class", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/security-center/insights/scans": { "get": { "operationId": "get-security-center-zone-scans", "summary": "Get Recent Zone Scans", "description": "Returns the most recent on-demand scans for a specific zone, up to a maximum of 5. Each scan includes its ID, start time, and current status. Results include both zone-specific scans and account-wide scans (which cover all zones). Also returns quota information showing how many scans have been used and how many remain in the current 24-hour window.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/security-center_identifier" } } ], "responses": { "200": { "description": "The request was successful.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/security-center_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/security-center_scansListResponse" } }, "type": "object" } ] } } } }, "4XX": { "description": "A client error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "Security Center Scans" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "security-center.zone-scans", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "start-security-center-zone-scan", "summary": "Start On-Demand Zone Scan", "description": "Initiates an on-demand security scan for a specific zone. Rate limited to 5 scans per account per 24-hour window (shared with account-level scans).", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/security-center_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_newScanRequest" } } } }, "responses": { "200": { "description": "The request was successful.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/security-center_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/security-center_newScanResponse" } }, "type": "object" } ] } } } }, "4XX": { "description": "A client error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "Security Center Scans" ], "x-api-token-group": [ "Zone Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "security-center.zone-scans", "x-fern-sdk-method-name": "start", "x-forge-hidden": true } }, "/zones/{zone_id}/security-center/insights/severity": { "get": { "operationId": "get-zone-security-center-insight-counts-by-severity", "summary": "Retrieves Zone Security Center Insight Counts by Severity", "description": "Retrieves zone-specific Security Center insight counts aggregated by severity level.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/security-center_identifier" } }, { "name": "dismissed", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_dismissed" } }, { "name": "issue_class", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_issueClasses" } }, { "name": "issue_type", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_issueTypes" } }, { "name": "product", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_products" } }, { "name": "source", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_sources" } }, { "name": "severity", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_severityQueryParam" } }, { "name": "subject", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_subjects" } }, { "name": "issue_class~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_issueClasses" } }, { "name": "issue_type~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_issueTypes" } }, { "name": "product~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_products" } }, { "name": "severity~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_severityQueryParam" } }, { "name": "subject~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_subjects" } } ], "responses": { "200": { "description": "The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_valueCountsResponse" } } } }, "4XX": { "description": "A client error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "Security Center Insights" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "security-center.zone-insights.severity", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/security-center/insights/type": { "get": { "operationId": "get-zone-security-center-insight-counts-by-type", "summary": "Retrieves Zone Security Center Insight Counts by Type", "description": "Retrieves zone-specific Security Center insight counts aggregated by insight type.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/security-center_identifier" } }, { "name": "dismissed", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_dismissed" } }, { "name": "issue_class", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_issueClasses" } }, { "name": "issue_type", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_issueTypes" } }, { "name": "product", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_products" } }, { "name": "source", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_sources" } }, { "name": "severity", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_severityQueryParam" } }, { "name": "subject", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_subjects" } }, { "name": "issue_class~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_issueClasses" } }, { "name": "issue_type~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_issueTypes" } }, { "name": "product~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_products" } }, { "name": "severity~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_severityQueryParam" } }, { "name": "subject~neq", "in": "query", "schema": { "$ref": "#/components/schemas/security-center_subjects" } } ], "responses": { "200": { "description": "The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_valueCountsResponse" } } } }, "4XX": { "description": "A client error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "Security Center Insights" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "security-center.zone-insights.type", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/security-center/insights/{issue_id}/audit-log": { "get": { "operationId": "get-zone-security-center-issue-audit-log", "summary": "Retrieves Zone Issue Audit Log", "description": "Lists audit log entries for a specific Security Center insight within a zone, showing changes to its status and classification over time.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/security-center_identifier" } }, { "name": "issue_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/security-center_auditLogPerPage" }, { "$ref": "#/components/parameters/security-center_auditLogCursor" }, { "$ref": "#/components/parameters/security-center_auditLogFieldChanged" }, { "$ref": "#/components/parameters/security-center_auditLogChangedBy" }, { "$ref": "#/components/parameters/security-center_auditLogSince" }, { "$ref": "#/components/parameters/security-center_auditLogBefore" }, { "$ref": "#/components/parameters/security-center_auditLogOrder" } ], "responses": { "200": { "description": "The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_auditLogResponse" } } } }, "4XX": { "description": "A client error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "Security Center Audit Log" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "security-center.zone-audit-logs", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/security-center/insights/{issue_id}/classification": { "patch": { "operationId": "update-zone-security-center-insight-classification", "summary": "Updates Zone Security Center Insight Classification", "description": "Updates the user classification for a zone-specific Security Center insight. Valid values are 'false_positive' or 'accept_risk'. To reset, set classification to null. Cannot change directly between classification values - must reset to null first.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/security-center_identifier" } }, { "name": "issue_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_userClassificationUpdate" } } } }, "responses": { "200": { "description": "The request was successful.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/security-center_api-response-single" } ] } } } }, "4XX": { "description": "A client error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "Security Center Insights" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "security-center.zone-insights", "x-fern-sdk-method-name": "update-classification", "x-forge-hidden": true } }, "/zones/{zone_id}/security-center/insights/{issue_id}/dismiss": { "put": { "operationId": "archive-zone-security-center-insight", "summary": "Archives Zone Security Center Insight", "description": "Archives a zone-specific Security Center insight, removing it from the active zone insights while preserving historical data.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/security-center_identifier" } }, { "name": "issue_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dismiss": { "type": "boolean", "default": true, "x-auditable": true } } } } } }, "responses": { "200": { "description": "The request was successful.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/security-center_api-response-single" } ] } } } }, "4XX": { "description": "A client error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "Security Center Insights" ], "x-api-token-group": [ "Zone Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "security-center.zone-insights.dismiss", "x-fern-sdk-method-name": "update", "x-forge-hidden": true, "x-forge-params": { "dismiss": { "default": null } } } }, "/zones/{zone_id}/security-center/securitytxt": { "delete": { "operationId": "delete-security-txt", "summary": "Deletes security.txt", "description": "Removes the security.txt file configuration for a zone. The /.well-known/security.txt endpoint will no longer be served.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/security-center_identifier" } } ], "responses": { "200": { "description": "The request was successful.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/security-center_api-response-single" } ] } } } }, "4XX": { "description": "A client error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "security.txt" ], "x-api-token-group": [ "Zone Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "security-txt", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "get-security-txt", "summary": "Retrieves security.txt", "description": "Retrieves the current security.txt file configuration for a zone, used for security vulnerability reporting.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/security-center_identifier" } } ], "responses": { "200": { "description": "The request was successful.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/security-center_api-response-common" }, { "properties": { "result": { "anyOf": [ { "$ref": "#/components/schemas/security-center_securityTxt" } ] } }, "type": "object" } ] } } } }, "4XX": { "description": "A client error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "security.txt" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "security-txt", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "update-security-txt", "summary": "Updates security.txt", "description": "Updates the security.txt file configuration for a zone, which provides security researchers with vulnerability reporting information.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/security-center_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_securityTxt" } } } }, "responses": { "200": { "description": "The request was successful.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/security-center_api-response-single" } ] } } } }, "4XX": { "description": "A client error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-center_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] } ], "tags": [ "security.txt" ], "x-api-token-group": [ "Zone Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "security-txt", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/settings": { "get": { "operationId": "zone-settings-get-all-zone-settings", "summary": "Get all zone settings", "description": "Available settings for your user in relation to a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier" } } ], "responses": { "200": { "description": "Get all Zone settings response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_zone_settings_response_collection" } } } }, "4XX": { "description": "Get all Zone settings response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-common-failure-3" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "zones.settings", "x-fern-sdk-method-name": "list", "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" }, "x-stainless-deprecation-message": "This endpoint is deprecated. Zone settings should instead be managed individually." }, "patch": { "operationId": "zone-settings-edit-zone-settings-info", "summary": "Edit multiple zone settings", "description": "Edit settings for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_multiple_settings" } } } }, "responses": { "200": { "description": "Edit zone settings info response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_zone_settings_response_collection" } } } }, "4XX": { "description": "Edit zone settings info response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-common-failure-3" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "zones.settings", "x-fern-sdk-method-name": "bulk-edit", "x-forge-sunset": { "date": "2030-01-01T00:00:00Z" }, "x-stainless-deprecation-message": "This endpoint is deprecated. Zone settings should instead be managed individually." } }, "/zones/{zone_id}/settings/aegis": { "get": { "operationId": "zone-cache-settings-get-aegis-setting", "summary": "Get aegis setting", "description": "Aegis provides dedicated egress IPs (from Cloudflare to your origin) for your layer 7 WAF and CDN services. The egress IPs are reserved exclusively for your account so that you can increase your origin security by only allowing traffic from a small list of IP addresses.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "Get aegis setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_aegis_response_value" } ] } } } }, "4XX": { "description": "Get aegis setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read", "Zone Read", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.aegis", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "zone-cache-settings-change-aegis-setting", "summary": "Change aegis setting", "description": "Aegis provides dedicated egress IPs (from Cloudflare to your origin) for your layer 7 WAF and CDN services. The egress IPs are reserved exclusively for your account so that you can increase your origin security by only allowing traffic from a small list of IP addresses.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/cache-rules_aegis_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Change aegis setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_aegis_response_value" } ] } } } }, "4XX": { "description": "Change aegis setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.aegis", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/settings/auto_origin_tls_kex": { "get": { "operationId": "ssl-detector-auto-origin-tls-kex-get-enrollment", "summary": "Get Auto-Origin TLS KEX enrollment status for the given zone", "description": "When enabled, Cloudflare automatically selects the preferred TLS key-exchange algorithm to use when establishing the TLS connection to the zone's origin, picking from the algorithms permitted by the zone's `origin_tls_compliance_modes` setting. When disabled, the default key-exchange ordering is used.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache_identifier" } } ], "responses": { "200": { "description": "Get Auto-Origin TLS KEX enrollment status response.", "content": { "application/json": { "examples": { "Disabled": { "$ref": "#/components/examples/cache_auto_origin_tls_kex_disabled_response" }, "Enabled": { "$ref": "#/components/examples/cache_auto_origin_tls_kex_enabled_response" } }, "schema": { "$ref": "#/components/schemas/cache_auto_origin_tls_kex_response" } } } }, "4XX": { "description": "Get Auto-Origin TLS KEX enrollment status failure.", "content": { "application/json": { "examples": { "Error": { "$ref": "#/components/examples/cache_auto_origin_tls_kex_error_response" } }, "schema": { "$ref": "#/components/schemas/cache_auto_origin_tls_kex_failure_response" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin TLS" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ssl.auto-origin-tls-kex", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "ssl-detector-auto-origin-tls-kex-patch-enrollment", "summary": "Patch Auto-Origin TLS KEX enrollment status for the given zone", "description": "Enable or disable Auto-Origin TLS KEX selection for the zone by sending `{\"enabled\": true}` or `{\"enabled\": false}`. When enabled, Cloudflare runs a periodic scan of the zone's origins to determine the preferred key-exchange algorithm and writes that preference to the edge so it is sent first in the TLS ClientHello to the origin.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache_auto_origin_tls_kex_patch" } } } }, "responses": { "200": { "description": "Patch Auto-Origin TLS KEX enrollment status response.", "content": { "application/json": { "examples": { "Disabled": { "$ref": "#/components/examples/cache_auto_origin_tls_kex_disabled_response" }, "Enabled": { "$ref": "#/components/examples/cache_auto_origin_tls_kex_enabled_response" } }, "schema": { "$ref": "#/components/schemas/cache_auto_origin_tls_kex_response" } } } }, "4XX": { "description": "Patch Auto-Origin TLS KEX enrollment status failure.", "content": { "application/json": { "examples": { "Error": { "$ref": "#/components/examples/cache_auto_origin_tls_kex_error_response" } }, "schema": { "$ref": "#/components/schemas/cache_auto_origin_tls_kex_failure_response" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin TLS" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ssl.auto-origin-tls-kex", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/settings/automatic_platform_optimization": { "get": { "operationId": "zone-settings-get-automatic-platform-optimization-setting", "summary": "Get Automatic Platform Optimization setting", "description": "Automatic Platform Optimization (APO) for WordPress is a performance feature that serves your\nWordPress site from Cloudflare's edge network, reducing load times for visitors.\nRefer to the APO documentation for more information.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "responses": { "200": { "description": "Get Automatic Platform Optimization setting response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_automatic_platform_optimization_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Get Automatic Platform Optimization setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.automatic-platform-optimization", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "zone-settings-change-automatic-platform-optimization-setting", "summary": "Change Automatic Platform Optimization setting", "description": "Automatic Platform Optimization (APO) for WordPress is a performance feature that serves your\nWordPress site from Cloudflare's edge network, reducing load times for visitors.\nRefer to the APO documentation for more information.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/speed_automatic_platform_optimization_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Change Automatic Platform Optimization setting response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_automatic_platform_optimization_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Change Automatic Platform Optimization setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.automatic-platform-optimization", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/settings/binary_ast": { "get": { "operationId": "zone-settings-get-binary-ast-setting", "summary": "Get Binary AST setting", "description": "Binary AST is a new binary encoding for JavaScript that enables faster parsing of scripts.\nWhen enabled, Cloudflare will serve a binary-encoded version of JavaScript to compatible browsers.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "responses": { "200": { "description": "Get Binary AST setting response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_binary_ast_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Get Binary AST setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.binary-ast", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "zone-settings-change-binary-ast-setting", "summary": "Change Binary AST setting", "description": "Binary AST is a new binary encoding for JavaScript that enables faster parsing of scripts.\nWhen enabled, Cloudflare will serve a binary-encoded version of JavaScript to compatible browsers.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/speed_binary_ast_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Change Binary AST setting response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_binary_ast_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Change Binary AST setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.binary-ast", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/settings/csam_scanner_third_party": { "get": { "operationId": "csam-scanner-get-setting", "summary": "Get CSAM Scanner setting", "description": "Retrieve the current CSAM Scanner configuration for a zone.\n\nThe notification email is masked by default in responses.\n", "parameters": [ { "$ref": "#/components/parameters/csam-config-service_zone_id" } ], "responses": { "200": { "description": "CSAM Scanner setting response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csam-config-service_csam_scanner_single_response" } } } }, "400": { "description": "Bad request - malformed zone ID in URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csam-config-service_api_response_common_failure" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csam-config-service_api_response_common_failure" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csam-config-service_api_response_common_failure" } } } }, "404": { "description": "Zone not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csam-config-service_api_response_common_failure" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csam-config-service_api_response_common_failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "CSAM Scanner Settings" ], "x-api-token-group": [ "Zone Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "csamScanner", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "csam-scanner-update-setting", "summary": "Update CSAM Scanner setting", "description": "Update the CSAM Scanner configuration for a zone. Allows enabling or\ndisabling CSAM scanning, updating the notification email, and\nconfiguring scanning sources.\n\nWhen a new email is provided, email verification is triggered\nautomatically. The `enabled` field is a toggle; the server may\nadjust it based on whether the notification email is verified.\n\nReturns 403 if the zone or account is locked by Trust & Safety.\n", "parameters": [ { "$ref": "#/components/parameters/csam-config-service_zone_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csam-config-service_csam_scanner_third_party_update_request" } } } }, "responses": { "200": { "description": "CSAM Scanner setting updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csam-config-service_csam_scanner_single_response" } } } }, "400": { "description": "Bad request - validation failure or malformed request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csam-config-service_api_response_common_failure" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csam-config-service_api_response_common_failure" } } } }, "403": { "description": "Forbidden - zone or account is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csam-config-service_api_response_common_failure" } } } }, "404": { "description": "Zone not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csam-config-service_api_response_common_failure" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/csam-config-service_api_response_common_failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "CSAM Scanner Settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "csamScanner", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/settings/fonts": { "get": { "operationId": "zone-settings-get-fonts-setting", "summary": "Get Cloudflare Fonts setting", "description": "Enhance your website's font delivery with Cloudflare Fonts. Deliver Google Hosted fonts from your own domain,\nboost performance, and enhance user privacy. Refer to the Cloudflare Fonts documentation for more information.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "responses": { "200": { "description": "Get Cloudflare Fonts setting response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_cloudflare_fonts" } }, "type": "object" } ] } } } }, "4XX": { "description": "Get Cloudflare Fonts setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.fonts", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "zone-settings-change-fonts-setting", "summary": "Change Cloudflare Fonts setting", "description": "Enhance your website's font delivery with Cloudflare Fonts. Deliver Google Hosted fonts from your own domain,\nboost performance, and enhance user privacy. Refer to the Cloudflare Fonts documentation for more information.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/speed_cloudflare_fonts_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Change Cloudflare Fonts setting response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_cloudflare_fonts" } }, "type": "object" } ] } } } }, "4XX": { "description": "Change Cloudflare Fonts setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.fonts", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/settings/google-tag-gateway/config": { "get": { "operationId": "zone-settings-get-google-tag-gateway-config", "summary": "Get Google Tag Gateway configuration", "description": "Gets the Google Tag Gateway configuration for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/google-tag-gateway_identifier" } } ], "responses": { "200": { "description": "Get Google Tag Gateway configuration response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/google-tag-gateway_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/google-tag-gateway_google-tag-gateway-config" } }, "type": "object" } ] } } } }, "4XX": { "description": "Get Google Tag Gateway configuration response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google-tag-gateway_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Google Tag Gateway" ], "x-api-token-group": [ "Zaraz Edit", "Zaraz Read", "Zaraz Admin" ], "x-cfPermissionsRequired": { "enum": [ "#zaraz:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "google-tag-gateway.config", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "zone-settings-change-google-tag-gateway-config", "summary": "Update Google Tag Gateway configuration", "description": "Updates the Google Tag Gateway configuration for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/google-tag-gateway_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google-tag-gateway_google-tag-gateway-config" } } } }, "responses": { "200": { "description": "Update Google Tag Gateway configuration response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/google-tag-gateway_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/google-tag-gateway_google-tag-gateway-config" } }, "type": "object" } ] } } } }, "4XX": { "description": "Update Google Tag Gateway configuration response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/google-tag-gateway_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Google Tag Gateway" ], "x-api-token-group": [ "Zaraz Edit", "Zaraz Admin" ], "x-cfPermissionsRequired": { "enum": [ "#zaraz:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "google-tag-gateway.config", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/settings/h2_prioritization": { "get": { "operationId": "zone-settings-get-h2-prioritization-setting", "summary": "Get HTTP/2 Prioritization setting", "description": "HTTP/2 Prioritization controls the order in which assets are delivered to browsers.\nCloudflare's HTTP/2 Prioritization overrides the default browser prioritization order,\nimproving the loading performance of web pages.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "responses": { "200": { "description": "Get HTTP/2 Prioritization setting response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_h2_prioritization_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Get HTTP/2 Prioritization setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.h2-prioritization", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "zone-settings-change-h2-prioritization-setting", "summary": "Change HTTP/2 Prioritization setting", "description": "HTTP/2 Prioritization controls the order in which assets are delivered to browsers.\nCloudflare's HTTP/2 Prioritization overrides the default browser prioritization order,\nimproving the loading performance of web pages.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/speed_h2_prioritization_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Change HTTP/2 Prioritization setting response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_h2_prioritization_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Change HTTP/2 Prioritization setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.h2-prioritization", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/settings/image_resizing": { "get": { "operationId": "zone-settings-get-image-resizing-setting", "summary": "Get Image Transformations setting", "description": "Gets the Image Transformations setting for a zone. Accepted values are `off`, `on`, `open`, and `latest`.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "responses": { "200": { "description": "Get Image Resizing setting response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_image_resizing_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Get Image Resizing setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.image-resizing", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "zone-settings-change-image-resizing-setting", "summary": "Change Image Transformations setting", "description": "Sets the Image Transformations setting for a zone. Accepted values are `off`, `on`, `open`, and `latest`.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/speed_image_resizing_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Change Image Resizing setting response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_image_resizing_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Change Image Resizing setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.image-resizing", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/settings/nel": { "get": { "operationId": "nel-settings-get", "summary": "Get NEL setting", "description": "Fetches the Network Error Logging (NEL) setting for a zone. NEL allows browsers to report network errors to a configured endpoint. The setting is enabled by default for free and pro zones, and disabled by default for business and enterprise zones unless the NEL product feature is enabled.\n", "parameters": [ { "name": "zone_id", "in": "path", "description": "Identifier of the zone.", "required": true, "schema": { "$ref": "#/components/schemas/nel-config_zone_identifier" } } ], "responses": { "200": { "description": "NEL setting response", "content": { "application/json": { "examples": { "nel_disabled": { "summary": "NEL disabled (enterprise zone default)", "value": { "errors": [], "messages": [], "result": { "editable": false, "id": "nel", "modified_on": "0001-01-01T00:00:00Z", "value": { "enabled": false } }, "success": true } }, "nel_enabled": { "summary": "NEL enabled (free/pro zone default)", "value": { "errors": [], "messages": [], "result": { "editable": true, "id": "nel", "modified_on": "2024-01-15T10:30:00Z", "value": { "enabled": true } }, "success": true } } }, "schema": { "$ref": "#/components/schemas/nel-config_nel_setting_response" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "examples": { "unauthorized": { "summary": "Missing or invalid authentication", "value": { "errors": [ { "code": 1009, "message": "auth.not_authorized" } ], "messages": [], "result": null, "success": false } } }, "schema": { "$ref": "#/components/schemas/nel-config_api_response_failure" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "examples": { "forbidden": { "summary": "Missing zone_settings:read permission", "value": { "errors": [ { "code": 1010, "message": "auth.forbidden" } ], "messages": [], "result": null, "success": false } } }, "schema": { "$ref": "#/components/schemas/nel-config_api_response_failure" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "examples": { "internal_error": { "summary": "Database or upstream failure", "value": { "errors": [ { "code": 1000, "message": "internal_error" } ], "messages": [], "result": null, "success": false } } }, "schema": { "$ref": "#/components/schemas/nel-config_api_response_failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "NEL Settings" ], "x-api-token-group": [ "Zone Settings Read" ] }, "patch": { "operationId": "nel-settings-edit", "summary": "Edit NEL setting", "description": "Updates the Network Error Logging (NEL) setting for a zone. Requires the NEL product feature to be enabled for the zone. The setting controls whether browsers report network errors to Cloudflare's NEL endpoint.\n", "parameters": [ { "name": "zone_id", "in": "path", "description": "Identifier of the zone.", "required": true, "schema": { "$ref": "#/components/schemas/nel-config_zone_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "examples": { "disable_nel": { "summary": "Disable NEL", "value": { "value": { "enabled": false } } }, "enable_nel": { "summary": "Enable NEL", "value": { "value": { "enabled": true } } } }, "schema": { "$ref": "#/components/schemas/nel-config_nel_setting_patch" } } } }, "responses": { "200": { "description": "Updated NEL setting response", "content": { "application/json": { "examples": { "nel_updated": { "summary": "NEL setting updated successfully", "value": { "errors": [], "messages": [], "result": { "editable": true, "id": "nel", "modified_on": "2024-01-15T10:30:00Z", "value": { "enabled": true } }, "success": true } } }, "schema": { "$ref": "#/components/schemas/nel-config_nel_setting_response" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "examples": { "invalid_content_type": { "summary": "Request Content-Type is not application/json", "value": { "errors": [ { "code": 1001, "message": "invalid_content_type" } ], "messages": [], "result": null, "success": false } }, "invalid_json": { "summary": "Invalid JSON body", "value": { "errors": [ { "code": 1001, "message": "invalid_json_body" } ], "messages": [], "result": null, "success": false } }, "missing_value": { "summary": "Missing value field in request body", "value": { "errors": [ { "code": 1001, "message": "missing_value" } ], "messages": [], "result": null, "success": false } } }, "schema": { "$ref": "#/components/schemas/nel-config_api_response_failure" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "examples": { "unauthorized": { "summary": "Missing or invalid authentication", "value": { "errors": [ { "code": 1009, "message": "auth.not_authorized" } ], "messages": [], "result": null, "success": false } } }, "schema": { "$ref": "#/components/schemas/nel-config_api_response_failure" } } } }, "403": { "description": "Insufficient permissions or NEL feature not enabled", "content": { "application/json": { "examples": { "forbidden": { "summary": "Missing zone_settings:edit permission or NEL feature not enabled", "value": { "errors": [ { "code": 1010, "message": "auth.forbidden" } ], "messages": [], "result": null, "success": false } } }, "schema": { "$ref": "#/components/schemas/nel-config_api_response_failure" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "examples": { "internal_error": { "summary": "Database or upstream failure", "value": { "errors": [ { "code": 1000, "message": "internal_error" } ], "messages": [], "result": null, "success": false } } }, "schema": { "$ref": "#/components/schemas/nel-config_api_response_failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "NEL Settings" ], "x-api-token-group": [ "Zone Settings Write" ] } }, "/zones/{zone_id}/settings/origin_h2_max_streams": { "get": { "operationId": "zone-cache-settings-get-origin-h2-max-streams-setting", "summary": "Get Origin H2 Max Streams Setting", "description": "Origin H2 Max Streams configures the max number of concurrent requests that Cloudflare will send within the same connection when communicating with the origin server, if the origin supports it. Note that if your origin does not support H2 multiplexing, 5xx errors may be observed, particularly 520s. Also note that the default value is `100` for all plan types except Enterprise where it is `1`. `1` means that H2 multiplexing is disabled.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "Get Origin H2 Max Streams setting response.", "content": { "application/json": { "examples": { "origin_h2_max_streams_50": { "$ref": "#/components/examples/cache-rules_origin_h2_max_streams_50" } }, "schema": { "$ref": "#/components/schemas/cache-rules_origin_h2_max_streams_response_value" } } } }, "4XX": { "description": "Get Origin H2 Max Streams setting response failure.", "content": { "application/json": { "examples": { "Error": { "$ref": "#/components/examples/cache-rules_dummy_error_response" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read", "Zone Read", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.origin-h2-max-streams", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "zone-cache-settings-change-origin-h2-max-streams-setting", "summary": "Change Origin H2 Max Streams Setting", "description": "Origin H2 Max Streams configures the max number of concurrent requests that Cloudflare will send within the same connection when communicating with the origin server, if the origin supports it. Note that if your origin does not support H2 multiplexing, 5xx errors may be observed, particularly 520s. Also note that the default value is `100` for all plan types except Enterprise where it is `1`. `1` means that H2 multiplexing is disabled.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/cache-rules_origin_h2_max_streams_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Change Origin H2 Max Streams setting response.", "content": { "application/json": { "examples": { "origin_h2_max_streams_50": { "$ref": "#/components/examples/cache-rules_origin_h2_max_streams_50" } }, "schema": { "$ref": "#/components/schemas/cache-rules_origin_h2_max_streams_response_value" } } } }, "4XX": { "description": "Change Origin H2 Max Streams response failure.", "content": { "application/json": { "examples": { "Error": { "$ref": "#/components/examples/cache-rules_dummy_error_response" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.origin-h2-max-streams", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/settings/origin_max_http_version": { "get": { "operationId": "zone-cache-settings-get-origin-max-http-version-setting", "summary": "Get Origin Max HTTP Version Setting", "description": "Origin Max HTTP Setting Version sets the highest HTTP version Cloudflare will attempt to use with your origin. This setting allows Cloudflare to make HTTP/2 requests to your origin. (Refer to [Enable HTTP/2 to Origin](https://developers.cloudflare.com/cache/how-to/enable-http2-to-origin/), for more information.). The default value is \"2\" for all plan types except Enterprise where it is \"1\".", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "Get Origin Max HTTP Version setting response.", "content": { "application/json": { "examples": { "max_http_version_2": { "$ref": "#/components/examples/cache-rules_origin_max_http_version_2" } }, "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_origin_max_http_version_response_value" } ] } } } }, "4XX": { "description": "Get Origin Max HTTP Version setting response failure.", "content": { "application/json": { "examples": { "Error": { "$ref": "#/components/examples/cache-rules_dummy_error_response" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read", "Zone Read", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.origin-max-http-version", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "zone-cache-settings-change-origin-max-http-version-setting", "summary": "Change Origin Max HTTP Version Setting", "description": "Origin Max HTTP Setting Version sets the highest HTTP version Cloudflare will attempt to use with your origin. This setting allows Cloudflare to make HTTP/2 requests to your origin. (Refer to [Enable HTTP/2 to Origin](https://developers.cloudflare.com/cache/how-to/enable-http2-to-origin/), for more information.). The default value is \"2\" for all plan types except Enterprise where it is \"1\".", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/cache-rules_origin_max_http_version_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Change Origin Max HTTP Version setting response.", "content": { "application/json": { "examples": { "max_http_version_2": { "$ref": "#/components/examples/cache-rules_origin_max_http_version_2" } }, "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_origin_max_http_version_response_value" } ] } } } }, "4XX": { "description": "Change Origin Max HTTP Version response failure.", "content": { "application/json": { "examples": { "Error": { "$ref": "#/components/examples/cache-rules_dummy_error_response" } }, "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.origin-max-http-version", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/settings/origin_tls_compliance_modes": { "delete": { "operationId": "zone-cache-settings-delete-origin-tls-compliance-modes-setting", "summary": "Delete Origin TLS Compliance Modes setting", "description": "Delete the Origin TLS Compliance Modes setting for the zone, removing any configured compliance constraint. After deletion, Cloudflare's default behavior applies (no compliance filtering of the key-exchange algorithm list sent to the origin).", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "Delete Origin TLS Compliance Modes setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_delete_response_single" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_origin_tls_compliance_modes" } }, "type": "object" } ] } } } }, "4XX": { "description": "Delete Origin TLS Compliance Modes setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin TLS" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } }, "get": { "operationId": "zone-cache-settings-get-origin-tls-compliance-modes-setting", "summary": "Get Origin TLS Compliance Modes setting", "description": "Origin TLS Compliance Modes constrains the set of TLS key-exchange algorithms Cloudflare may use when establishing the TLS connection to the zone's origin. The value is a list of named compliance modes (currently `fips` and `pqh`). Multiple modes are combined as the intersection of their permitted algorithm lists. An empty list (or no rule configured) means no compliance constraint is applied.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "responses": { "200": { "description": "Get Origin TLS Compliance Modes setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_origin_tls_compliance_modes_response_value" } ] } } } }, "4XX": { "description": "Get Origin TLS Compliance Modes setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin TLS" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } }, "patch": { "operationId": "zone-cache-settings-change-origin-tls-compliance-modes-setting", "summary": "Change Origin TLS Compliance Modes setting", "description": "Update the set of TLS compliance modes for the zone. PATCH performs a full replace of the modes list, not a merge — the request body is treated as the complete new list, and any modes not present in it are removed. (To remove a single mode from an existing configuration, send the updated list without it.) The request body must be of the form `{\"value\": [\"fips\", \"pqh\"]}`. Currently supported modes are `fips` and `pqh`; an empty list clears the constraint. Future modes (e.g. `cnsa2`) may be added; clients should treat unknown values as opaque strings. Invalid mode values are rejected with a 4xx response.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/cache-rules_origin_tls_compliance_modes_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Change Origin TLS Compliance Modes setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_origin_tls_compliance_modes_response_value" } ] } } } }, "4XX": { "description": "Change Origin TLS Compliance Modes setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin TLS" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } }, "put": { "operationId": "zone-cache-settings-replace-origin-tls-compliance-modes-setting", "summary": "Replace Origin TLS Compliance Modes setting", "description": "Replace the entire set of TLS compliance modes for the zone with the list provided in the request body. PUT performs a full replace, not a merge — any modes not present in the request body are removed. The request body must be of the form `{\"value\": [\"fips\", \"pqh\"]}`. Currently supported modes are `fips` and `pqh`; an empty list clears the constraint. Future modes (e.g. `cnsa2`) may be added; clients should treat unknown values as opaque strings. Invalid mode values are rejected with a 4xx response.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache-rules_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/cache-rules_origin_tls_compliance_modes_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Replace Origin TLS Compliance Modes setting response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_zone_cache_settings_response_single" }, { "$ref": "#/components/schemas/cache-rules_origin_tls_compliance_modes_response_value" } ] } } } }, "4XX": { "description": "Replace Origin TLS Compliance Modes setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache-rules_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Origin TLS" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true } } }, "/zones/{zone_id}/settings/rum": { "get": { "operationId": "web-analytics-get-rum-status", "summary": "Get RUM status for a zone", "description": "Retrieves RUM status for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rum_identifier" } } ], "responses": { "200": { "description": "Rum Status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rum_rum-site-response-single" } } } }, "4XX": { "description": "Failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rum_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Web Analytics" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.rum", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "web-analytics-toggle-rum", "summary": "Toggle RUM on/off for a zone", "description": "Toggles RUM on/off for an existing zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rum_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rum_toggle-rum-request" } } } }, "responses": { "200": { "description": "Rum toggled on/off for an existing zone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rum_rum-site-response-single" } } } }, "4XX": { "description": "Failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rum_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Web Analytics" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.rum", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/settings/speed_brain": { "get": { "operationId": "zone-settings-get-speed-brain-setting", "summary": "Get Cloudflare Speed Brain setting", "description": "Speed Brain lets compatible browsers speculate on content which can be prefetched or preloaded, making website\nnavigation faster. Refer to the Cloudflare Speed Brain documentation for more information.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "responses": { "200": { "description": "Get Cloudflare Speed Brain setting response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_cloudflare_speed_brain_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Get Cloudflare Speed Brain setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.speed-brain", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "zone-settings-change-speed-brain-setting", "summary": "Change Cloudflare Speed Brain setting", "description": "Speed Brain lets compatible browsers speculate on content which can be prefetched or preloaded, making website\nnavigation faster. Refer to the Cloudflare Speed Brain documentation for more information.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "description": "Whether the feature is enabled or disabled.", "type": "string", "enum": [ "on", "off" ] } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Cloudflare Speed Brain setting response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_cloudflare_speed_brain_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Change Cloudflare Speed Brain setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.speed-brain", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/settings/ssl_automatic_mode": { "get": { "operationId": "ssl-detector-automatic-mode-get-enrollment", "summary": "Get Automatic SSL/TLS enrollment status for the given zone", "description": "If the system is enabled, the response will include next_scheduled_scan, representing the next time this zone will be scanned and the zone's ssl/tls encryption mode is potentially upgraded by the system. If the system is disabled, next_scheduled_scan will not be present in the response body.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache_identifier" } } ], "responses": { "200": { "description": "Get Automatic SSL/TLS Enrollment status response.", "content": { "application/json": { "examples": { "Disabled": { "$ref": "#/components/examples/cache_dummy_automatic_upgrader_enabled_response" }, "Enabled": { "$ref": "#/components/examples/cache_dummy_automatic_upgrader_disabled_response" } }, "schema": { "$ref": "#/components/schemas/cache_api-response-single-id" } } } }, "4XX": { "description": "Get Automatic SSL/TLS Enrollment status failure.", "content": { "application/json": { "examples": { "Error": { "$ref": "#/components/examples/cache_dummy_error_response" } }, "schema": { "$ref": "#/components/schemas/cache_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Automatic SSL/TLS" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read", "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ssl.automatic-upgrader", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "ssl-detector-automatic-mode-patch-enrollment", "summary": "Patch Automatic SSL/TLS Enrollment status for given zone", "description": "The automatic system is enabled when this endpoint is hit with value in the request body is set to \"auto\", and disabled when the request body value is set to \"custom\".", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache_schemas_patch" } } } }, "responses": { "200": { "description": "Patch Automatic SSL/TLS Enrollment status response.", "content": { "application/json": { "examples": { "Enabled": { "$ref": "#/components/examples/cache_dummy_automatic_upgrader_enabled_response" } }, "schema": { "$ref": "#/components/schemas/cache_api-response-single-id" } } } }, "4XX": { "description": "Patch Automatic SSL/TLS Enrollment status failure.", "content": { "application/json": { "examples": { "Error": { "$ref": "#/components/examples/cache_dummy_error_response" } }, "schema": { "$ref": "#/components/schemas/cache_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Automatic SSL/TLS" ], "x-api-token-group": [ "Zone Settings Write", "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read", "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ssl.automatic-upgrader", "x-fern-sdk-method-name": "patch", "x-forge-hidden": true } }, "/zones/{zone_id}/settings/transformations_allowed_origins": { "get": { "operationId": "zone-settings-get-transformations-allowed-origins-setting", "summary": "Get Image Transformations Allowed Origins setting", "description": "Media Transformations Allowed Origins restricts transformations for images and video served through\nCloudflare's network to requests originating from specified domains. Refer to the\nImage Transformations and Video Transformations documentation for more information.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "responses": { "200": { "description": "Get Image Transformations Allowed Origins setting response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_transformations_allowed_origins_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Get Image Transformations Allowed Origins setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.transformations-allowed-origins", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "zone-settings-change-transformations-allowed-origins-setting", "summary": "Change Image Transformations Allowed Origins setting", "description": "Media Transformations Allowed Origins restricts transformations for images and video served through\nCloudflare's network to requests originating from specified domains. Refer to the\nImage Transformations and Video Transformations documentation for more information.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/speed_transformations_allowed_origins_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Change Image Transformations Allowed Origins setting response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_transformations_allowed_origins_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Change Image Transformations Allowed Origins setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.transformations-allowed-origins", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/settings/transformations_c2pa": { "get": { "operationId": "zone-settings-get-transformations-c2pa-setting", "summary": "Get Image Transformations C2PA setting", "description": "C2PA (Coalition for Content Provenance and Authenticity) signing adds cryptographic metadata\nto images processed through Cloudflare Image Transformations, enabling verification of image\nauthenticity and provenance.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "responses": { "200": { "description": "Get Image Transformations C2PA setting response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_transformations_c2pa_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Get Image Transformations C2PA setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.transformations-c2pa", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "zone-settings-change-transformations-c2pa-setting", "summary": "Change Image Transformations C2PA setting", "description": "C2PA (Coalition for Content Provenance and Authenticity) signing adds cryptographic metadata\nto images processed through Cloudflare Image Transformations, enabling verification of image\nauthenticity and provenance.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/speed_transformations_c2pa_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Change Image Transformations C2PA setting response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_transformations_c2pa_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Change Image Transformations C2PA setting response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.transformations-c2pa", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/settings/transformations_config": { "get": { "operationId": "zone-settings-get-transformations-config", "summary": "Get Transformations configuration", "description": "Returns the combined Transformations configuration for a zone, including the transformations\ntoggle, allowed origins, and C2PA signing settings in a single response.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "responses": { "200": { "description": "Get Transformations configuration response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_transformations_config_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Get Transformations configuration response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.transformations-config", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "zone-settings-change-transformations-config", "summary": "Change Transformations configuration", "description": "Updates one or more fields of the combined Transformations configuration for a zone.\nOmitted fields are left unchanged. The response always returns the full current state\nof all three sub-settings.\n", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/speed_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/speed_transformations_config_value" } }, "required": [ "value" ] } } } }, "responses": { "200": { "description": "Change Transformations configuration response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/speed_transformations_config_response" } }, "type": "object" } ] } } } }, "4XX": { "description": "Change Transformations configuration response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/speed_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.transformations-config", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/settings/zaraz/config": { "get": { "operationId": "get-zones-zone_identifier-zaraz-config", "summary": "Get Zaraz configuration", "description": "Gets latest Zaraz configuration for a zone. It can be preview or published configuration, whichever was the last updated. Secret variables values will not be included.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zaraz_identifier" } } ], "responses": { "200": { "description": "Get Zaraz configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_zaraz-config-response" } } } }, "4XX": { "description": "Get Zaraz configuration response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zaraz" ], "x-api-token-group": [ "Zaraz Edit", "Zaraz Read", "Zaraz Admin" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zaraz.config", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "put-zones-zone_identifier-zaraz-config", "summary": "Update Zaraz configuration", "description": "Updates Zaraz configuration for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zaraz_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_zaraz-config-body" } } } }, "responses": { "200": { "description": "Update Zaraz configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_zaraz-config-response" } } } }, "4XX": { "description": "Update Zaraz configuration response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zaraz" ], "x-api-token-group": [ "Zaraz Edit", "Zaraz Admin" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zaraz.config", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/settings/zaraz/default": { "get": { "operationId": "get-zones-zone_identifier-zaraz-default", "summary": "Get default Zaraz configuration", "description": "Gets default Zaraz configuration for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zaraz_identifier" } } ], "responses": { "200": { "description": "Get Zaraz default configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_zaraz-config-response" } } } }, "4XX": { "description": "Get Zaraz default configuration response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zaraz" ], "x-api-token-group": [ "Zaraz Edit", "Zaraz Read", "Zaraz Admin" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zaraz.default", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/settings/zaraz/export": { "get": { "operationId": "get-zones-zone_identifier-zaraz-export", "summary": "Export Zaraz configuration", "description": "Exports full current published Zaraz configuration for a zone, secret variables included.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zaraz_identifier" } } ], "responses": { "200": { "description": "Get Zaraz configuration response.", "headers": { "Content-Disposition": { "example": "attachment; filename=zaraz-2023-11-10-23-00.json", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_zaraz-config-return" } } } }, "4XX": { "description": "Get Zaraz configuration response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zaraz" ], "x-api-token-group": [ "Zaraz Edit", "Zaraz Read", "Zaraz Admin" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zaraz.export", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/settings/zaraz/history": { "get": { "operationId": "get-zones-zone_identifier-zaraz-history", "summary": "List Zaraz historical configuration records", "description": "Lists a history of published Zaraz configuration records for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zaraz_identifier" } }, { "name": "offset", "in": "query", "description": "Ordinal number to start listing the results with. Default value is 0.", "schema": { "type": "integer", "minimum": 0 }, "example": 0 }, { "name": "limit", "in": "query", "description": "Maximum amount of results to list. Default value is 10.", "schema": { "type": "integer", "minimum": 1 }, "example": 10 }, { "name": "sortField", "in": "query", "description": "The field to sort by. Default is updated_at.", "schema": { "type": "string", "enum": [ "id", "user_id", "description", "created_at", "updated_at" ] }, "example": "updated_at" }, { "name": "sortOrder", "in": "query", "description": "Sorting order. Default is DESC.", "schema": { "type": "string", "enum": [ "DESC", "ASC" ] }, "example": "DESC" } ], "responses": { "200": { "description": "List Zaraz historical configuration records response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_zaraz-history-response" } } } }, "4XX": { "description": "List Zaraz historical configuration records failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zaraz" ], "x-api-token-group": [ "Zaraz Edit", "Zaraz Read", "Zaraz Admin" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zaraz.history", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "put": { "operationId": "put-zones-zone_identifier-zaraz-history", "summary": "Restore Zaraz historical configuration by ID", "description": "Restores a historical published Zaraz configuration by ID for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zaraz_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "ID of the Zaraz configuration to restore.", "type": "integer", "example": 12345, "minimum": 1 } } } }, "responses": { "200": { "description": "Restore Zaraz historical configuration by ID response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_zaraz-config-response" } } } }, "4XX": { "description": "Restore Zaraz historical configuration by ID failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zaraz" ], "x-api-token-group": [ "Zaraz Edit", "Zaraz Admin" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zaraz.history", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/settings/zaraz/history/configs": { "get": { "operationId": "get-zones-zone_identifier-zaraz-config-history", "summary": "Get Zaraz historical configurations by ID(s)", "description": "Gets a history of published Zaraz configurations by ID(s) for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zaraz_identifier" } }, { "name": "ids", "in": "query", "description": "Comma separated list of Zaraz configuration IDs.", "required": true, "schema": { "type": "array", "items": { "type": "integer" } }, "example": [ 12345, 23456 ], "explode": false, "style": "form" } ], "responses": { "200": { "description": "Get Zaraz historical configurations by ID(s) response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_zaraz-config-history-response" } } } }, "4XX": { "description": "Get Zaraz historical configurations by ID(s) failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zaraz" ], "x-api-token-group": [ "Zaraz Edit", "Zaraz Read", "Zaraz Admin" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zaraz.history.configs", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/settings/zaraz/publish": { "post": { "operationId": "post-zones-zone_identifier-zaraz-publish", "summary": "Publish Zaraz preview configuration", "description": "Publish current Zaraz preview configuration for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zaraz_identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Zaraz configuration description.", "type": "string", "example": "Config with enabled ecommerce tracking" } } } }, "responses": { "200": { "description": "Update Zaraz workflow response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zaraz_api-response-common" }, { "properties": { "result": { "type": "string", "example": "Config has been published successfully" } }, "type": "object" } ] } } } }, "4XX": { "description": "Update Zaraz workflow response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zaraz" ], "x-api-token-group": [ "Zaraz Admin" ], "x-cfPermissionsRequired": { "enum": [ "#zaraz:publish" ] }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zaraz.publish", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/settings/zaraz/workflow": { "get": { "operationId": "get-zones-zone_identifier-zaraz-workflow", "summary": "Get Zaraz workflow", "description": "Gets Zaraz workflow for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zaraz_identifier" } } ], "responses": { "200": { "description": "Get Zaraz workflow response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_zaraz-workflow-response" } } } }, "4XX": { "description": "Get Zaraz workflow response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zaraz" ], "x-api-token-group": [ "Zaraz Edit", "Zaraz Read", "Zaraz Admin" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zaraz.workflow", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "put-zones-zone_identifier-zaraz-workflow", "summary": "Update Zaraz workflow", "description": "Updates Zaraz workflow for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zaraz_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_zaraz-workflow" } } } }, "responses": { "200": { "description": "Update Zaraz workflow response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_zaraz-workflow-response" } } } }, "4XX": { "description": "Update Zaraz workflow response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zaraz_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zaraz" ], "x-api-token-group": [ "Zaraz Edit", "Zaraz Admin" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zaraz.workflow", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/settings/{setting_id}": { "get": { "operationId": "zone-settings-get-single-setting", "summary": "Get zone setting", "description": "Fetch a single zone setting by name", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier" } }, { "name": "setting_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_setting_name" } } ], "responses": { "200": { "description": "Get zone setting response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common-4" }, { "properties": { "result": { "$ref": "#/components/schemas/zones_setting" } } } ] } } } }, "4XX": { "description": "Get zone setting response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-common-failure-3" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.settings", "x-fern-sdk-method-name": "get" }, "patch": { "operationId": "zone-settings-edit-single-setting", "summary": "Edit zone setting", "description": "Updates a single zone setting by the identifier", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_identifier" } }, { "name": "setting_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/zones_setting_name" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_zone_settings_single_request" } } } }, "responses": { "200": { "description": "Edit zone setting response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common-4" }, { "properties": { "result": { "$ref": "#/components/schemas/zones_setting" } } } ] } } } }, "4XX": { "description": "Edit zone settings info response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/zones_api-response-common-failure-3" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Settings" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.settings", "x-fern-sdk-method-name": "edit" } }, "/zones/{zone_id}/smart_shield": { "get": { "operationId": "smart-shield-get-settings", "summary": "Get Smart Shield Settings", "description": "Retrieve Smart Shield Settings.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/smartshield_identifier" } } ], "responses": { "200": { "description": "Smart Shield Settings response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/smartshield_api-response-common" }, { "$ref": "#/components/schemas/smartshield_single_smart_shield_get_response" } ] } } } }, "500": { "description": "Get Smart Shield Settings response failure.", "content": { "application/json": { "examples": { "Invalid value": { "$ref": "#/components/examples/smartshield_smart_shield_500_response" } }, "schema": { "$ref": "#/components/schemas/smartshield_api-response-common-failure" } } } }, "502": { "description": "Get Smart Shield Settings response failure.", "content": { "application/json": { "examples": { "Not found": { "$ref": "#/components/examples/smartshield_smart_shield_502_get_response" } }, "schema": { "$ref": "#/components/schemas/smartshield_api-response-common-failure" } } } }, "4XX": { "description": "Patch Smart Shield Settings response failure.", "content": { "application/json": { "examples": { "Invalid value": { "$ref": "#/components/examples/smartshield_smart_shield_4xx_get_response" } }, "schema": { "$ref": "#/components/schemas/smartshield_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Smart Shield Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read", "Zone Read", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "smart-shield", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "smart-shield-patch-settings", "summary": "Patch Smart Shield Settings", "description": "Set Smart Shield Settings.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/smartshield_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/smartshield_smart_shield_settings_patch_body" } } } }, "responses": { "200": { "description": "Smart Shield Settings response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/smartshield_api-response-common" }, { "$ref": "#/components/schemas/smartshield_single_smart_shield_patch_response" } ] } } } }, "500": { "description": "Get Smart Shield Settings response failure.", "content": { "application/json": { "examples": { "Invalid value": { "$ref": "#/components/examples/smartshield_smart_shield_500_response" } }, "schema": { "$ref": "#/components/schemas/smartshield_api-response-common-failure" } } } }, "502": { "description": "Smart Shield Settings response failure.", "content": { "application/json": { "examples": { "Not found": { "$ref": "#/components/examples/smartshield_smart_shield_502_patch_response" } }, "schema": { "$ref": "#/components/schemas/smartshield_api-response-common-failure" } } } }, "4XX": { "description": "Patch Smart Shield Settings response failure.", "content": { "application/json": { "examples": { "Invalid value": { "$ref": "#/components/examples/smartshield_smart_shield_4xx_get_response" } }, "schema": { "$ref": "#/components/schemas/smartshield_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Smart Shield Settings" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read", "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "smart-shield", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/smart_shield/cache_reserve_clear": { "get": { "operationId": "smart-shield-settings-get-cache-reserve-clear", "summary": "Get Cache Reserve Clear", "description": "You can use Cache Reserve Clear to clear your Cache Reserve, but you must first disable Cache Reserve. In most cases, this will be accomplished within 24 hours. You cannot re-enable Cache Reserve while this process is ongoing. Keep in mind that you cannot undo or cancel this operation.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/smartshield_identifier" } } ], "responses": { "200": { "description": "Get Cache Reserve Clear response.", "content": { "application/json": { "examples": { "Completed": { "$ref": "#/components/examples/smartshield_cache_reserve_clear_completed" }, "In-progress": { "$ref": "#/components/examples/smartshield_cache_reserve_clear_in_progress" } }, "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/smartshield_api-response-common" }, { "$ref": "#/components/schemas/smartshield_cache_reserve_clear_response_value" } ] } } } }, "4XX": { "description": "Get Cache Reserve Clear failure response.", "content": { "application/json": { "examples": { "Not found": { "$ref": "#/components/examples/smartshield_cache_reserve_clear_not_found" } }, "schema": { "$ref": "#/components/schemas/smartshield_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Cache Reserve Clear" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read", "Zone Read", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "smart-shield.cache-reserve-clear", "x-fern-sdk-method-name": "status", "x-forge-hidden": true }, "post": { "operationId": "smart-shield-settings-start-cache-reserve-clear", "summary": "Start Cache Reserve Clear", "description": "You can use Cache Reserve Clear to clear your Cache Reserve, but you must first disable Cache Reserve. In most cases, this will be accomplished within 24 hours. You cannot re-enable Cache Reserve while this process is ongoing. Keep in mind that you cannot undo or cancel this operation.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/smartshield_identifier" } } ], "requestBody": { "description": "The request body is currently not used.", "required": true, "content": { "application/json": { "example": "{}" } } }, "responses": { "200": { "description": "Start Cache Reserve Clear response.", "content": { "application/json": { "examples": { "In-progress": { "$ref": "#/components/examples/smartshield_cache_reserve_clear_in_progress" } }, "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/smartshield_api-response-common" }, { "$ref": "#/components/schemas/smartshield_cache_reserve_clear_response_value" } ] } } } }, "4XX": { "description": "Start Cache Reserve Clear failure response.", "content": { "application/json": { "examples": { "Rejected": { "$ref": "#/components/examples/smartshield_cache_reserve_clear_rejected_cr_on" } }, "schema": { "$ref": "#/components/schemas/smartshield_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Cache Reserve Clear" ], "x-api-token-group": [ "Zone Settings Write", "Zone Write" ], "x-cfPermissionsRequired": { "enum": [ "#zone_settings:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "smart-shield.cache-reserve-clear", "x-fern-sdk-method-name": "clear", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation permanently clears Cache Reserve for this zone and cannot be undone." } }, "/zones/{zone_id}/smart_shield/healthchecks": { "get": { "operationId": "smart-shield-list-health-checks", "summary": "List Health Checks", "description": "List configured health checks.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/smartshield_identifier" } }, { "$ref": "#/components/parameters/smartshield_page" }, { "$ref": "#/components/parameters/smartshield_per_page" } ], "responses": { "200": { "description": "List Health Checks response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/smartshield_response_collection" } } } }, "4XX": { "description": "List Health Checks response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/smartshield_response_collection" }, { "$ref": "#/components/schemas/smartshield_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Health Checks" ], "x-api-token-group": [ "Health Checks Write", "Health Checks Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "smart-shield.health-checks", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "smart-shield-create-health-check", "summary": "Create Health Check", "description": "Create a new health check.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/smartshield_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/smartshield_query_healthcheck" } } } }, "responses": { "200": { "description": "Create Health Check response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/smartshield_single_hc_response" } } } }, "4XX": { "description": "Create Health Check response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/smartshield_single_hc_response" }, { "$ref": "#/components/schemas/smartshield_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Health Checks" ], "x-api-token-group": [ "Health Checks Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "smart-shield.health-checks", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/smart_shield/healthchecks/{healthcheck_id}": { "delete": { "operationId": "smart-shield-delete-health-check", "summary": "Delete Health Check", "description": "Delete a health check.", "parameters": [ { "name": "healthcheck_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/smartshield_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/smartshield_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": {} } }, "responses": { "200": { "description": "Delete Health Check response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/smartshield_single_hc_id_response" } } } }, "4XX": { "description": "Delete Health Check response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/smartshield_single_hc_id_response" }, { "$ref": "#/components/schemas/smartshield_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Health Checks" ], "x-api-token-group": [ "Health Checks Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "smart-shield.health-checks", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "smart-shield-health-check-details", "summary": "Health Check Details", "description": "Fetch a single configured health check.", "parameters": [ { "name": "healthcheck_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/smartshield_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/smartshield_identifier" } } ], "responses": { "200": { "description": "Health Check Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/smartshield_single_hc_response" } } } }, "4XX": { "description": "Health Check Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/smartshield_single_hc_response" }, { "$ref": "#/components/schemas/smartshield_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Health Checks" ], "x-api-token-group": [ "Health Checks Write", "Health Checks Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "smart-shield.health-checks", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "smart-shield-patch-health-check", "summary": "Patch Health Check", "description": "Patch a configured health check.", "parameters": [ { "name": "healthcheck_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/smartshield_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/smartshield_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/smartshield_query_healthcheck" } } } }, "responses": { "200": { "description": "Patch Health Check response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/smartshield_single_hc_response" } } } }, "4XX": { "description": "Patch Health Check response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/smartshield_single_hc_response" }, { "$ref": "#/components/schemas/smartshield_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Health Checks" ], "x-api-token-group": [ "Health Checks Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "smart-shield.health-checks", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "smart-shield-update-health-check", "summary": "Update Health Check", "description": "Update a configured health check.", "parameters": [ { "name": "healthcheck_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/smartshield_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/smartshield_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/smartshield_single_hc_response" } } } }, "responses": { "200": { "description": "Update Health Check response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/smartshield_single_hc_response" } } } }, "4XX": { "description": "Update Health Check response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/smartshield_single_hc_response" }, { "$ref": "#/components/schemas/smartshield_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Health Checks" ], "x-api-token-group": [ "Health Checks Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "smart-shield.health-checks", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/snippets": { "get": { "operationId": "listZoneSnippets", "summary": "List zone snippets", "description": "Fetches all snippets belonging to the zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/snippets_ZoneId" } }, { "name": "page", "in": "query", "schema": { "$ref": "#/components/schemas/snippets_Page" } }, { "name": "per_page", "in": "query", "schema": { "$ref": "#/components/schemas/snippets_PerPage" } } ], "responses": { "200": { "$ref": "#/components/responses/snippets_Snippets" }, "4XX": { "$ref": "#/components/responses/snippets_Failure" }, "5XX": { "$ref": "#/components/responses/snippets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Snippets" ], "x-api-token-group": [ "Snippets Write", "Snippets Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "snippets", "x-fern-sdk-method-name": "list" } }, "/zones/{zone_id}/snippets/snippet_rules": { "delete": { "operationId": "deleteZoneSnippetRules", "summary": "Delete zone snippet rules", "description": "Deletes all snippet rules belonging to the zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/snippets_ZoneId" } } ], "responses": { "200": { "$ref": "#/components/responses/snippets_SnippetRules" }, "4XX": { "$ref": "#/components/responses/snippets_Failure" }, "5XX": { "$ref": "#/components/responses/snippets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Snippets" ], "x-api-token-group": [ "Snippets Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "snippets.rules", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "listZoneSnippetRules", "summary": "List zone snippet rules", "description": "Fetches all snippet rules belonging to the zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/snippets_ZoneId" } } ], "responses": { "200": { "$ref": "#/components/responses/snippets_SnippetRules" }, "4XX": { "$ref": "#/components/responses/snippets_Failure" }, "5XX": { "$ref": "#/components/responses/snippets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Snippets" ], "x-api-token-group": [ "Snippets Write", "Snippets Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "snippets.rules", "x-fern-sdk-method-name": "list" }, "put": { "operationId": "updateZoneSnippetRules", "summary": "Update zone snippet rules", "description": "Updates all snippet rules belonging to the zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/snippets_ZoneId" } } ], "requestBody": { "$ref": "#/components/requestBodies/snippets_SnippetRules" }, "responses": { "200": { "$ref": "#/components/responses/snippets_SnippetRules" }, "4XX": { "$ref": "#/components/responses/snippets_Failure" }, "5XX": { "$ref": "#/components/responses/snippets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Snippets" ], "x-api-token-group": [ "Snippets Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "snippets.rules", "x-fern-sdk-method-name": "update" } }, "/zones/{zone_id}/snippets/{snippet_name}": { "delete": { "operationId": "deleteZoneSnippet", "summary": "Delete a zone snippet", "description": "Deletes a snippet belonging to the zone. Returns a 4XX response if the zone or snippet no longer exists.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/snippets_ZoneId" } }, { "name": "snippet_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/snippets_SnippetName" } } ], "responses": { "200": { "$ref": "#/components/responses/snippets_Null" }, "4XX": { "$ref": "#/components/responses/snippets_Failure" }, "5XX": { "$ref": "#/components/responses/snippets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Snippets" ], "x-api-token-group": [ "Snippets Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "snippets", "x-fern-sdk-method-name": "delete" }, "get": { "operationId": "getZoneSnippet", "summary": "Get a zone snippet", "description": "Fetches a snippet belonging to the zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/snippets_ZoneId" } }, { "name": "snippet_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/snippets_SnippetName" } } ], "responses": { "200": { "$ref": "#/components/responses/snippets_Snippet" }, "4XX": { "$ref": "#/components/responses/snippets_Failure" }, "5XX": { "$ref": "#/components/responses/snippets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Snippets" ], "x-api-token-group": [ "Snippets Write", "Snippets Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "snippets", "x-fern-sdk-method-name": "get" }, "put": { "operationId": "updateZoneSnippet", "summary": "Update a zone snippet", "description": "Creates or updates a snippet belonging to the zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/snippets_ZoneId" } }, { "name": "snippet_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/snippets_SnippetName" } } ], "requestBody": { "$ref": "#/components/requestBodies/snippets_Snippet" }, "responses": { "200": { "$ref": "#/components/responses/snippets_Snippet" }, "4XX": { "$ref": "#/components/responses/snippets_Failure" }, "5XX": { "$ref": "#/components/responses/snippets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Snippets" ], "x-api-token-group": [ "Snippets Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "snippets", "x-fern-sdk-method-name": "update" } }, "/zones/{zone_id}/snippets/{snippet_name}/content": { "get": { "operationId": "getZoneSnippetContent", "summary": "Get a zone snippet content", "description": "Fetches the content of a snippet belonging to the zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/snippets_ZoneId" } }, { "name": "snippet_name", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/snippets_SnippetName" } } ], "responses": { "200": { "$ref": "#/components/responses/snippets_SnippetContent" }, "4XX": { "$ref": "#/components/responses/snippets_Failure" }, "5XX": { "$ref": "#/components/responses/snippets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Zone Snippets" ], "x-api-token-group": [ "Snippets Write", "Snippets Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "snippets.content", "x-fern-sdk-method-name": "get" }, "x-forge-commands": { "snippets": { "description": "Lightweight JavaScript snippets that run on requests before Workers — for quick header modifications and redirects", "groups": { "content": { "description": "Raw JavaScript source code content of individual snippets" }, "rules": { "description": "Rules that determine which requests trigger specific snippets based on URL patterns" } } } } }, "/zones/{zone_id}/spectrum/analytics/aggregate/current": { "get": { "operationId": "spectrum-aggregate-analytics-get-current-aggregated-analytics", "summary": "Get current aggregated analytics", "description": "Retrieves analytics aggregated from the last minute of usage on Spectrum applications underneath a given zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/spectrum-analytics_identifier" } }, { "name": "appID", "in": "query", "schema": { "$ref": "#/components/schemas/spectrum-analytics_app_id_param" } }, { "name": "colo_name", "in": "query", "schema": { "description": "Co-location identifier.", "type": "string", "example": "PDX", "maxLength": 3 } } ], "responses": { "200": { "description": "Get current aggregated analytics response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-analytics_query-response-aggregate" } } } }, "4xx": { "description": "Get current aggregated analytics response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-analytics_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Spectrum Analytics" ], "x-api-token-group": [ "Analytics Read" ] } }, "/zones/{zone_id}/spectrum/analytics/events/bytime": { "get": { "operationId": "spectrum-analytics-(-by-time)-get-analytics-by-time", "summary": "Get analytics by time", "description": "Retrieves a list of aggregate metrics grouped by time interval.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/spectrum-analytics_identifier" } }, { "name": "dimensions", "in": "query", "schema": { "$ref": "#/components/schemas/spectrum-analytics_dimensions" } }, { "name": "sort", "in": "query", "schema": { "$ref": "#/components/schemas/spectrum-analytics_sort" } }, { "name": "until", "in": "query", "schema": { "$ref": "#/components/schemas/spectrum-analytics_until" } }, { "name": "metrics", "in": "query", "schema": { "$ref": "#/components/schemas/spectrum-analytics_metrics" } }, { "name": "filters", "in": "query", "schema": { "$ref": "#/components/schemas/spectrum-analytics_filters" } }, { "name": "since", "in": "query", "schema": { "$ref": "#/components/schemas/spectrum-analytics_since" } }, { "name": "time_delta", "in": "query", "required": true, "schema": { "description": "Used to select time series resolution.", "type": "string", "example": "minute", "enum": [ "year", "quarter", "month", "week", "day", "hour", "dekaminute", "minute" ] } } ], "responses": { "200": { "description": "Get analytics by time response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-analytics_query-response-single" } } } }, "4xx": { "description": "Get analytics by time response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-analytics_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Spectrum Analytics" ], "x-api-token-group": [ "Analytics Read" ] } }, "/zones/{zone_id}/spectrum/analytics/events/summary": { "get": { "operationId": "spectrum-analytics-(-summary)-get-analytics-summary", "summary": "Get analytics summary", "description": "Retrieves a list of summarised aggregate metrics over a given time period.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/spectrum-analytics_identifier" } }, { "name": "dimensions", "in": "query", "schema": { "$ref": "#/components/schemas/spectrum-analytics_dimensions" } }, { "name": "sort", "in": "query", "schema": { "$ref": "#/components/schemas/spectrum-analytics_sort" } }, { "name": "until", "in": "query", "schema": { "$ref": "#/components/schemas/spectrum-analytics_until" } }, { "name": "metrics", "in": "query", "schema": { "$ref": "#/components/schemas/spectrum-analytics_metrics" } }, { "name": "filters", "in": "query", "schema": { "$ref": "#/components/schemas/spectrum-analytics_filters" } }, { "name": "since", "in": "query", "schema": { "$ref": "#/components/schemas/spectrum-analytics_since" } } ], "responses": { "200": { "description": "Get analytics summary response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-analytics_query-response-single" } } } }, "4xx": { "description": "Get analytics summary response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-analytics_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Spectrum Analytics" ], "x-api-token-group": [ "Analytics Read" ] } }, "/zones/{zone_id}/spectrum/apps": { "get": { "operationId": "spectrum-applications-list-spectrum-applications", "summary": "List Spectrum applications", "description": "Retrieves a list of currently existing Spectrum applications inside a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/spectrum-config_zone_identifier" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results. This parameter is required in order to use other pagination parameters. If included in the query, `result_info` will be present in the response.", "type": "number", "example": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Sets the maximum number of results per page.", "type": "number", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "direction", "in": "query", "schema": { "description": "Sets the direction by which results are ordered.", "type": "string", "example": "desc", "default": "asc", "enum": [ "asc", "desc" ] } }, { "name": "order", "in": "query", "schema": { "description": "Application field by which results are ordered.", "type": "string", "example": "protocol", "default": "dns", "enum": [ "protocol", "app_id", "created_on", "modified_on", "dns" ] } } ], "responses": { "200": { "description": "List Spectrum applications response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-config_app_config_collection" } } } }, "4XX": { "description": "List Spectrum applications response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-config_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Spectrum Applications" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "spectrum.apps", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "spectrum-applications-create-spectrum-application-using-a-name-for-the-origin", "summary": "Create Spectrum application using a name for the origin", "description": "Creates a new Spectrum application from a configuration using a name for the origin.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/spectrum-config_zone_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-config_update_app_config" } } } }, "responses": { "200": { "description": "Create Spectrum application using a name for the origin response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-config_app_config_single" } } } }, "4XX": { "description": "Create Spectrum application using a name for the origin response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-config_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Spectrum Applications" ], "x-api-token-group": [ "Zone Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "spectrum.apps", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/spectrum/apps/{app_id}": { "delete": { "operationId": "spectrum-applications-delete-spectrum-application", "summary": "Delete Spectrum application", "description": "Deletes a previously existing application.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/spectrum-config_app_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/spectrum-config_zone_identifier" } } ], "responses": { "200": { "description": "Delete Spectrum application response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-config_api-response-single-id" } } } }, "4XX": { "description": "Delete Spectrum application response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-config_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Spectrum Applications" ], "x-api-token-group": [ "Zone Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "spectrum.apps", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "spectrum-applications-get-spectrum-application-configuration", "summary": "Get Spectrum application configuration", "description": "Gets the application configuration of a specific application inside a zone.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/spectrum-config_app_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/spectrum-config_zone_identifier" } } ], "responses": { "200": { "description": "Get Spectrum application configuration response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-config_app_config_single" } } } }, "4XX": { "description": "Get Spectrum application configuration response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-config_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Spectrum Applications" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "spectrum.apps", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "spectrum-applications-update-spectrum-application-configuration-using-a-name-for-the-origin", "summary": "Update Spectrum application configuration using a name for the origin", "description": "Updates a previously existing application's configuration that uses a name for the origin.", "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/spectrum-config_app_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/spectrum-config_zone_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-config_update_app_config" } } } }, "responses": { "200": { "description": "Update Spectrum application configuration using a name for the origin response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-config_app_config_single" } } } }, "4XX": { "description": "Update Spectrum application configuration using a name for the origin response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-config_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Spectrum Applications" ], "x-api-token-group": [ "Zone Settings Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "spectrum.apps", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/spectrum/protocols": { "get": { "operationId": "spectrum-applications-list-spectrum-application-protocols", "summary": "List Spectrum application protocols", "description": "Retrieves a list of Spectrum application protocols available for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/spectrum-config_zone_identifier" } } ], "responses": { "200": { "description": "List Spectrum application protocols response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-config_protocol_collection" } } } }, "4XX": { "description": "List Spectrum application protocols response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/spectrum-config_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Spectrum Applications" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "spectrum.protocols", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/zones/{zone_id}/speed_api/availabilities": { "get": { "operationId": "speed-get-availabilities", "summary": "Get quota and availability", "description": "Retrieves quota for all plans, as well as the current zone quota.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_identifier" } } ], "responses": { "200": { "description": "Page test availability.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_availabilities-response" } } } }, "4XX": { "description": "Failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Observatory" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "speed.availabilities", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/zones/{zone_id}/speed_api/pages": { "get": { "operationId": "speed-list-pages", "summary": "List tested webpages", "description": "Lists all webpages which have been tested.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_identifier" } } ], "responses": { "200": { "description": "List of pages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_pages-response-collection" } } } }, "4XX": { "description": "Failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Observatory" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "speed.pages", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/zones/{zone_id}/speed_api/pages/{url}/tests": { "delete": { "operationId": "speed-delete-tests", "summary": "Delete all page tests", "description": "Deletes all tests for a specific webpage from a specific region. Deleted tests are still counted as part of the quota.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_identifier" } }, { "name": "url", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_url" } }, { "name": "region", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/observatory_region" }, { "default": "us-central1", "type": "string" } ] } } ], "responses": { "200": { "description": "Number of deleted tests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_count-response" } } } }, "4XX": { "description": "Failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Observatory" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "speed.pages.tests", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "speed-list-test-history", "summary": "List page test history", "description": "Test history (list of tests) for a specific webpage.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_identifier" } }, { "name": "url", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_url" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "region", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/observatory_region" }, { "default": "us-central1", "type": "string" } ] } } ], "responses": { "200": { "description": "List of test history for a page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_page-test-response-collection" } } } }, "4XX": { "description": "Failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Observatory" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "speed.pages.tests", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "speed-create-test", "summary": "Start page test", "description": "Starts a test for a specific webpage, in a specific region.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_identifier" } }, { "name": "url", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_url" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "region": { "allOf": [ { "$ref": "#/components/schemas/observatory_region" }, { "default": "us-central1", "type": "string" } ] } } } } } }, "responses": { "200": { "description": "Page test details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_page-test-response-single" } } } }, "4XX": { "description": "Failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Observatory" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "speed.pages.tests", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/speed_api/pages/{url}/tests/{test_id}": { "get": { "operationId": "speed-get-test", "summary": "Get a page test result", "description": "Retrieves the result of a specific test.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_identifier" } }, { "name": "url", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_url" } }, { "name": "test_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page test result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_page-test-response-single" } } } }, "4XX": { "description": "Failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Observatory" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "speed.pages.tests", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/speed_api/pages/{url}/trend": { "get": { "operationId": "speed-list-page-trend", "summary": "List core web vital metrics trend", "description": "Lists the core web vital metrics trend over time for a specific page.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_identifier" } }, { "name": "url", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_url" } }, { "name": "region", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/observatory_region" } }, { "name": "deviceType", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/observatory_device_type" } }, { "name": "start", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/observatory_timestamp" } }, { "name": "end", "in": "query", "schema": { "$ref": "#/components/schemas/observatory_timestamp" } }, { "name": "tz", "in": "query", "description": "The timezone of the start and end timestamps.", "required": true, "schema": { "type": "string" }, "example": "America/Chicago" }, { "name": "metrics", "in": "query", "description": "A comma-separated list of metrics to include in the results.", "required": true, "schema": { "type": "string", "example": "performanceScore,ttfb,fcp,si,lcp,tti,tbt,cls" } } ], "responses": { "200": { "description": "Page trend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_trend-response" } } } }, "4XX": { "description": "Failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Observatory" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "speed.pages", "x-fern-sdk-method-name": "trend", "x-forge-hidden": true } }, "/zones/{zone_id}/speed_api/schedule/{url}": { "delete": { "operationId": "speed-delete-test-schedule", "summary": "Delete scheduled page test", "description": "Deletes a scheduled test for a page.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_identifier" } }, { "name": "url", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_url" } }, { "name": "region", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/observatory_region" }, { "default": "us-central1", "type": "string" } ] } } ], "responses": { "200": { "description": "Number of deleted tests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_count-response" } } } }, "4XX": { "description": "Failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Observatory" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "speed.schedule", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "speed-get-scheduled-test", "summary": "Get a page test schedule", "description": "Retrieves the test schedule for a page in a specific region.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_identifier" } }, { "name": "url", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_url" } }, { "name": "region", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/observatory_region" }, { "default": "us-central1", "type": "string" } ] } } ], "responses": { "200": { "description": "Page test schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_schedule-response-single" } } } }, "4XX": { "description": "Failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Observatory" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "speed.schedule", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "speed-create-scheduled-test", "summary": "Create scheduled page test", "description": "Creates a scheduled test for a page.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_identifier" } }, { "name": "url", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/observatory_url" } }, { "name": "region", "in": "query", "schema": { "allOf": [ { "$ref": "#/components/schemas/observatory_region" }, { "default": "us-central1", "type": "string" } ] }, "x-stainless-terraform-configurability": "computed_optional" }, { "name": "frequency", "in": "query", "description": "The frequency of the scheduled test. Defaults to WEEKLY for free plans, DAILY for paid plans.", "schema": { "$ref": "#/components/schemas/observatory_schedule_frequency" }, "x-stainless-terraform-configurability": "computed_optional" } ], "responses": { "200": { "description": "Page test schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_create-schedule-response" } } } }, "4XX": { "description": "Failure response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/observatory_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Observatory" ], "x-api-token-group": [ "Zone Settings Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "speed.schedule", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/ssl/analyze": { "post": { "operationId": "analyze-certificate-analyze-certificate", "summary": "Analyze Certificate", "description": "Returns the set of hostnames, the signature algorithm, and the expiration date of the certificate.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle_method": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_bundle_method" }, "certificate": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate" } } } } } }, "responses": { "200": { "description": "Analyze Certificate response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_analyze_response" } } } }, "4XX": { "description": "Analyze Certificate response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_analyze_response" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Analyze Certificate" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write", "Access: Mutual TLS Certificates Read", "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ssl.analyze", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/ssl/certificate_packs": { "get": { "operationId": "certificate-packs-list-certificate-packs", "summary": "List Certificate Packs", "description": "For a given zone, list all active certificate packs.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "page", "in": "query", "schema": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "description": "Number of certificate packs per page.", "type": "number", "default": 20, "maximum": 50, "minimum": 5 } }, { "name": "status", "in": "query", "schema": { "description": "Include Certificate Packs of all statuses, not just active ones.", "type": "string", "example": "all", "enum": [ "all" ] } }, { "name": "deploy", "in": "query", "schema": { "description": "Specify the deployment environment for the certificate packs.", "type": "string", "enum": [ "staging", "production" ] } } ], "responses": { "200": { "description": "List Certificate Packs response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_pack_response_collection" } } } }, "4XX": { "description": "List Certificate Packs response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_pack_response_collection" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Certificate Packs" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ssl.certificate-packs", "x-fern-sdk-method-name": "list", "x-forge-hidden": true } }, "/zones/{zone_id}/ssl/certificate_packs/order": { "post": { "operationId": "certificate-packs-order-advanced-certificate-manager-certificate-pack", "summary": "Order Advanced Certificate Manager Certificate Pack", "description": "For a given zone, order an advanced certificate pack.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "certificate_authority": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_authority-2" }, "cloudflare_branding": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_cloudflare_branding" }, "hosts": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hosts-2" }, "type": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_advanced_type" }, "validation_method": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_validation_method" }, "validity_days": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_validity_days" } }, "required": [ "type", "hosts", "validation_method", "validity_days", "certificate_authority" ] } } } }, "responses": { "200": { "description": "Order Advanced Certificate Manager Certificate Pack response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_advanced_certificate_pack_response_single" } } } }, "4XX": { "description": "Order Advanced Certificate Manager Certificate Pack response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_advanced_certificate_pack_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Certificate Packs" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read", "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ssl.certificate-packs", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/ssl/certificate_packs/quota": { "get": { "operationId": "certificate-packs-get-certificate-pack-quotas", "summary": "Get Certificate Pack Quotas", "description": "For a given zone, list certificate pack quotas.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Get Certificate Pack Quotas response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_pack_quota_response" } } } }, "4XX": { "description": "Get Certificate Pack Quotas response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_pack_quota_response" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Certificate Packs" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ssl.certificate-packs.quota", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/ssl/certificate_packs/{certificate_pack_id}": { "delete": { "operationId": "certificate-packs-delete-advanced-certificate-manager-certificate-pack", "summary": "Delete Advanced Certificate Manager Certificate Pack", "description": "For a given zone, delete an advanced certificate pack.", "parameters": [ { "name": "certificate_pack_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Delete Advanced Certificate Manager Certificate Pack response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_delete_advanced_certificate_pack_response_single" } } } }, "4XX": { "description": "Delete Advanced Certificate Manager Certificate Pack response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_delete_advanced_certificate_pack_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Certificate Packs" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read", "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ssl.certificate-packs", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "certificate-packs-get-certificate-pack", "summary": "Get Certificate Pack", "description": "For a given zone, get a certificate pack.", "parameters": [ { "name": "certificate_pack_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Get Certificate Pack response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_pack_response_single" } } } }, "4XX": { "description": "Get Certificate Pack response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_pack_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Certificate Packs" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ssl.certificate-packs", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "certificate-packs-restart-validation-for-advanced-certificate-manager-certificate-pack", "summary": "Restart Validation or Update Advanced Certificate Manager Certificate Pack", "description": "For a given zone, restart validation or add cloudflare branding for an advanced certificate pack. The former is only a validation operation for a Certificate Pack in a validation_timed_out status.", "parameters": [ { "name": "certificate_pack_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cloudflare_branding": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_cloudflare_branding" } } } } } }, "responses": { "200": { "description": "Restart Validation for Advanced Certificate Manager Certificate Pack response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_advanced_certificate_pack_response_single" } } } }, "4XX": { "description": "Restart Validation for Advanced Certificate Manager Certificate Pack response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_advanced_certificate_pack_response_single" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Certificate Packs" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read", "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ssl.certificate-packs", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/ssl/recommendation": { "get": { "operationId": "ssl/-tls-mode-recommendation-ssl/-tls-recommendation", "summary": "SSL/TLS Recommendation", "description": "Retrieve the SSL/TLS Recommender's recommendation for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/cache_identifier" } } ], "responses": { "200": { "description": "SSL/TLS Recommendation response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache_api-response-single-id" } } } }, "4XX": { "description": "SSL/TLS Recommendation response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cache_api-response-common-failure" } } } } }, "deprecated": true, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "SSL/TLS Mode Recommendation" ], "x-api-token-group": [ "Zone Settings Write", "Zone Settings Read", "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ssl.recommendations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stainless-deprecation-message": "SSL/TLS Recommender has been decommissioned in favor of Automatic SSL/TLS" } }, "/zones/{zone_id}/ssl/universal/settings": { "get": { "operationId": "universal-ssl-settings-for-a-zone-universal-ssl-settings-details", "summary": "Universal SSL Settings Details", "description": "Get Universal SSL Settings for a Zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "responses": { "200": { "description": "Universal SSL Settings Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ssl_universal_settings_response" } } } }, "4XX": { "description": "Universal SSL Settings Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ssl_universal_settings_response" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Universal SSL Settings for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ssl.universal.settings", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "universal-ssl-settings-for-a-zone-edit-universal-ssl-settings", "summary": "Edit Universal SSL Settings", "description": "Patch Universal SSL Settings for a Zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_universal" } } } }, "responses": { "200": { "description": "Edit Universal SSL Settings response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ssl_universal_settings_response" } } } }, "4XX": { "description": "Edit Universal SSL Settings response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ssl_universal_settings_response" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Universal SSL Settings for a Zone" ], "x-api-token-group": [ "SSL and Certificates Write" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read", "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ssl.universal.settings", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/ssl/verification": { "get": { "operationId": "ssl-verification-ssl-verification-details", "summary": "SSL Verification Details", "description": "Get SSL Verification Info for a Zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, { "name": "retry", "in": "query", "schema": { "description": "Immediately retry SSL Verification.", "type": "boolean", "example": true, "enum": [ true ] } } ], "responses": { "200": { "description": "SSL Verification Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ssl_verification_response_collection" } } } }, "4XX": { "description": "SSL Verification Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ssl_verification_response_collection" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "SSL Verification" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write", "Access: Mutual TLS Certificates Read", "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ssl.verification", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/ssl/verification/{certificate_pack_id}": { "patch": { "operationId": "ssl-verification-edit-ssl-certificate-pack-validation-method", "summary": "Edit SSL Certificate Pack Validation Method", "description": "Edit SSL validation method for a certificate pack. A PATCH request will request an immediate validation check on any certificate, and return the updated status. If a validation method is provided, the validation will be immediately attempted using that method.", "parameters": [ { "name": "certificate_pack_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_cert_pack_uuid" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_validation_method-3" } } } }, "responses": { "200": { "description": "Edit SSL Certificate Pack Validation Method response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ssl_validation_method_response_collection" } } } }, "4XX": { "description": "Edit SSL Certificate Pack Validation Method response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ssl_validation_method_response_collection" }, { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "SSL Verification" ], "x-api-token-group": [ "Access: Mutual TLS Certificates Write", "Access: Mutual TLS Certificates Read", "SSL and Certificates Write", "SSL and Certificates Read" ], "x-cfPermissionsRequired": { "enum": [ "#ssl:read", "#ssl:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "ssl.verification", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/stream/usage": { "get": { "operationId": "usage-analytics-get-zone-stream-usage", "summary": "Get zone Stream usage", "description": "Retrieve Stream usage analytics for a zone. Returns time-series data for Stream billable minutes viewed. The gateway resolves the zone to its owning account and rewrites this path before forwarding to the backend usage handler.\n", "parameters": [ { "$ref": "#/components/parameters/usage-analytics_zone_id" }, { "$ref": "#/components/parameters/usage-analytics_metrics" }, { "$ref": "#/components/parameters/usage-analytics_since" }, { "$ref": "#/components/parameters/usage-analytics_until" }, { "$ref": "#/components/parameters/usage-analytics_time_delta" }, { "$ref": "#/components/parameters/usage-analytics_limit" }, { "$ref": "#/components/parameters/usage-analytics_filters" } ], "responses": { "200": { "description": "Usage analytics response.", "content": { "application/json": { "examples": { "success": { "summary": "Successful Stream usage retrieval", "value": { "errors": [], "messages": [], "result": [ { "streamMinutesViewed": 12500, "ts": 1693526400 }, { "streamMinutesViewed": 9800, "ts": 1693530000 } ], "success": true } } }, "schema": { "$ref": "#/components/schemas/usage-analytics_stream_usage_response" } } } }, "400": { "$ref": "#/components/responses/usage-analytics_bad_request" }, "401": { "$ref": "#/components/responses/usage-analytics_unauthorized" }, "403": { "$ref": "#/components/responses/usage-analytics_forbidden" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Usage Analytics" ], "x-api-token-group": [ "Stream Read" ], "x-fern-availability": "deprecated", "x-fern-sdk-group-name": "stream.usage", "x-fern-sdk-method-name": "get" } }, "/zones/{zone_id}/subscription": { "delete": { "operationId": "zone-subscription-delete-zone-subscription", "summary": "Delete Zone Subscription", "description": "Deletes a zone's subscription.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "responses": { "200": { "description": "Delete Zone Subscription response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "subscription_id": { "$ref": "#/components/schemas/bill-subs-api_schemas-identifier" } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Delete Zone Subscription response failure", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "subscription_id": { "$ref": "#/components/schemas/bill-subs-api_schemas-identifier" } } } }, "type": "object" } ] }, { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Subscription" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.subscriptions", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "zone-subscription-zone-subscription-details", "summary": "Zone Subscription Details", "description": "Lists zone subscription details.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "responses": { "200": { "description": "Zone Subscription Details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_zone_subscription_response_single" } } } }, "4XX": { "description": "Zone Subscription Details response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Subscription" ], "x-api-token-group": [ "Billing Write", "Billing Read" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.subscriptions", "x-fern-sdk-method-name": "get" }, "post": { "operationId": "zone-subscription-create-zone-subscription", "summary": "Create Zone Subscription", "description": "Create a zone subscription, either plan or add-ons.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_subscription-v2" } } } }, "responses": { "200": { "description": "Create Zone Subscription response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_zone_subscription_response_single" } } } }, "4XX": { "description": "Create Zone Subscription response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Subscription" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read", "#billing:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.subscriptions", "x-fern-sdk-method-name": "create" }, "put": { "operationId": "zone-subscription-update-zone-subscription", "summary": "Update Zone Subscription", "description": "Updates zone subscriptions, either plan or add-ons.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_subscription-v2" } } } }, "responses": { "200": { "description": "Update Zone Subscription response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_zone_subscription_response_single" } } } }, "4XX": { "description": "Update Zone Subscription response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Subscription" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read", "#billing:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "zones.subscriptions", "x-fern-sdk-method-name": "update" } }, "/zones/{zone_id}/subscriptions": { "delete": { "operationId": "zone-subscription-delete-zone-subscriptions", "summary": "Delete Zone Subscription", "description": "Deletes a zone's subscription. Retained for audit-log coverage. Use the singular `/zones/{zone_id}/subscription` path instead.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "responses": { "200": { "description": "Delete Zone Subscription response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "subscription_id": { "$ref": "#/components/schemas/bill-subs-api_schemas-identifier" } } } }, "type": "object" } ] } } } }, "4XX": { "description": "Delete Zone Subscription response failure", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "subscription_id": { "$ref": "#/components/schemas/bill-subs-api_schemas-identifier" } } } }, "type": "object" } ] }, { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Subscription" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "zones.subscriptions", "x-fern-sdk-method-name": "deleteBulk", "x-forge-hidden": true }, "post": { "operationId": "zone-subscription-create-zone-subscriptions", "summary": "Create Zone Subscription", "description": "Create a zone subscription, either plan or add-ons. Retained for audit-log coverage. Use the singular `/zones/{zone_id}/subscription` path instead.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_subscription-v2" } } } }, "responses": { "200": { "description": "Create Zone Subscription response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_zone_subscription_response_single" } } } }, "4XX": { "description": "Create Zone Subscription response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_zone_subscription_response_single" }, { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Subscription" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read", "#billing:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "zones.subscriptions", "x-fern-sdk-method-name": "createBulk", "x-forge-hidden": true }, "put": { "operationId": "zone-subscription-update-zone-subscriptions", "summary": "Update Zone Subscription", "description": "Updates zone subscriptions, either plan or add-ons. Retained for audit-log coverage. Use the singular `/zones/{zone_id}/subscription` path instead.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/bill-subs-api_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_subscription-v2" } } } }, "responses": { "200": { "description": "Update Zone Subscription response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bill-subs-api_zone_subscription_response_single" } } } }, "4XX": { "description": "Update Zone Subscription response failure", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_zone_subscription_response_single" }, { "$ref": "#/components/schemas/bill-subs-api_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Zone Subscription" ], "x-api-token-group": [ "Billing Write" ], "x-cfPermissionsRequired": { "enum": [ "#billing:read", "#billing:edit" ] }, "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-ignore": true, "x-fern-sdk-group-name": "zones.subscriptions", "x-fern-sdk-method-name": "updateBulk", "x-forge-hidden": true } }, "/zones/{zone_id}/tags": { "delete": { "operationId": "tags-zone-delete", "summary": "Delete tags from a zone-level resource", "description": "Removes all tags from a specific zone-level resource.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/resource-tagging_zone_id" } }, { "$ref": "#/components/parameters/resource-tagging_if_match" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_delete_tags_request_zone_level" } } } }, "responses": { "204": { "description": "Tags successfully deleted (no content)." }, "412": { "description": "Precondition failed. The resource has been modified since the provided ETag was obtained.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } }, "4XX": { "description": "Delete tags response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } }, "5XX": { "description": "Delete tags response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Resource Tagging" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "zone-tags", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-stability": "beta" }, "get": { "operationId": "tags-zone-get", "summary": "Get tags for a zone-level resource", "description": "Retrieves tags for a specific zone-level resource.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/resource-tagging_zone_id" } }, { "name": "resource_id", "in": "query", "description": "The ID of the resource to retrieve tags for.", "required": true, "schema": { "$ref": "#/components/schemas/resource-tagging_resource_id" } }, { "name": "resource_type", "in": "query", "description": "The type of the resource.", "required": true, "schema": { "$ref": "#/components/schemas/resource-tagging_zone_resource_type" } }, { "name": "access_application_id", "in": "query", "description": "Access application ID identifier. Required for access_application_policy resources.", "schema": { "$ref": "#/components/schemas/resource-tagging_access_application_id" } } ], "responses": { "200": { "description": "Get tags for single resource response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_tagged_resource_response_single" } } } }, "4XX": { "description": "Get tags for single resource response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } }, "5XX": { "description": "Get tags for single resource response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Resource Tagging" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "zone-tags", "x-fern-sdk-method-name": "get", "x-forge-hidden": true, "x-stability": "beta" }, "put": { "operationId": "tags-zone-set", "summary": "Set tags for a zone-level resource", "description": "Creates or updates tags for a specific zone-level resource. Replaces all existing tags for the resource.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/resource-tagging_zone_id" } }, { "$ref": "#/components/parameters/resource-tagging_if_match" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_set_tags_request_zone_level" } } } }, "responses": { "200": { "description": "Set tags response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_tagged_resource_response_single" } } } }, "412": { "description": "Precondition failed. The resource has been modified since the provided ETag was obtained.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } }, "4XX": { "description": "Set tags response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } }, "5XX": { "description": "Set tags response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resource-tagging_api-response-common-failure" } } } } }, "security": [ { "api_email": [], "api_key": [] } ], "tags": [ "Resource Tagging" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "beta", "x-fern-sdk-group-name": "zone-tags", "x-fern-sdk-method-name": "update", "x-forge-hidden": true, "x-stability": "beta" } }, "/zones/{zone_id}/token_validation/config": { "get": { "operationId": "token-validation-config-list", "summary": "List token validation configurations", "description": "Lists the JWT validation configurations defined for the zone.", "parameters": [ { "$ref": "#/components/parameters/api-shield_page" }, { "$ref": "#/components/parameters/api-shield_per_page" } ], "responses": { "200": { "$ref": "#/components/responses/api-shield_list-configs-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "externalDocs": { "description": "Learn more about JSON Web Tokens Validation.", "url": "https://developers.cloudflare.com/api-shield/security/jwt-validation/" }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Token Validation Token Configuration" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.token-validation.configurations", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ], "post": { "operationId": "token-validation-config-create", "summary": "Create a token validation configuration", "description": "Creates a JWT validation configuration for the zone.", "requestBody": { "$ref": "#/components/requestBodies/api-shield_create-config" }, "responses": { "200": { "$ref": "#/components/responses/api-shield_create-config-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "externalDocs": { "description": "Learn more about JSON Web Tokens Validation.", "url": "https://developers.cloudflare.com/api-shield/security/jwt-validation/" }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Token Validation Token Configuration" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.token-validation.configurations", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/token_validation/config/{config_id}": { "delete": { "operationId": "token-validation-config-delete", "summary": "Delete a token validation configuration", "description": "Deletes a JWT validation configuration from the zone.", "responses": { "200": { "$ref": "#/components/responses/api-shield_delete-config-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "externalDocs": { "description": "Learn more about JSON Web Tokens Validation.", "url": "https://developers.cloudflare.com/api-shield/security/jwt-validation/" }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Token Validation Token Configuration" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.token-validation.configurations", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes the token validation configuration. The request is rejected if rules, operations, or JWT authentication identifiers still reference it." }, "get": { "operationId": "token-validation-config-get", "summary": "Get a token validation configuration", "description": "Returns a JWT validation configuration by ID.", "responses": { "200": { "$ref": "#/components/responses/api-shield_get-config-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "externalDocs": { "description": "Learn more about JSON Web Tokens Validation.", "url": "https://developers.cloudflare.com/api-shield/security/jwt-validation/" }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Token Validation Token Configuration" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.token-validation.configurations", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "$ref": "#/components/parameters/api-shield_config_id" } ], "patch": { "operationId": "token-validation-config-edit", "summary": "Edit a token validation configuration", "description": "Updates only the supplied fields on a JWT validation configuration.", "requestBody": { "$ref": "#/components/requestBodies/api-shield_edit-config" }, "responses": { "200": { "$ref": "#/components/responses/api-shield_edit-config-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "externalDocs": { "description": "Learn more about JSON Web Tokens Validation.", "url": "https://developers.cloudflare.com/api-shield/security/jwt-validation/" }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Token Validation Token Configuration" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.token-validation.configurations", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/token_validation/config/{config_id}/credentials": { "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "$ref": "#/components/parameters/api-shield_config_id" } ], "patch": { "operationId": "token-validation-config-credentials-edit", "summary": "Edit token validation credentials", "description": "Updates the configuration's complete key set while allowing omitted fields on existing keys to retain stored values. Omitted key identities are removed.", "requestBody": { "$ref": "#/components/requestBodies/api-shield_edit-config-credentials" }, "responses": { "200": { "$ref": "#/components/responses/api-shield_update-config-credentials-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "externalDocs": { "description": "Learn more about JSON Web Tokens Validation.", "url": "https://developers.cloudflare.com/api-shield/security/jwt-validation/" }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Token Validation Token Configuration" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.token-validation.configurations.credentials", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "token-validation-config-credentials-update", "summary": "Replace token validation credentials", "description": "Replaces the configuration's complete key set. Symmetric keys must include their key material.", "requestBody": { "$ref": "#/components/requestBodies/api-shield_update-config-credentials" }, "responses": { "200": { "$ref": "#/components/responses/api-shield_update-config-credentials-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "externalDocs": { "description": "Learn more about JSON Web Tokens Validation.", "url": "https://developers.cloudflare.com/api-shield/security/jwt-validation/" }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Token Validation Token Configuration" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.token-validation.configurations.credentials", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/token_validation/rules": { "get": { "operationId": "token-validation-rules-list", "summary": "List token validation rules", "description": "Lists token validation rules for the zone, with filters for configuration, action, state, ID, and host.", "parameters": [ { "$ref": "#/components/parameters/api-shield_per_page" }, { "$ref": "#/components/parameters/api-shield_page" }, { "name": "token_configuration", "in": "query", "description": "Select rules using any of these token configurations.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_uuid-2" } }, "examples": { "multipleIDs": { "value": [ "f0963ed4-f3a1-4599-8a61-9e5658c865e0,3aad66bb-059d-4b3d-87e1-cdf4d406f412" ] }, "multipleIDsExploded": { "value": [ "f0963ed4-f3a1-4599-8a61-9e5658c865e0", "3aad66bb-059d-4b3d-87e1-cdf4d406f412" ] } } }, { "name": "action", "in": "query", "schema": { "$ref": "#/components/schemas/api-shield_action" } }, { "name": "enabled", "in": "query", "schema": { "$ref": "#/components/schemas/api-shield_enabled" } }, { "name": "id", "in": "query", "description": "Select rules with these IDs.", "schema": { "$ref": "#/components/schemas/api-shield_uuid-2" } }, { "name": "rule_id", "in": "query", "description": "Select rules with these IDs.", "schema": { "$ref": "#/components/schemas/api-shield_uuid-2" } }, { "name": "host", "in": "query", "description": "Select rules with this host in `include`.", "schema": { "$ref": "#/components/schemas/api-shield_host" } }, { "name": "hostname", "in": "query", "description": "Select rules with this host in `include`.", "schema": { "$ref": "#/components/schemas/api-shield_host" } } ], "responses": { "200": { "$ref": "#/components/responses/api-shield_list-rules-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "externalDocs": { "description": "Learn more about JSON Web Tokens Validation.", "url": "https://developers.cloudflare.com/api-shield/security/jwt-validation/" }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Token Validation Token Rules" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.token-validation.rules", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ], "post": { "operationId": "token-validation-rules-create", "summary": "Create a token validation rule", "description": "Creates a token validation rule for the zone.", "requestBody": { "$ref": "#/components/requestBodies/api-shield_create-rule" }, "responses": { "200": { "$ref": "#/components/responses/api-shield_create-rule-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "externalDocs": { "description": "Learn more about JSON Web Tokens Validation.", "url": "https://developers.cloudflare.com/api-shield/security/jwt-validation/" }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Token Validation Token Rules" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.token-validation.rules", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/token_validation/rules/bulk": { "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ], "patch": { "operationId": "token-validation-rules-bulk-edit", "summary": "Edit token validation rules", "description": "Updates and reorders multiple token validation rules in one request, then returns the updated rules.", "requestBody": { "$ref": "#/components/requestBodies/api-shield_bulk-edit-rules" }, "responses": { "200": { "$ref": "#/components/responses/api-shield_bulk-edit-rules-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "externalDocs": { "description": "Learn more about JSON Web Tokens Validation.", "url": "https://developers.cloudflare.com/api-shield/security/jwt-validation/" }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Token Validation Token Rules" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.token-validation.rules", "x-fern-sdk-method-name": "bulk-edit", "x-forge-hidden": true }, "post": { "operationId": "token-validation-rules-bulk-create", "summary": "Create token validation rules", "description": "Creates multiple token validation rules for the zone in one request.", "requestBody": { "$ref": "#/components/requestBodies/api-shield_bulk-create-rules" }, "responses": { "200": { "$ref": "#/components/responses/api-shield_bulk-create-rules-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "externalDocs": { "description": "Learn more about JSON Web Tokens Validation.", "url": "https://developers.cloudflare.com/api-shield/security/jwt-validation/" }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Token Validation Token Rules" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.token-validation.rules", "x-fern-sdk-method-name": "bulk-create", "x-forge-hidden": true } }, "/zones/{zone_id}/token_validation/rules/preview": { "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" } ], "post": { "operationId": "token-validation-rules-preview", "summary": "Preview a token validation rule", "description": "Returns zone operations annotated as included or excluded to preview the rule's coverage before creation.", "parameters": [ { "$ref": "#/components/parameters/api-shield_per_page" }, { "$ref": "#/components/parameters/api-shield_page" }, { "name": "state", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_selector-operation-state" } }, "examples": { "multiple": { "value": [ "included,excluded" ] }, "multipleExploded": { "value": [ "included", "excluded" ] } } }, { "name": "host", "in": "query", "description": "Filter operations by host.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_host" } } }, { "name": "hostname", "in": "query", "description": "Filter operations by host.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_host" } } }, { "name": "method", "in": "query", "description": "Filter operations by method.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_method" } } }, { "name": "endpoint", "in": "query", "description": "Filter operations by endpoint. Allows substring matching.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_endpoint" } } } ], "requestBody": { "$ref": "#/components/requestBodies/api-shield_preview-rules" }, "responses": { "200": { "$ref": "#/components/responses/api-shield_preview-rules-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "externalDocs": { "description": "Learn more about JSON Web Tokens Validation.", "url": "https://developers.cloudflare.com/api-shield/security/jwt-validation/" }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Token Validation Token Rules" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-ignore": true, "x-fern-sdk-group-name": "api-security.token-validation.rules", "x-fern-sdk-method-name": "preview", "x-forge-hidden": true } }, "/zones/{zone_id}/token_validation/rules/{rule_id}": { "delete": { "operationId": "token-validation-rules-delete", "summary": "Delete a token validation rule", "description": "Deletes a token validation rule from the zone.", "responses": { "200": { "$ref": "#/components/responses/api-shield_delete-rule-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "externalDocs": { "description": "Learn more about JSON Web Tokens Validation.", "url": "https://developers.cloudflare.com/api-shield/security/jwt-validation/" }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Token Validation Token Rules" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.token-validation.rules", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true, "x-forge-require-confirmation": "This operation deletes the token validation rule from the zone." }, "get": { "operationId": "token-validation-rules-get", "summary": "Get a token validation rule", "description": "Returns a token validation rule by ID.", "responses": { "200": { "$ref": "#/components/responses/api-shield_get-rule-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "externalDocs": { "description": "Learn more about JSON Web Tokens Validation.", "url": "https://developers.cloudflare.com/api-shield/security/jwt-validation/" }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Token Validation Token Rules" ], "x-api-token-group": [ "Account API Gateway", "Account API Gateway Read", "Domain API Gateway", "Domain API Gateway Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.token-validation.rules", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "parameters": [ { "$ref": "#/components/parameters/api-shield_zone_id" }, { "$ref": "#/components/parameters/api-shield_rule_id" } ], "patch": { "operationId": "token-validation-rules-edit", "summary": "Edit a token validation rule", "description": "Updates only the supplied fields on a token validation rule.", "requestBody": { "$ref": "#/components/requestBodies/api-shield_edit-rule" }, "responses": { "200": { "$ref": "#/components/responses/api-shield_edit-rule-success" }, "4XX": { "$ref": "#/components/responses/api-shield_generic_failure" } }, "externalDocs": { "description": "Learn more about JSON Web Tokens Validation.", "url": "https://developers.cloudflare.com/api-shield/security/jwt-validation/" }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Token Validation Token Rules" ], "x-api-token-group": [ "Account API Gateway", "Domain API Gateway" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "api-security.token-validation.rules", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/url_normalization": { "delete": { "operationId": "deleteUrlNormalization", "summary": "Delete URL Normalization settings", "description": "Deletes the URL Normalization settings.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } } ], "responses": { "204": { "$ref": "#/components/responses/rulesets_Empty" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Normalization" ], "x-api-token-group": [ "Response Compression Write", "Config Settings Write", "Dynamic URL Redirects Write", "Cache Settings Write", "Custom Errors Write", "Origin Write", "Managed headers Write", "Zone Transform Rules Write", "Mass URL Redirects Write", "Magic Firewall Write", "L4 DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Write", "Sanitize Write", "Transform Rules Write", "Select Configuration Write", "Bot Management Write", "Zone WAF Write", "Account WAF Write", "Account Rulesets Write", "Logs Write", "Logs Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "url-normalization", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "getUrlNormalization", "summary": "Get URL Normalization settings", "description": "Fetches the current URL Normalization settings.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } } ], "responses": { "200": { "$ref": "#/components/responses/rulesets_UrlNormalization" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Normalization" ], "x-api-token-group": [ "Response Compression Write", "Response Compression Read", "Config Settings Write", "Config Settings Read", "Dynamic URL Redirects Write", "Dynamic URL Redirects Read", "Cache Settings Write", "Cache Settings Read", "Custom Errors Write", "Custom Errors Read", "Origin Write", "Origin Read", "Managed headers Write", "Managed headers Read", "Zone Transform Rules Write", "Zone Transform Rules Read", "Mass URL Redirects Write", "Mass URL Redirects Read", "Magic Firewall Write", "Magic Firewall Read", "L4 DDoS Managed Ruleset Write", "L4 DDoS Managed Ruleset Read", "HTTP DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Read", "Sanitize Write", "Sanitize Read", "Transform Rules Write", "Transform Rules Read", "Select Configuration Write", "Select Configuration Read", "Bot Management Write", "Bot Management Read", "Zone WAF Write", "Zone WAF Read", "Account WAF Write", "Account WAF Read", "Account Rulesets Read", "Account Rulesets Write", "Logs Write", "Logs Read", "Logs Write", "Logs Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "url-normalization", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "updateUrlNormalization", "summary": "Update URL Normalization settings", "description": "Updates the URL Normalization settings.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/rulesets_ZoneId" } } ], "requestBody": { "$ref": "#/components/requestBodies/rulesets_UrlNormalization" }, "responses": { "200": { "$ref": "#/components/responses/rulesets_UrlNormalization" }, "4XX": { "$ref": "#/components/responses/rulesets_Failure" } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "URL Normalization" ], "x-api-token-group": [ "Response Compression Write", "Config Settings Write", "Dynamic URL Redirects Write", "Cache Settings Write", "Custom Errors Write", "Origin Write", "Managed headers Write", "Zone Transform Rules Write", "Mass URL Redirects Write", "Magic Firewall Write", "L4 DDoS Managed Ruleset Write", "HTTP DDoS Managed Ruleset Write", "Sanitize Write", "Transform Rules Write", "Select Configuration Write", "Bot Management Write", "Zone WAF Write", "Account WAF Write", "Account Rulesets Write", "Logs Write", "Logs Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "url-normalization", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/waiting_rooms": { "get": { "operationId": "waiting-room-list-waiting-rooms", "summary": "List waiting rooms for zone", "description": "Lists waiting rooms for zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } }, { "$ref": "#/components/parameters/waitingroom_page" }, { "$ref": "#/components/parameters/waitingroom_per_page" } ], "responses": { "200": { "description": "List waiting rooms for zone response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_response_collection" } } } }, "4XX": { "description": "List waiting rooms for zone response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_response_collection" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Read", "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "waiting-room-create-waiting-room", "summary": "Create waiting room", "description": "Creates a new waiting room.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_query_waitingroom" } } } }, "responses": { "200": { "description": "Create waiting room response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_single_response" } } } }, "4XX": { "description": "Create waiting room response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_single_response" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/waiting_rooms/preview": { "post": { "operationId": "waiting-room-create-a-custom-waiting-room-page-preview", "summary": "Create a custom waiting room page preview", "description": "Creates a waiting room page preview. Upload a custom waiting room page for preview. You will receive a preview URL in the form `http://waitingrooms.dev/preview/`. You can use the following query parameters to change the state of the preview:\n1. `force_queue`: Boolean indicating if all users will be queued in the waiting room and no one will be let into the origin website (also known as queueAll).\n2. `queue_is_full`: Boolean indicating if the waiting room's queue is currently full and not accepting new users at the moment.\n3. `queueing_method`: The queueing method currently used by the waiting room.\n\t- **fifo** indicates a FIFO queue.\n\t- **random** indicates a Random queue.\n\t- **passthrough** indicates a Passthrough queue. Keep in mind that the waiting room page will only be displayed if `force_queue=true` or `event=prequeueing` — for other cases the request will pass through to the origin. For our preview, this will be a fake origin website returning \\\"Welcome\\\". \n\t- **reject** indicates a Reject queue.\n4. `event`: Used to preview a waiting room event.\n\t- **none** indicates no event is occurring.\n\t- **prequeueing** indicates that an event is prequeueing (between `prequeue_start_time` and `event_start_time`).\n\t- **started** indicates that an event has started (between `event_start_time` and `event_end_time`).\n5. `shuffle_at_event_start`: Boolean indicating if the event will shuffle users in the prequeue when it starts. This can only be set to **true** if an event is active (`event` is not **none**).\n\nFor example, you can make a request to `http://waitingrooms.dev/preview/?force_queue=false&queue_is_full=false&queueing_method=random&event=started&shuffle_at_event_start=true`\n6. `waitTime`: Non-zero, positive integer indicating the estimated wait time in minutes. The default value is 10 minutes.\n\nFor example, you can make a request to `http://waitingrooms.dev/preview/?waitTime=50` to configure the estimated wait time as 50 minutes.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_query_preview" } } } }, "responses": { "200": { "description": "Create a custom waiting room page preview response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_preview_response" } } } }, "4XX": { "description": "Create a custom waiting room page preview response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_preview_response" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.page", "x-fern-sdk-method-name": "preview", "x-forge-hidden": true } }, "/zones/{zone_id}/waiting_rooms/settings": { "get": { "operationId": "waiting-room-get-zone-settings", "summary": "Get zone-level Waiting Room settings", "description": "Get zone-level Waiting Room settings.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "responses": { "200": { "description": "The current zone-level Waiting Room settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_zone_settings_response" } } } }, "4XX": { "description": "The current zone-level Waiting Room settings response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_zone_settings_response" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Read", "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.settings", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "waiting-room-patch-zone-settings", "summary": "Patch zone-level Waiting Room settings", "description": "Patch zone-level Waiting Room settings.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_zone_settings" } } } }, "responses": { "200": { "description": "The updated zone-level Waiting Room settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_zone_settings_response" } } } }, "4XX": { "description": "The zone-level Waiting Room settings response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_zone_settings_response" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.settings", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "waiting-room-update-zone-settings", "summary": "Update zone-level Waiting Room settings", "description": "Replace zone-level Waiting Room settings.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_zone_settings" } } } }, "responses": { "200": { "description": "The updated zone-level Waiting Room settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_zone_settings_response" } } } }, "4XX": { "description": "The zone-level Waiting Room settings response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_zone_settings_response" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.settings", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/waiting_rooms/{waiting_room_id}": { "delete": { "operationId": "waiting-room-delete-waiting-room", "summary": "Delete waiting room", "description": "Deletes a waiting room.", "parameters": [ { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": {} } }, "responses": { "200": { "description": "Delete waiting room response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id_response" } } } }, "4XX": { "description": "Delete waiting room response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_waiting_room_id_response" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "waiting-room-waiting-room-details", "summary": "Waiting room details", "description": "Fetches a single configured waiting room.", "parameters": [ { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "responses": { "200": { "description": "Waiting room details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_single_response" } } } }, "4XX": { "description": "Waiting room details response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_single_response" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Read", "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "waiting-room-patch-waiting-room", "summary": "Patch waiting room", "description": "Patches a configured waiting room.", "parameters": [ { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_query_waitingroom" } } } }, "responses": { "200": { "description": "Patch waiting room response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_single_response" } } } }, "4XX": { "description": "Patch waiting room response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_single_response" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "waiting-room-update-waiting-room", "summary": "Update waiting room", "description": "Updates a configured waiting room.", "parameters": [ { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_query_waitingroom" } } } }, "responses": { "200": { "description": "Update waiting room response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_single_response" } } } }, "4XX": { "description": "Update waiting room response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_single_response" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/waiting_rooms/{waiting_room_id}/events": { "get": { "operationId": "waiting-room-list-events", "summary": "List events", "description": "Lists events for a waiting room.", "parameters": [ { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } }, { "$ref": "#/components/parameters/waitingroom_page" }, { "$ref": "#/components/parameters/waitingroom_per_page" } ], "responses": { "200": { "description": "List events response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_event_response_collection" } } } }, "4XX": { "description": "List events response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_event_response_collection" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Read", "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.events", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "waiting-room-create-event", "summary": "Create event", "description": "Only available for the Waiting Room Advanced subscription. Creates an event for a waiting room. An event takes place during a specified period of time, temporarily changing the behavior of a waiting room. While the event is active, some of the properties in the event's configuration may either override or inherit from the waiting room's configuration. Note that events cannot overlap with each other, so only one event can be active at a time.", "parameters": [ { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_query_event" } } } }, "responses": { "200": { "description": "Create event response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_event_response" } } } }, "4XX": { "description": "Create event response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_event_response" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.events", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/waiting_rooms/{waiting_room_id}/events/{event_id}": { "delete": { "operationId": "waiting-room-delete-event", "summary": "Delete event", "description": "Deletes an event for a waiting room.", "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_event_id" } }, { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": {} } }, "responses": { "200": { "description": "Delete event response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_event_id_response" } } } }, "4XX": { "description": "Delete event response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_event_id_response" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.events", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "waiting-room-event-details", "summary": "Event details", "description": "Fetches a single configured event for a waiting room.", "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_event_id" } }, { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "responses": { "200": { "description": "Event details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_event_response" } } } }, "4XX": { "description": "Event details response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_event_response" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Read", "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.events", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "waiting-room-patch-event", "summary": "Patch event", "description": "Patches a configured event for a waiting room.", "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_event_id" } }, { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_query_event" } } } }, "responses": { "200": { "description": "Patch event response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_event_response" } } } }, "4XX": { "description": "Patch event response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_event_response" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.events", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true }, "put": { "operationId": "waiting-room-update-event", "summary": "Update event", "description": "Updates a configured event for a waiting room.", "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_event_id" } }, { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_query_event" } } } }, "responses": { "200": { "description": "Update event response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_event_response" } } } }, "4XX": { "description": "Update event response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_event_response" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.events", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/waiting_rooms/{waiting_room_id}/events/{event_id}/details": { "get": { "operationId": "waiting-room-preview-active-event-details", "summary": "Preview active event details", "description": "Previews an event's configuration as if it was active. Inherited fields from the waiting room will be displayed with their current values.", "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_event_id" } }, { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "responses": { "200": { "description": "Preview active event details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_event_details_response" } } } }, "4XX": { "description": "Preview active event details response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_event_details_response" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Read", "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.events.details", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/waiting_rooms/{waiting_room_id}/rules": { "get": { "operationId": "waiting-room-list-waiting-room-rules", "summary": "List Waiting Room Rules", "description": "Lists rules for a waiting room.", "parameters": [ { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "responses": { "200": { "description": "List Waiting Room Rules response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_rules_response_collection" } } } }, "4XX": { "description": "List Waiting Room Rules response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_rules_response_collection" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Read", "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.rules", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "post": { "operationId": "waiting-room-create-waiting-room-rule", "summary": "Create Waiting Room Rule", "description": "Only available for the Waiting Room Advanced subscription. Creates a rule for a waiting room.", "parameters": [ { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_create_rule" } } } }, "responses": { "200": { "description": "Create Waiting Room Rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_rules_response_collection" } } } }, "4XX": { "description": "Create Waiting Room Rule response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_rules_response_collection" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.rules", "x-fern-sdk-method-name": "create", "x-forge-hidden": true }, "put": { "operationId": "waiting-room-replace-waiting-room-rules", "summary": "Replace Waiting Room Rules", "description": "Only available for the Waiting Room Advanced subscription. Replaces all rules for a waiting room.", "parameters": [ { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_update_rules" } } } }, "responses": { "200": { "description": "Replace Waiting Room Rules response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_rules_response_collection" } } } }, "4XX": { "description": "Replace Waiting Room Rules response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_rules_response_collection" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.rules", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/waiting_rooms/{waiting_room_id}/rules/{rule_id}": { "delete": { "operationId": "waiting-room-delete-waiting-room-rule", "summary": "Delete Waiting Room Rule", "description": "Deletes a rule for a waiting room.", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_rule_id" } }, { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": {} } }, "responses": { "200": { "description": "Delete Waiting Room Rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_rules_response_collection" } } } }, "4XX": { "description": "Delete Waiting Room Rule response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_rules_response_collection" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.rules", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "patch": { "operationId": "waiting-room-patch-waiting-room-rule", "summary": "Patch Waiting Room Rule", "description": "Patches a rule for a waiting room.", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_rule_id" } }, { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_patch_rule" } } } }, "responses": { "200": { "description": "Patch Waiting Room Rule response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_rules_response_collection" } } } }, "4XX": { "description": "Patch Waiting Room Rule response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_rules_response_collection" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.rules", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/waiting_rooms/{waiting_room_id}/status": { "get": { "operationId": "waiting-room-get-waiting-room-status", "summary": "Get waiting room status", "description": "Fetches the status of a configured waiting room. Response fields include:\n1. `status`: String indicating the status of the waiting room. The possible status are:\n\t- **not_queueing** indicates that the configured thresholds have not been met and all users are going through to the origin.\n\t- **queueing** indicates that the thresholds have been met and some users are held in the waiting room.\n\t- **event_prequeueing** indicates that an event is active and is currently prequeueing users before it starts.\n\t- **suspended** indicates that the room is suspended.\n2. `event_id`: String of the current event's `id` if an event is active, otherwise an empty string.\n3. `estimated_queued_users`: Integer of the estimated number of users currently waiting in the queue.\n4. `estimated_total_active_users`: Integer of the estimated number of users currently active on the origin.\n5. `max_estimated_time_minutes`: Integer of the maximum estimated time currently presented to the users.", "parameters": [ { "name": "waiting_room_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/waitingroom_identifier" } } ], "responses": { "200": { "description": "Get waiting room status response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/waitingroom_status_response" } } } }, "4XX": { "description": "Get waiting room status response failure", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_status_response" }, { "$ref": "#/components/schemas/waitingroom_api-response-common-failure" } ] } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Waiting Room" ], "x-api-token-group": [ "Waiting Rooms Read", "Waiting Rooms Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "waiting-rooms.statuses", "x-fern-sdk-method-name": "get", "x-forge-hidden": true } }, "/zones/{zone_id}/web3/hostnames": { "get": { "operationId": "web3-hostname-list-web3-hostnames", "summary": "List Web3 Hostnames", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } } ], "responses": { "200": { "description": "List Web3 Hostnames response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_collection_response" } } } }, "4XX": { "description": "List Web3 Hostnames error response (4XX).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_collection_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } }, "5XX": { "description": "List Web3 Hostnames response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_collection_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Web3 Hostname" ], "x-api-token-group": [ "Web3 Hostnames Write", "Web3 Hostnames Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web3.hostnames", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "web3-hostname-create-web3-hostname", "summary": "Create Web3 Hostname", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_create_request" } } } }, "responses": { "200": { "description": "Create Web3 Hostname response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_single_response" } } } }, "4XX": { "description": "Create Web3 Hostname error response (4XX).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_collection_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } }, "5XX": { "description": "Create Web3 Hostname response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_single_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Web3 Hostname" ], "x-api-token-group": [ "Web3 Hostnames Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web3.hostnames", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/web3/hostnames/{identifier}": { "delete": { "operationId": "web3-hostname-delete-web3-hostname", "summary": "Delete Web3 Hostname", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": {} } }, "responses": { "200": { "description": "Delete Web3 Hostname response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_api-response-single-id" } } } }, "4XX": { "description": "Delete Web3 Hostname error response (4XX).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_collection_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } }, "5XX": { "description": "Delete Web3 Hostname response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_api-response-single-id" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Web3 Hostname" ], "x-api-token-group": [ "Web3 Hostnames Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web3.hostnames", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "web3-hostname-web3-hostname-details", "summary": "Web3 Hostname Details", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } } ], "responses": { "200": { "description": "Web3 Hostname Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_single_response" } } } }, "4XX": { "description": "Web3 Hostname Details error response (4XX).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_collection_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } }, "5XX": { "description": "Web3 Hostname Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_single_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Web3 Hostname" ], "x-api-token-group": [ "Web3 Hostnames Write", "Web3 Hostnames Read" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web3.hostnames", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "patch": { "operationId": "web3-hostname-edit-web3-hostname", "summary": "Edit Web3 Hostname", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_modify_request" } } } }, "responses": { "200": { "description": "Edit Web3 Hostname response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_single_response" } } } }, "4XX": { "description": "Edit Web3 Hostname error response (4XX).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_collection_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } }, "5XX": { "description": "Edit Web3 Hostname response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_single_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Web3 Hostname" ], "x-api-token-group": [ "Web3 Hostnames Write" ], "x-cfPlanAvailability": { "business": true, "enterprise": true, "free": true, "pro": true }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web3.hostnames", "x-fern-sdk-method-name": "edit", "x-forge-hidden": true } }, "/zones/{zone_id}/web3/hostnames/{identifier}/ipfs_universal_path/content_list": { "get": { "operationId": "web3-hostname-ipfs-universal-path-gateway-content-list-details", "summary": "IPFS Universal Path Gateway Content List Details", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } } ], "responses": { "200": { "description": "IPFS Universal Path Gateway Content List Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_content_list_details_response" } } } }, "4XX": { "description": "IPFS Universal Path Gateway Content List Details error response (4XX).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_content_list_details_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } }, "5XX": { "description": "IPFS Universal Path Gateway Content List Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_content_list_details_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Web3 Hostname" ], "x-api-token-group": [ "Web3 Hostnames Write", "Web3 Hostnames Read" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web3.hostnames.ipfs-universal-paths.content-lists", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "web3-hostname-update-ipfs-universal-path-gateway-content-list", "summary": "Update IPFS Universal Path Gateway Content List", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_content_list_update_request" } } } }, "responses": { "200": { "description": "Update IPFS Universal Path Gateway Content List response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_content_list_details_response" } } } }, "4XX": { "description": "Update IPFS Universal Path Gateway Content List error response (4XX).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_content_list_details_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } }, "5XX": { "description": "Update IPFS Universal Path Gateway Content List response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_content_list_details_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Web3 Hostname" ], "x-api-token-group": [ "Web3 Hostnames Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web3.hostnames.ipfs-universal-paths.content-lists", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/web3/hostnames/{identifier}/ipfs_universal_path/content_list/entries": { "get": { "operationId": "web3-hostname-list-ipfs-universal-path-gateway-content-list-entries", "summary": "List IPFS Universal Path Gateway Content List Entries", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } } ], "responses": { "200": { "description": "List IPFS Universal Path Gateway Content List Entries response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_content_list_entry_collection_response" } } } }, "4XX": { "description": "List IPFS Universal Path Gateway Content List Entries error response (4XX).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_content_list_entry_collection_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } }, "5XX": { "description": "List IPFS Universal Path Gateway Content List Entries response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_content_list_entry_collection_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Web3 Hostname" ], "x-api-token-group": [ "Web3 Hostnames Write", "Web3 Hostnames Read" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web3.hostnames.ipfs-universal-paths.content-lists.entries", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "web3-hostname-create-ipfs-universal-path-gateway-content-list-entry", "summary": "Create IPFS Universal Path Gateway Content List Entry", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_content_list_entry_create_request" } } } }, "responses": { "200": { "description": "Create IPFS Universal Path Gateway Content List Entry response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_content_list_entry_single_response" } } } }, "4XX": { "description": "Create IPFS Universal Path Gateway Content List Entry error response (4XX).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_content_list_entry_single_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } }, "5XX": { "description": "Create IPFS Universal Path Gateway Content List Entry response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_content_list_entry_single_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Web3 Hostname" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web3.hostnames.ipfs-universal-paths.content-lists.entries", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/web3/hostnames/{identifier}/ipfs_universal_path/content_list/entries/{content_list_entry_identifier}": { "delete": { "operationId": "web3-hostname-delete-ipfs-universal-path-gateway-content-list-entry", "summary": "Delete IPFS Universal Path Gateway Content List Entry", "parameters": [ { "name": "content_list_entry_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } }, { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": {} } }, "responses": { "200": { "description": "Delete IPFS Universal Path Gateway Content List Entry response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_api-response-single-id" } } } }, "4XX": { "description": "Delete IPFS Universal Path Gateway Content List Entry error response (4XX).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_api-response-single-id" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } }, "5XX": { "description": "Delete IPFS Universal Path Gateway Content List Entry response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_api-response-single-id" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Web3 Hostname" ], "x-api-token-group": [ "Web3 Hostnames Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web3.hostnames.ipfs-universal-paths.content-lists.entries", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "web3-hostname-ipfs-universal-path-gateway-content-list-entry-details", "summary": "IPFS Universal Path Gateway Content List Entry Details", "parameters": [ { "name": "content_list_entry_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } }, { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } } ], "responses": { "200": { "description": "IPFS Universal Path Gateway Content List Entry Details response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_content_list_entry_single_response" } } } }, "4XX": { "description": "IPFS Universal Path Gateway Content List Entry Details error response (4XX).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_content_list_entry_single_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } }, "5XX": { "description": "IPFS Universal Path Gateway Content List Entry Details response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_content_list_entry_single_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Web3 Hostname" ], "x-api-token-group": [ "Web3 Hostnames Write", "Web3 Hostnames Read" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web3.hostnames.ipfs-universal-paths.content-lists.entries", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "web3-hostname-edit-ipfs-universal-path-gateway-content-list-entry", "summary": "Edit IPFS Universal Path Gateway Content List Entry", "parameters": [ { "name": "content_list_entry_identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } }, { "name": "identifier", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/web3_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_content_list_entry_create_request" } } } }, "responses": { "200": { "description": "Edit IPFS Universal Path Gateway Content List Entry response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/web3_content_list_entry_single_response" } } } }, "4XX": { "description": "Edit IPFS Universal Path Gateway Content List Entry error response (4XX).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_content_list_entry_single_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } }, "5XX": { "description": "Edit IPFS Universal Path Gateway Content List Entry response failure.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/web3_content_list_entry_single_response" }, { "$ref": "#/components/schemas/web3_api-response-common-failure" } ] } } } } }, "security": [ { "api_email": [], "api_key": [], "api_token": [] } ], "tags": [ "Web3 Hostname" ], "x-api-token-group": [ "Web3 Hostnames Write" ], "x-cfPlanAvailability": { "business": false, "enterprise": true, "free": false, "pro": false }, "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "web3.hostnames.ipfs-universal-paths.content-lists.entries", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } }, "/zones/{zone_id}/workers/routes": { "get": { "operationId": "worker-routes-list-routes", "summary": "List Routes", "description": "Returns routes for a zone.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } } ], "responses": { "200": { "description": "List Routes response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/workers_route" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "List Routes response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Routes" ], "x-api-token-group": [ "Workers Routes Write", "Workers Routes Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.routes", "x-fern-sdk-method-name": "list", "x-forge-hidden": true }, "post": { "operationId": "worker-routes-create-route", "summary": "Create Route", "description": "Creates a route that maps a URL pattern to a Worker.", "parameters": [ { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_route" } } } }, "responses": { "200": { "description": "Create Route response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_route" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Create Route response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Routes" ], "x-api-token-group": [ "Workers Routes Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.routes", "x-fern-sdk-method-name": "create", "x-forge-hidden": true } }, "/zones/{zone_id}/workers/routes/{route_id}": { "delete": { "operationId": "worker-routes-delete-route", "summary": "Delete Route", "description": "Deletes a route.", "parameters": [ { "name": "route_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } } ], "responses": { "200": { "description": "Delete Route response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/workers_identifier" } } } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Delete Route response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Routes" ], "x-api-token-group": [ "Workers Routes Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.routes", "x-fern-sdk-method-name": "delete", "x-forge-hidden": true }, "get": { "operationId": "worker-routes-get-route", "summary": "Get Route", "description": "Returns information about a route, including URL pattern and Worker.", "parameters": [ { "name": "route_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } } ], "responses": { "200": { "description": "Get Route response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_route" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Get Route response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Routes" ], "x-api-token-group": [ "Workers Routes Write", "Workers Routes Read" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.routes", "x-fern-sdk-method-name": "get", "x-forge-hidden": true }, "put": { "operationId": "worker-routes-update-route", "summary": "Update Route", "description": "Updates the URL pattern or Worker associated with a route.", "parameters": [ { "name": "route_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } }, { "name": "zone_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/workers_identifier" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_route" } } } }, "responses": { "200": { "description": "Update Route response.", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_route" } }, "required": [ "result" ], "type": "object" } ] } } } }, "4XX": { "description": "Update Route response failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workers_api-response-common-failure" } } } } }, "security": [ { "api_token": [] }, { "api_email": [], "api_key": [] } ], "tags": [ "Worker Routes" ], "x-api-token-group": [ "Workers Routes Write" ], "x-fern-availability": "generally-available", "x-fern-sdk-group-name": "workers.routes", "x-fern-sdk-method-name": "update", "x-forge-hidden": true } } }, "components": { "parameters": { "access_page": { "in": "query", "name": "page", "schema": { "description": "Page number of results.", "type": "integer", "default": 1 } }, "access_per_page": { "in": "query", "name": "per_page", "schema": { "description": "Number of results per page.", "type": "integer", "default": 1000, "maximum": 1000 } }, "analytics-engine_AccountId": { "description": "Cloudflare account identifier.", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } }, "api-shield_api_discovery_origin_parameter": { "description": "Filter results to only include discovery results sourced from a particular discovery engine\n * `ML` - Discovered operations that were sourced using ML API Discovery\n * `SessionIdentifier` - Discovered operations that were sourced using Session Identifier API Discovery\n", "in": "query", "name": "origin", "schema": { "$ref": "#/components/schemas/api-shield_api_discovery_origin" } }, "api-shield_api_discovery_state_parameter": { "description": "Filter results to only include discovery results in a particular state. States are as follows\n * `review` - Discovered operations that are not saved into API Shield Endpoint Management\n * `saved` - Discovered operations that are already saved into API Shield Endpoint Management\n * `ignored` - Discovered operations that have been marked as ignored\n", "in": "query", "name": "state", "schema": { "$ref": "#/components/schemas/api-shield_api_discovery_state" } }, "api-shield_config_id": { "description": "Token Configuration ID", "example": "4a7ee8d3-dd63-4ceb-9d5f-c27831854ce7", "in": "path", "name": "config_id", "required": true, "schema": { "$ref": "#/components/schemas/api-shield_uuid-2" } }, "api-shield_diff_parameter": { "in": "query", "name": "diff", "schema": { "description": "When `true`, only return API Discovery results that are not saved into API Shield Endpoint Management", "type": "boolean" } }, "api-shield_direction_parameter": { "in": "query", "name": "direction", "schema": { "description": "Direction to order results.", "type": "string", "example": "desc", "enum": [ "asc", "desc" ] } }, "api-shield_discovery_id": { "description": "Discovery ID of a discovered operation", "in": "path", "name": "discovery_id", "required": true, "schema": { "$ref": "#/components/schemas/api-shield_uuid-2" } }, "api-shield_endpoint_parameter": { "in": "query", "name": "endpoint", "schema": { "description": "Filter results to only include endpoints containing this pattern.", "type": "string", "example": "/api/v1" } }, "api-shield_filter_parameter": { "description": "Filter for labels where the name or description matches using substring match", "in": "query", "name": "filter", "schema": { "type": "string", "example": "login" } }, "api-shield_host_parameter": { "in": "query", "name": "host", "schema": { "description": "Filter results to only include the specified hosts.", "type": "array", "items": { "example": "api.cloudflare.com", "type": "string" }, "uniqueItems": true } }, "api-shield_label_name_parameter": { "description": "The label name", "in": "path", "name": "name", "required": true, "schema": { "$ref": "#/components/schemas/api-shield_label_name" } }, "api-shield_method_parameter": { "in": "query", "name": "method", "schema": { "description": "Filter results to only include the specified HTTP methods.", "type": "array", "items": { "example": "GET", "type": "string" }, "uniqueItems": true } }, "api-shield_old_omit_source": { "description": "Omit the source-files of schemas and only retrieve their meta-data.", "in": "query", "name": "omit_source", "schema": { "type": "boolean", "default": false } }, "api-shield_old_schema_id": { "description": "Identifier for the schema-ID", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "in": "path", "name": "schema_id", "required": true, "schema": { "type": "string", "format": "uuid", "maxLength": 36, "readOnly": true } }, "api-shield_omit_source_query": { "description": "Omit the source-files of schemas and only retrieve their meta-data.", "in": "query", "name": "omit_source", "schema": { "type": "boolean", "default": false } }, "api-shield_operation_feature_parameter": { "description": "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.", "in": "query", "name": "feature", "schema": { "type": "array", "items": { "enum": [ "thresholds", "parameter_schemas", "schema_info", "confidence_intervals" ], "example": "thresholds", "type": "string" }, "example": [ "thresholds" ], "uniqueItems": true } }, "api-shield_operation_id": { "description": "Identifier for the operation", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "in": "path", "name": "operation_id", "required": true, "schema": { "$ref": "#/components/schemas/api-shield_uuid" } }, "api-shield_order_parameter": { "in": "query", "name": "order", "schema": { "description": "Field to order by", "type": "string", "example": "method", "enum": [ "host", "method", "endpoint", "traffic_stats.requests", "traffic_stats.last_updated" ] } }, "api-shield_order_parameter-2": { "in": "query", "name": "order", "schema": { "description": "Field to order by", "type": "string", "example": "description", "enum": [ "name", "description", "created_at", "last_updated", "mapped_resources.operations" ] } }, "api-shield_page": { "description": "Page number of paginated results.", "in": "query", "name": "page", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, "api-shield_per_page": { "description": "Maximum number of results per page.", "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 20, "maximum": 50, "minimum": 5 } }, "api-shield_rule_id": { "description": "Token Validation Rule ID", "example": "4a7ee8d3-dd63-4ceb-9d5f-c27831854ce7", "in": "path", "name": "rule_id", "required": true, "schema": { "$ref": "#/components/schemas/api-shield_uuid-2" } }, "api-shield_schema_id_path": { "description": "The unique identifier of the schema", "in": "path", "name": "schema_id", "required": true, "schema": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/api-shield_uuid-2" }, { "format": "uuid", "readOnly": true, "type": "string" } ] } }, "api-shield_source_parameter": { "description": "Filter for labels with source", "in": "query", "name": "source", "schema": { "$ref": "#/components/schemas/api-shield_label_source" } }, "api-shield_with_mapped_resource_counts_parameter": { "description": "Include `mapped_resources` for each label", "in": "query", "name": "with_mapped_resource_counts", "schema": { "type": "boolean", "example": true, "default": false } }, "api-shield_with_schemas_parameter": { "description": "When true, includes OpenAPI schemas (both uploaded and learned) for the operation in the response. Due to the conversion overhead, this parameter is only supported on single-operation retrieval.", "in": "query", "name": "with_schemas", "schema": { "type": "boolean", "default": false } }, "api-shield_zone_id": { "in": "path", "name": "zone_id", "required": true, "schema": { "$ref": "#/components/schemas/api-shield_identifier-2" } }, "art_account_id": { "description": "Cloudflare account identifier.", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "pattern": "^[0-9a-f]{32}$" } }, "billable-usage-api_account_id": { "description": "Identifies the Cloudflare account.", "in": "path", "name": "account_id", "required": true, "schema": { "$ref": "#/components/schemas/billable-usage-api_identifier" } }, "billable-usage-api_from": { "description": "Start date for the usage query (ISO 8601). The provided time range must include the subscription billing cycle anchor day, otherwise no usage data is returned. Use the info endpoint to retrieve the subscription anchor day.", "in": "query", "name": "from", "schema": { "type": "string", "format": "date", "example": "2025-05-01" } }, "billable-usage-api_organization_id": { "description": "Identifies the Cloudflare organization.", "in": "path", "name": "organization_id", "required": true, "schema": { "$ref": "#/components/schemas/billable-usage-api_identifier" } }, "billable-usage-api_to": { "description": "End date for the usage query (ISO 8601).", "in": "query", "name": "to", "schema": { "type": "string", "format": "date", "example": "2025-05-31" } }, "billable-usage-api_v2_from": { "description": "Start date for the usage query (ISO 8601). Required if `to` is set. When omitted along with `to`, defaults to the start of the current month. Filters by charge period (when consumption happened), not billing period. The maximum date range is 31 days.", "in": "query", "name": "from", "schema": { "type": "string", "format": "date", "example": "2025-05-01" } }, "billable-usage-api_v2_to": { "description": "End date for the usage query (ISO 8601). Required if `from` is set. When omitted along with `from`, defaults to today. Filters by charge period (when consumption happened), not billing period. The maximum date range is 31 days.", "in": "query", "name": "to", "schema": { "type": "string", "format": "date", "example": "2025-05-31" } }, "brex_AccountId": { "description": "Cloudflare account ID.", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string", "minLength": 1 } }, "builds_AccountId": { "in": "path", "name": "account_id", "required": true, "schema": { "$ref": "#/components/schemas/builds_account_id" } }, "builds_BuildUuid": { "in": "path", "name": "build_uuid", "required": true, "schema": { "$ref": "#/components/schemas/builds_build_uuid" } }, "builds_DeployHookUuid": { "description": "Deploy hook UUID", "in": "path", "name": "deploy_hook_uuid", "required": true, "schema": { "$ref": "#/components/schemas/builds_deploy_hook_uuid" } }, "builds_Page": { "description": "Page number for pagination", "in": "query", "name": "page", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, "builds_PerPage": { "description": "Number of items per page", "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 50, "maximum": 200, "minimum": 1 } }, "builds_RepoConnectionUuid": { "in": "path", "name": "repo_connection_uuid", "required": true, "schema": { "$ref": "#/components/schemas/builds_repo_connection_uuid" } }, "builds_ScriptName": { "description": "Human-readable name of the worker.", "in": "path", "name": "script_name", "required": true, "schema": { "$ref": "#/components/schemas/builds_script_name" } }, "builds_ScriptTag": { "description": "The Worker script tag (external script ID)", "in": "path", "name": "script_tag", "required": true, "schema": { "$ref": "#/components/schemas/builds_external_script_id" } }, "builds_TriggerUuid": { "in": "path", "name": "trigger_uuid", "required": true, "schema": { "$ref": "#/components/schemas/builds_trigger_uuid" } }, "cc_AccountId": { "description": "Account identifier.", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string", "example": "account-123" } }, "cloudforce-one_account_id": { "description": "Cloudflare account ID.", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } }, "csam-config-service_zone_id": { "description": "Identifier for the zone.", "in": "path", "name": "zone_id", "required": true, "schema": { "$ref": "#/components/schemas/csam-config-service_zone_identifier" } }, "dls_account_id": { "in": "path", "name": "account_id", "required": true, "schema": { "$ref": "#/components/schemas/dls_identifier" } }, "dls_hostname": { "in": "path", "name": "hostname", "required": true, "schema": { "$ref": "#/components/schemas/dls_hostname" } }, "dls_zone_id": { "in": "path", "name": "zone_id", "required": true, "schema": { "$ref": "#/components/schemas/dls_identifier" } }, "dns-records_include_shadow_metadata": { "in": "query", "name": "include_shadow_metadata", "schema": { "description": "Whether to include shadow metadata in the `meta` field of each record in the response. See [Shadowed records](https://developers.cloudflare.com/dns/manage-dns-records/reference/shadowed-records).\n", "type": "boolean", "example": true, "default": false } }, "email-auth_record_id": { "description": "DNS record ID (rec_tag) to inspect", "example": "e5bb46707a802688812d5d1c9f7977d4", "in": "query", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9-]{1,64}$" } }, "email-auth_zone_id": { "description": "Zone identifier.", "in": "path", "name": "zone_id", "required": true, "schema": { "$ref": "#/components/schemas/email-auth_identifier" } }, "email-security_account_id": { "description": "Account identifier tag.", "in": "path", "name": "account_id", "required": true, "schema": { "$ref": "#/components/schemas/email-security_identifier" } }, "email-security_direction": { "description": "The sorting direction.", "in": "query", "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, "email-security_page": { "description": "Current page within paginated list of results.", "in": "query", "name": "page", "schema": { "type": "integer", "example": 1, "default": 1, "minimum": 1 } }, "email-security_per_page": { "description": "The number of results per page. Maximum value is 1000.", "in": "query", "name": "per_page", "schema": { "type": "integer", "example": 20, "default": 20, "maximum": 1000, "minimum": 1 } }, "email-security_search": { "description": "Search term for filtering records. Behavior may change.", "in": "query", "name": "search", "schema": { "type": "string" } }, "email-security_submission": { "description": "When true, search the submissions datastore only. When false or omitted, search the\nregular datastore only.", "in": "query", "name": "submission", "schema": { "type": "boolean" } }, "healthchecks_page": { "description": "Page number of paginated results.", "in": "query", "name": "page", "schema": { "type": "number", "default": 1, "minimum": 1 } }, "healthchecks_per_page": { "description": "Maximum number of results per page. Must be a multiple of 5.", "in": "query", "name": "per_page", "schema": { "type": "number", "default": 25, "maximum": 1000, "minimum": 5 } }, "iam_include_expired": { "description": "When true, includes recently-expired tokens in the response.", "in": "query", "name": "include_expired", "schema": { "type": "boolean", "default": false } }, "intel-sinkholes_account_id": { "description": "The unique identifier for the Cloudflare account.", "in": "path", "name": "account_id", "required": true, "schema": { "$ref": "#/components/schemas/intel-sinkholes_identifier" } }, "intel-sinkholes_ingress_id": { "description": "The unique identifier for the ingress rule.", "in": "path", "name": "ingress_id", "required": true, "schema": { "type": "string", "example": "de32ae5203724ed08dcc26e971a4d22f" } }, "intel-sinkholes_sinkhole_id": { "description": "The unique identifier for the sinkhole.", "in": "path", "name": "sinkhole_id", "required": true, "schema": { "type": "string", "example": "93defa6e909e464e8c89a85859f36d3c" } }, "intel-sinkholes_zone_id": { "description": "The unique identifier for the Cloudflare zone.", "in": "path", "name": "zone_id", "required": true, "schema": { "$ref": "#/components/schemas/intel-sinkholes_identifier" } }, "kamino_environment_id": { "description": "Reference identifier for the environment.", "in": "path", "name": "environment_id", "required": true, "schema": { "type": "string" } }, "kamino_zone_id": { "description": "Identifier of the zone.", "in": "path", "name": "zone_id", "required": true, "schema": { "type": "string" } }, "lex_AccountID": { "description": "Cloudflare account ID.", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "lex_DatasetID": { "description": "Log Explorer dataset ID.", "in": "path", "name": "dataset_id", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "lex_ZoneID": { "description": "Cloudflare zone ID.", "in": "path", "name": "zone_id", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "logpull_accessKeyIdHeader": { "in": "header", "name": "R2-Access-Key-Id", "required": true, "schema": { "$ref": "#/components/schemas/logpull_AccessKeyId" } }, "logpull_account_id": { "description": "Cloudflare account ID (32-character hex string).", "in": "path", "name": "account_id", "required": true, "schema": { "$ref": "#/components/schemas/logpull_AccountId" } }, "logpull_bucketParam": { "description": "R2 bucket name.", "in": "query", "name": "bucket", "required": true, "schema": { "$ref": "#/components/schemas/logpull_Bucket" } }, "logpull_endParam": { "description": "End time in RFC3339 format.", "in": "query", "name": "end", "required": true, "schema": { "$ref": "#/components/schemas/logpull_TimestampRFC3339" } }, "logpull_limitParam": { "description": "Maximum number of results to return.", "in": "query", "name": "limit", "schema": { "$ref": "#/components/schemas/logpull_Limit" } }, "logpull_prefixParam": { "description": "R2 bucket prefix logs are stored under.", "in": "query", "name": "prefix", "schema": { "$ref": "#/components/schemas/logpull_Prefix" } }, "logpull_secretAccessKeyHeader": { "in": "header", "name": "R2-Secret-Access-Key", "required": true, "schema": { "$ref": "#/components/schemas/logpull_SecretAccessKey" } }, "logpull_startParam": { "description": "Start time in RFC3339 format.", "in": "query", "name": "start", "required": true, "schema": { "$ref": "#/components/schemas/logpull_TimestampRFC3339" } }, "moq_account_id": { "description": "Cloudflare account identifier.", "in": "path", "name": "account_id", "required": true, "schema": { "$ref": "#/components/schemas/moq_account_identifier" } }, "moq_asc": { "description": "Sort order by `created`. When true, results are returned oldest-first\n(ascending); otherwise newest-first (descending, the default).\n", "in": "query", "name": "asc", "schema": { "type": "boolean", "default": false } }, "moq_created_after": { "description": "Cursor for pagination. Returns relays created strictly after this\nRFC 3339 timestamp (typically the `created` value of the last item\non the current page, to fetch the next page).\n", "in": "query", "name": "created_after", "schema": { "type": "string", "format": "date-time", "example": "2026-03-27T15:00:00Z" } }, "moq_created_before": { "description": "Cursor for pagination. Returns relays created strictly before this\nRFC 3339 timestamp (typically the `created` value of the first item\non the current page, to fetch the previous page).\n", "in": "query", "name": "created_before", "schema": { "type": "string", "format": "date-time", "example": "2026-03-27T15:00:00Z" } }, "moq_jti": { "description": "Token identifier (jti — 32 hex characters).", "in": "path", "name": "jti", "required": true, "schema": { "type": "string", "example": "f3a1b2c3d4e5f67890a1b2c3d4e5f678", "pattern": "^[0-9a-f]{32}$" } }, "moq_per_page": { "description": "Maximum number of relays to return per page. Values above the maximum are\nclamped to it rather than rejected.\n", "in": "query", "name": "per_page", "schema": { "type": "integer", "example": 50, "default": 1000, "maximum": 1000, "minimum": 1 } }, "moq_relay_id": { "description": "Relay unique identifier (32 hex characters).", "in": "path", "name": "relay_id", "required": true, "schema": { "type": "string", "example": "a1b2c3d4e5f67890a1b2c3d4e5f67890", "pattern": "^[0-9a-f]{32}$" } }, "organizations-api_OrganizationListFiltersContainingAccount": { "description": "Filter the list of organizations to the ones that contain this particular\naccount.", "explode": false, "in": "query", "name": "containing.account", "schema": { "type": "string" } }, "organizations-api_OrganizationListFiltersContainingOrganization": { "description": "Filter the list of organizations to the ones that contain this particular\norganization.", "explode": false, "in": "query", "name": "containing.organization", "schema": { "type": "string" } }, "organizations-api_OrganizationListFiltersContainingUser": { "description": "Filter the list of organizations to the ones that contain this particular\nuser.\n\nIMPORTANT: Just because an organization \"contains\" a user is not a\nrepresentation of any authorization or privilege to manage any resources\ntherein. An organization \"containing\" a user simply means the user is managed by\nthat organization.", "explode": false, "in": "query", "name": "containing.user", "schema": { "type": "string" } }, "organizations-api_OrganizationListFiltersId": { "description": "Only return organizations with the specified IDs (ex. id=foo&id=bar). Send multiple elements\nby repeating the query value.", "explode": false, "in": "query", "name": "id", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_OrganizationID" } } }, "organizations-api_OrganizationListFiltersName": { "description": "(case-sensitive) Filter the list of organizations to where the name is equal to a\nparticular string.", "explode": false, "in": "query", "name": "name", "schema": { "type": "string" } }, "organizations-api_OrganizationListFiltersNameContains": { "description": "(case-insensitive) Filter the list of organizations to where the name contains a particular\nstring.", "explode": false, "in": "query", "name": "name.contains", "schema": { "type": "string" } }, "organizations-api_OrganizationListFiltersNameEndsWith": { "description": "(case-insensitive) Filter the list of organizations to where the name ends with a particular\nstring.", "explode": false, "in": "query", "name": "name.endsWith", "schema": { "type": "string" } }, "organizations-api_OrganizationListFiltersNameStartsWith": { "description": "(case-insensitive) Filter the list of organizations to where the name starts with a\nparticular string.", "explode": false, "in": "query", "name": "name.startsWith", "schema": { "type": "string" } }, "organizations-api_OrganizationListFiltersParentId": { "description": "Filter the list of organizations to the ones that are a sub-organization\nof the specified organization.\n\n\"null\" is a valid value to provide for this parameter. It means \"where\nan organization has no parent (i.e. it is a 'root' organization).\"", "explode": false, "in": "query", "name": "parent.id", "schema": { "anyOf": [ { "$ref": "#/components/schemas/organizations-api_OrganizationID" }, { "enum": [ "null" ], "type": "string" } ] } }, "organizations-api_PageTokenParamsPageSize": { "description": "The amount of items to return. Defaults to 10.", "explode": false, "in": "query", "name": "page_size", "schema": { "type": "integer", "maximum": 1000, "minimum": 0 } }, "organizations-api_PageTokenParamsPageToken": { "description": "An opaque token returned from the last list response that when\nprovided will retrieve the next page.\n\nParameters used to filter the retrieved list must remain in subsequent\nrequests with a page token.", "explode": false, "in": "query", "name": "page_token", "schema": { "type": "string" } }, "posture-api_AccountTag": { "description": "Cloudflare account ID for the user making the request.", "example": "46148281d8a93d002ef242d8b0d5f9f6", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string" } }, "posture-api_Archived": { "description": "Archived", "in": "query", "name": "archived", "schema": { "type": "boolean" } }, "posture-api_AssetIds": { "description": "Filter finding instances by an array of asset IDs. Supports multiple comma-separated values.", "example": [ "c416bc38-75db-425f-ae25-c37b5df5c37f", "qw45mm66-75db-425f-ae25-c37b5df5c37f" ], "in": "query", "name": "asset_ids", "schema": { "type": "array", "items": { "format": "uuid", "type": "string" } } }, "posture-api_Direction": { "description": "Direction to order results.", "in": "query", "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, "posture-api_FindingIdByte": { "description": "A base64-encoded ID identifying this Finding.", "in": "path", "name": "finding_id", "required": true, "schema": { "type": "string", "format": "byte" } }, "posture-api_FindingInstanceId": { "description": "A uuid ID identifying this Finding instance.", "in": "path", "name": "instance_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, "posture-api_FindingInstanceIds": { "description": "Filter finding instances by an array of finding instance IDs. Supports multiple comma-separated values.", "example": [ "c416bc38-75db-425f-ae25-c37b5df5c37f", "b555bc38-75db-425f-ae25-c37b5df5c37f" ], "in": "query", "name": "finding_instance_ids", "schema": { "type": "array", "items": { "format": "uuid", "type": "string" } } }, "posture-api_FindingInstanceOrder": { "description": "Which field to use when ordering the Finding's instances.\nWhen ordering by 'remediation.status', only the most recent non-stale remediation job is considered. Stale jobs (created before the instance's affliction_date) are treated as having no status for ordering purposes.", "in": "query", "name": "order", "schema": { "type": "string", "enum": [ "affliction_date", "asset.name", "remediation.status" ] } }, "posture-api_FindingOrder": { "description": "Which field to use when ordering the findings.", "in": "query", "name": "order", "schema": { "type": "string", "enum": [ "finding.name", "instance_count", "integration.name", "latest_affliction_date", "severity" ] } }, "posture-api_FindingTypeId": { "description": "A UUID string identifying the finding type.", "in": "path", "name": "finding_type_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, "posture-api_FindingTypeIdParam": { "description": "A UUID string identifying the finding type.", "in": "path", "name": "finding_type_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, "posture-api_FindingTypeIds": { "description": "A comma separated list of UUIDs identifying the finding type(s).", "example": "1bd08189-9871-43f9-b838-60338d1d2a15,d7446a0d-da76-4f05-9659-803d78b27b7d", "in": "query", "name": "finding_type_ids", "schema": { "type": "string", "format": "uuid" } }, "posture-api_FindingTypeSearch": { "description": "Filter finding types by name or ID (case-insensitive substring match).", "in": "query", "name": "search", "schema": { "type": "string" } }, "posture-api_FindingTypeVendors": { "description": "Filter finding types by vendor. Supports multiple comma-separated values. Each value may be either the vendor enum (GOOGLE_WORKSPACE) or the friendly name returned by the read routes (Google Workspace).", "explode": false, "in": "query", "name": "vendors", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/posture-api_VendorsEnum" } }, "style": "form" }, "posture-api_Ignored": { "description": "Filter for only the ignored findings. Set to false to only see \"active\" items", "in": "query", "name": "ignored", "schema": { "type": "boolean" } }, "posture-api_IntegrationId": { "description": "Filter by an integration ID", "in": "query", "name": "integration_id", "schema": { "type": "string", "format": "uuid" } }, "posture-api_MaxAfflictionDate": { "description": "Filter to view findings that occurred on or before the affliction date. Can be a date-time in ISO 8601 format or an epoch timestamp.", "in": "query", "name": "max_affliction_date", "schema": { "type": "string", "format": "date-time" } }, "posture-api_MinAfflictionDate": { "description": "Filter to view findings that occurred on or after the affliction date. Can be a date-time in ISO 8601 format or an epoch timestamp.", "in": "query", "name": "min_affliction_date", "schema": { "type": "string", "format": "date-time" } }, "posture-api_Observation": { "description": "Filter by observation type of the finding", "in": "query", "name": "observation", "schema": { "type": "string", "enum": [ "Activity", "Insight", "Issue" ] } }, "posture-api_Page": { "description": "A page number within the paginated result set.", "in": "query", "name": "page", "schema": { "type": "integer" } }, "posture-api_PerPage": { "description": "Number of results to return per page.", "in": "query", "name": "per_page", "schema": { "type": "integer" } }, "posture-api_PolicyId": { "description": "A UUID identifying the policy.", "in": "path", "name": "policy_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, "posture-api_Product": { "description": "Filter by product category of the finding", "in": "query", "name": "product", "schema": { "type": "string", "enum": [ "Cloud", "Saas" ] } }, "posture-api_RemediationStatuses": { "description": "Filter finding instances by most recent remediation job status. Supports multiple comma-separated values.\nUse 'none' to filter instances with no remediation jobs or instances where the most recent job is stale.\nNote: Stale jobs (created before the instance's affliction_date) are ignored for filtering purposes, but are still included in the 'remediations' array with stale=true.", "example": [ "pending", "completed", "none" ], "explode": false, "in": "query", "name": "remediation_statuses", "schema": { "type": "array", "items": { "enum": [ "none", "pending", "processing", "validating", "completed", "failed" ], "type": "string" } }, "style": "form" }, "posture-api_Search": { "description": "A search term.", "in": "query", "name": "search", "schema": { "type": "string" } }, "posture-api_Severity": { "description": "Filter by severity", "in": "query", "name": "severity", "schema": { "type": "string", "enum": [ "Critical", "High", "Medium", "Low" ] } }, "posture-api_StorageNamespaceId": { "description": "A storage namespace identifier for the finding, used to scope finding instance exports.\nConstructed by base64-decoding the finding ID (which encodes `integration_id:finding_type_id`)\nand replacing the colon separator with a hyphen.\nFor example, a finding ID that decodes to `00000000-0000-0000-0000-000000000001:00000000-0000-0000-0000-000000000002`\nbecomes `00000000-0000-0000-0000-000000000001-00000000-0000-0000-0000-000000000002`.", "example": "00000000-0000-0000-0000-000000000001-00000000-0000-0000-0000-000000000002", "in": "path", "name": "storage_namespace_id", "required": true, "schema": { "type": "string", "pattern": "^[\\da-f]{8}-([\\da-f]{4}-){3}[\\da-f]{12}-[\\da-f]{8}-([\\da-f]{4}-){3}[\\da-f]{12}$" } }, "posture-api_Type": { "description": "Filter by type of the finding", "in": "query", "name": "type", "schema": { "type": "string", "enum": [ "Content", "Posture" ] } }, "posture-api_Vendor": { "description": "Filter by vendor", "in": "query", "name": "vendor", "schema": { "$ref": "#/components/schemas/posture-api_VendorsEnum" } }, "posture-api_WebhookId": { "description": "A UUID identifying the webhook configuration.", "in": "path", "name": "webhook_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, "realtimekit_account_id": { "description": "The account identifier tag.", "example": "023e105f4ecef8ad9ca31a8372d0c353", "in": "path", "name": "account_id", "required": true, "schema": { "$ref": "#/components/schemas/realtimekit_account_identifier" } }, "realtimekit_app_id": { "description": "A Cloudflare-generated unique identifier for an item.", "example": "14a396e7-ca44-4937-bf1f-050a69118543", "in": "path", "name": "app_id", "required": true, "schema": { "$ref": "#/components/schemas/realtimekit_app_id" } }, "realtimekit_endDate": { "description": "end date in YYYY-MM-DD format", "examples": { "default": { "value": "2022-09-22T00:00:00Z" } }, "in": "query", "name": "end_date", "schema": { "type": "string", "example": "2022-09-22T00:00:00Z" } }, "realtimekit_endTime": { "description": "The end time range for which you want to retrieve the meetings. The time must be specified in ISO format.", "in": "query", "name": "end_time", "schema": { "type": "string", "format": "date-time" } }, "realtimekit_meeting_id": { "description": "The unique identifier for the meeting.", "example": "550e8400-e29b-41d4-a716-446655440000", "in": "path", "name": "meeting_id", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$" } }, "realtimekit_meetingId": { "description": "ID of the meeting", "in": "path", "name": "meeting_id", "required": true, "schema": { "type": "string" } }, "realtimekit_pageNo": { "allowEmptyValue": true, "description": "The page number from which you want your page search results to be displayed.", "in": "query", "name": "page_no", "schema": { "type": "number", "minimum": 0 } }, "realtimekit_participantId": { "description": "ID of the participant", "in": "path", "name": "participant_id", "required": true, "schema": { "type": "string" } }, "realtimekit_participants": { "examples": { "default": { "value": "1:10" } }, "in": "query", "name": "participants", "schema": { "type": "string", "example": "1:10" } }, "realtimekit_participantsSortBy": { "in": "query", "name": "sort_by", "schema": { "type": "string", "enum": [ "joinedAt", "duration" ] } }, "realtimekit_perPage": { "allowEmptyValue": true, "description": "Number of results per page", "in": "query", "name": "per_page", "schema": { "type": "number", "minimum": 0 } }, "realtimekit_recordingSortBy": { "in": "query", "name": "sort_by", "schema": { "type": "string", "enum": [ "invokedTime" ] } }, "realtimekit_recordingStatus": { "description": "Filter by one or more recording status", "explode": false, "in": "query", "name": "status", "schema": { "type": "array", "items": { "enum": [ "INVOKED", "RECORDING", "UPLOADING", "UPLOADED", "ERRORED", "PAUSED" ], "type": "string" } } }, "realtimekit_search": { "description": "The search query string. You can search using the meeting ID or title.", "in": "query", "name": "search", "schema": { "type": "string" } }, "realtimekit_sessionId": { "description": "ID of the session", "in": "path", "name": "session_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, "realtimekit_sortBy": { "in": "query", "name": "sort_by", "schema": { "type": "string", "enum": [ "minutesConsumed", "createdAt" ] } }, "realtimekit_sortOrder": { "in": "query", "name": "sort_order", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } }, "realtimekit_startDate": { "description": "start date in YYYY-MM-DD format", "examples": { "default": { "value": "2022-09-01T00:00:00Z" } }, "in": "query", "name": "start_date", "schema": { "type": "string", "example": "2022-09-01T00:00:00Z" } }, "realtimekit_startTime": { "description": "The start time range for which you want to retrieve the meetings. The time must be specified in ISO format.", "in": "query", "name": "start_time", "schema": { "type": "string", "format": "date-time" } }, "realtimekit_status": { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "LIVE", "ENDED" ] } }, "realtimekit_streamId": { "description": "ID of the livestream", "in": "path", "name": "stream_id", "required": true, "schema": { "type": "number" }, "style": "simple" }, "registrar-api-sandbox_cursor_pagination_cursor": { "description": "Opaque token from a previous response's `result_info.cursor`.\nPass this value to fetch the next page of results. Omit (or\npass an empty string) for the first page.\n", "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 256 } }, "registrar-api-sandbox_cursor_pagination_direction": { "description": "Sort direction for results. Defaults to ascending order.\n", "in": "query", "name": "direction", "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } }, "registrar-api-sandbox_cursor_pagination_per_page": { "description": "Number of items to return per page.", "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 20, "maximum": 50, "minimum": 1 } }, "registrar-api_cursor_pagination_cursor": { "description": "Opaque token from a previous response's `result_info.cursor`.\nPass this value to fetch the next page of results. Omit (or\npass an empty string) for the first page.\n", "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 256 } }, "registrar-api_cursor_pagination_direction": { "description": "Sort direction for results. Defaults to ascending order.\n", "in": "query", "name": "direction", "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } }, "registrar-api_cursor_pagination_per_page": { "description": "Number of items to return per page.", "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 20, "maximum": 50, "minimum": 1 } }, "resource-sharing_direction": { "description": "Direction to sort objects.", "in": "query", "name": "direction", "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } }, "resource-sharing_include_recipient_counts": { "description": "Include recipient counts in the response.", "in": "query", "name": "include_recipient_counts", "schema": { "type": "boolean", "example": true } }, "resource-sharing_include_resources": { "description": "Include resources in the response.", "in": "query", "name": "include_resources", "schema": { "type": "boolean", "example": true } }, "resource-sharing_kind": { "description": "Filter shares by kind.", "in": "query", "name": "kind", "schema": { "$ref": "#/components/schemas/resource-sharing_share_kind" } }, "resource-sharing_order": { "description": "Order shares by values in the given field.", "in": "query", "name": "order", "schema": { "type": "string", "default": "created", "enum": [ "name", "created" ] } }, "resource-sharing_page": { "description": "Page number. Defaults to `1` when `per_page` is supplied without\n`page`. May be omitted entirely along with `per_page` to receive a\nnon-paginated response.", "in": "query", "name": "page", "schema": { "type": "integer", "example": 2, "default": 1, "minimum": 1, "multipleOf": 1 } }, "resource-sharing_per_page": { "description": "Number of objects to return per page. Defaults to `20` when `page`\nis supplied without `per_page`. May be omitted entirely along with\n`page` to receive a non-paginated response.", "in": "query", "name": "per_page", "schema": { "type": "integer", "example": 20, "default": 20, "maximum": 100, "minimum": 1, "multipleOf": 1 } }, "resource-sharing_resource_status": { "description": "Filter share resources by status.", "in": "query", "name": "status", "schema": { "$ref": "#/components/schemas/resource-sharing_resource_status" } }, "resource-sharing_resource_type": { "description": "Filter share resources by resource_type.", "in": "query", "name": "resource_type", "schema": { "$ref": "#/components/schemas/resource-sharing_resource_type" } }, "resource-sharing_resource_types": { "description": "Filter share resources by resource_types.", "in": "query", "name": "resource_types", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/resource-sharing_resource_type" } } }, "resource-sharing_status": { "description": "Filter shares by status.", "in": "query", "name": "status", "schema": { "$ref": "#/components/schemas/resource-sharing_share_status" } }, "resource-sharing_tag": { "description": "Filter shares by tag. Each value is either `key=value` (matches shares whose tags contain that key/value pair) or `key` alone (matches shares that have any value for that key). May be repeated; multiple `tag` parameters are ANDed together. Maximum 20 `tag` parameters per request.", "explode": true, "in": "query", "name": "tag", "schema": { "type": "array", "items": { "example": "env=production", "maxLength": 1281, "type": "string" }, "maxItems": 20 }, "style": "form" }, "resource-sharing_target_type": { "description": "Filter shares by target_type.", "in": "query", "name": "target_type", "schema": { "$ref": "#/components/schemas/resource-sharing_share_target_type" } }, "resource-tagging_cursor": { "description": "Cursor for pagination.", "in": "query", "name": "cursor", "schema": { "type": "string", "example": "eyJhY2NvdW50X2lkIjoxMjM0NTY3ODkwfQ" } }, "resource-tagging_if_match": { "description": "ETag value for optimistic concurrency control. When provided, the server will\nverify the current resource ETag matches before applying the write. Returns\n412 Precondition Failed if the resource has been modified since the ETag was\nobtained. Omit this header for unconditional writes.\n", "in": "header", "name": "If-Match", "schema": { "type": "string", "example": "\"v1:RBNvo1WzZ4oRRq0W9-hkng\"" } }, "resource-tagging_tag": { "description": "Filter resources by tag criteria. This parameter can be repeated multiple times, with AND logic between parameters.\n\nSupported syntax:\n- **Key-only**: `tag=` - Resource must have the tag key (e.g., `tag=production`)\n- **Key-value**: `tag==` - Resource must have the tag with specific value (e.g., `tag=env=prod`)\n- **Multiple values (OR)**: `tag==,` - Resource must have tag with any of the values (e.g., `tag=env=prod,staging`)\n- **Negate key-only**: `tag=!` - Resource must not have the tag key (e.g., `tag=!archived`)\n- **Negate key-value**: `tag=!=` - Resource must not have the tag with specific value (e.g., `tag=region!=us-west-1`)\n\nMultiple tag parameters are combined with AND logic.\n", "explode": true, "in": "query", "name": "tag", "schema": { "type": "array", "items": { "type": "string" }, "example": [ "production", "env=prod", "env=prod,staging", "!archived", "region!=us-west-1" ] } }, "resource-tagging_type": { "description": "Filter by resource type.", "in": "query", "name": "type", "schema": { "$ref": "#/components/schemas/resource-tagging_resource_type" } }, "rulesets_DryRun": { "description": "Validates the request without persisting changes when set to `true`. Responses that normally return 200 return `result: null`; endpoints that normally return 204 continue to return 204.", "in": "query", "name": "dry_run", "schema": { "type": "boolean", "default": false } }, "secrets-store_account_id": { "description": "Account identifier.", "in": "path", "name": "account_id", "required": true, "schema": { "type": "string", "example": "985e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 } }, "secrets-store_direction": { "description": "Direction to sort objects.", "in": "query", "name": "direction", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, "secrets-store_force": { "description": "When true, cascade-deletes all secrets in the store before deleting the store itself.\nRequired when deleting a non-empty store. Without this parameter, attempting to\ndelete a non-empty store returns 409.\n", "in": "query", "name": "force", "schema": { "type": "boolean", "default": false } }, "secrets-store_order": { "description": "Order secrets by values in the given field.", "in": "query", "name": "order", "schema": { "type": "string", "default": "created", "enum": [ "name", "comment", "created", "modified", "status" ] } }, "secrets-store_page": { "description": "Page number.", "in": "query", "name": "page", "schema": { "type": "integer", "example": 2, "minimum": 0, "multipleOf": 1 } }, "secrets-store_per_page": { "description": "Number of objects to return per page.", "in": "query", "name": "per_page", "schema": { "type": "integer", "example": 20, "maximum": 100, "minimum": 0, "multipleOf": 1 } }, "secrets-store_scopes_query": { "description": "Only secrets with the given scopes will be returned.", "explode": false, "in": "query", "name": "scopes", "schema": { "type": "array", "items": { "enum": [ "workers", "ai_gateway", "dex", "access", "containers", "websearch" ], "type": "string" } }, "style": "form" }, "secrets-store_search": { "description": "Search secrets using a filter string, filtering across name and comment.", "in": "query", "name": "search", "schema": { "type": "string" } }, "secrets-store_secret_id": { "description": "Secret identifier.", "in": "path", "name": "secret_id", "required": true, "schema": { "type": "string", "example": "3fd85f74b32742f1bff64a85009dda07", "maxLength": 32 } }, "secrets-store_store_id": { "description": "Store identifier.", "in": "path", "name": "store_id", "required": true, "schema": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 } }, "secrets-store_store_order": { "description": "Order stores by values in the given field.", "in": "query", "name": "order", "schema": { "type": "string", "default": "created", "enum": [ "name", "created", "modified" ] } }, "security-center_auditLogBefore": { "description": "Filter entries changed before this timestamp (RFC 3339).", "in": "query", "name": "before", "schema": { "type": "string", "format": "date-time" } }, "security-center_auditLogChangedBy": { "description": "Filter by the actor that made the change.", "in": "query", "name": "changed_by", "schema": { "type": "string" } }, "security-center_auditLogCursor": { "description": "Opaque cursor for pagination. Use the cursor value from result_info of the previous response.", "in": "query", "name": "cursor", "schema": { "type": "string" } }, "security-center_auditLogFieldChanged": { "description": "Filter by the field that was changed.", "in": "query", "name": "field_changed", "schema": { "type": "string", "enum": [ "status", "user_classification" ] } }, "security-center_auditLogOrder": { "description": "Sort order for results. Use 'asc' for oldest first or 'desc' for newest first.", "in": "query", "name": "order", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, "security-center_auditLogPerPage": { "description": "Number of results per page.", "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 25, "maximum": 1000, "minimum": 1 } }, "security-center_auditLogSince": { "description": "Filter entries changed at or after this timestamp (RFC 3339).", "in": "query", "name": "since", "schema": { "type": "string", "format": "date-time" } }, "smartshield_page": { "description": "Page number of paginated results.", "in": "query", "name": "page", "schema": { "type": "number", "default": 1, "minimum": 1 } }, "smartshield_per_page": { "description": "Maximum number of results per page. Must be a multiple of 5.", "in": "query", "name": "per_page", "schema": { "type": "number", "default": 25, "maximum": 1000, "minimum": 5 } }, "teams-devices_devices_get_device_param_include": { "description": "Comma-separated list of additional information that should be included in the device response. Supported values are: \"last_seen_registration.policy\".\n", "in": "query", "name": "include", "schema": { "type": "string" } }, "teams-devices_devices_get_registration_param_include": { "description": "Comma-separated list of additional information that should be included in the registration response. Supported values are: \"policy\".\n", "in": "query", "name": "include", "schema": { "type": "string" } }, "teams-devices_devices_list_devices_param_active_registrations": { "description": "Include or exclude devices with active registrations. The default is \"only\" - return only devices with active registrations.", "explode": false, "in": "query", "name": "active_registrations", "schema": { "type": "string", "enum": [ "include", "only", "exclude" ] } }, "teams-devices_devices_list_devices_param_cursor": { "description": "Opaque token indicating the starting position when requesting the next set of records. A cursor value can be obtained from the result_info.cursor field in the response.", "explode": false, "in": "query", "name": "cursor", "schema": { "type": "string" } }, "teams-devices_devices_list_devices_param_id": { "description": "Filter by a one or more device IDs.", "explode": true, "in": "query", "name": "id", "schema": { "type": "array", "items": { "type": "string" } } }, "teams-devices_devices_list_devices_param_include": { "description": "Comma-separated list of additional information that should be included in the device response. Supported values are: \"last_seen_registration.policy\".\n", "in": "query", "name": "include", "schema": { "type": "string" } }, "teams-devices_devices_list_devices_param_last_seen_registration_policy_id": { "description": "Filter by the ID of the device settings profile assigned to the device registration.", "explode": false, "in": "query", "name": "last_seen_registration.policy.id", "schema": { "description": "The ID of the device settings profile.", "type": "string", "format": "uuid", "example": "11ffb86f-3f0c-4306-b4a2-e62f872b166a" } }, "teams-devices_devices_list_devices_param_last_seen_user_email": { "description": "Filter by the last seen user's email.", "explode": false, "in": "query", "name": "last_seen_user.email", "schema": { "type": "string" } }, "teams-devices_devices_list_devices_param_per_page": { "description": "The maximum number of devices to return in a single response.", "explode": false, "in": "query", "name": "per_page", "schema": { "type": "integer", "format": "uint64" } }, "teams-devices_devices_list_devices_param_search": { "description": "Search by device details.", "explode": false, "in": "query", "name": "search", "schema": { "type": "string" } }, "teams-devices_devices_list_devices_param_seen_after": { "description": "Filter by the last_seen timestamp - returns only devices last seen after this timestamp.", "explode": false, "in": "query", "name": "seen_after", "schema": { "type": "string" } }, "teams-devices_devices_list_devices_param_seen_before": { "description": "Filter by the last_seen timestamp - returns only devices last seen before this timestamp.", "explode": false, "in": "query", "name": "seen_before", "schema": { "type": "string" } }, "teams-devices_devices_list_devices_param_sort_by": { "description": "The device field to order results by.", "explode": false, "in": "query", "name": "sort_by", "schema": { "type": "string", "enum": [ "name", "id", "client_version", "last_seen_user.email", "last_seen_at", "active_registrations", "created_at" ] } }, "teams-devices_devices_list_devices_param_sort_order": { "description": "Sort direction.", "explode": false, "in": "query", "name": "sort_order", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, "teams-devices_devices_list_registrations_param_cursor": { "description": "Opaque token indicating the starting position when requesting the next set of records. A cursor value can be obtained from the result_info.cursor field in the response.", "explode": false, "in": "query", "name": "cursor", "schema": { "type": "string" } }, "teams-devices_devices_list_registrations_param_device_id": { "description": "Filter by WARP device ID.", "explode": false, "in": "query", "name": "device.id", "schema": { "type": "string" } }, "teams-devices_devices_list_registrations_param_id": { "description": "Filter by registration ID.", "explode": true, "in": "query", "name": "id", "schema": { "type": "array", "items": { "type": "string" } } }, "teams-devices_devices_list_registrations_param_include": { "description": "Comma-separated list of additional information that should be included in the registration response. Supported values are: \"policy\".\n", "in": "query", "name": "include", "schema": { "type": "string" } }, "teams-devices_devices_list_registrations_param_per_page": { "description": "The maximum number of devices to return in a single response.", "explode": false, "in": "query", "name": "per_page", "schema": { "type": "integer", "format": "uint64" } }, "teams-devices_devices_list_registrations_param_policy_id": { "description": "Filter by the ID of the device settings profile assigned to the registration.", "explode": false, "in": "query", "name": "policy.id", "schema": { "description": "The ID of the device settings profile.", "type": "string", "format": "uuid", "example": "11ffb86f-3f0c-4306-b4a2-e62f872b166a" } }, "teams-devices_devices_list_registrations_param_search": { "description": "Filter by registration details.", "explode": false, "in": "query", "name": "search", "schema": { "type": "string" } }, "teams-devices_devices_list_registrations_param_seen_after": { "description": "Filter by the last_seen timestamp - returns only registrations last seen after this timestamp.", "explode": false, "in": "query", "name": "seen_after", "schema": { "type": "string" } }, "teams-devices_devices_list_registrations_param_seen_before": { "description": "Filter by the last_seen timestamp - returns only registrations last seen before this timestamp.", "explode": false, "in": "query", "name": "seen_before", "schema": { "type": "string" } }, "teams-devices_devices_list_registrations_param_sort_by": { "description": "The registration field to order results by.", "explode": false, "in": "query", "name": "sort_by", "schema": { "type": "string", "enum": [ "id", "user.name", "user.email", "last_seen_at", "created_at" ] } }, "teams-devices_devices_list_registrations_param_sort_order": { "description": "Sort direction.", "explode": false, "in": "query", "name": "sort_order", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, "teams-devices_devices_list_registrations_param_status": { "description": "Filter by registration status. Defaults to 'active'.", "explode": false, "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "active", "all", "revoked" ] } }, "teams-devices_devices_list_registrations_param_user_id": { "description": "Filter by user ID.", "explode": true, "in": "query", "name": "user.id", "schema": { "type": "array", "items": { "type": "string" } } }, "usage-analytics_account_id": { "description": "Standard Cloudflare hex account identifier. The API gateway translates this to an internal numeric ID before forwarding to the backend service.\n", "in": "path", "name": "account_id", "required": true, "schema": { "$ref": "#/components/schemas/usage-analytics_identifier" } }, "usage-analytics_filters": { "description": "Filter expressions to apply to the query. Format: field==value. Multiple filters can be combined.\n", "in": "query", "name": "filters", "schema": { "type": "string", "example": "" } }, "usage-analytics_limit": { "description": "Maximum number of data points to return. The actual number of results depends on the interaction between the time range (since/until) and time_delta granularity. Results are truncated to this limit without error if the time range produces more data points than the limit allows.\n", "in": "query", "name": "limit", "schema": { "type": "integer", "example": 100, "default": 100, "maximum": 10000, "minimum": 1 } }, "usage-analytics_metrics": { "description": "Comma-separated list of metrics to include in the response. Available metrics depend on the endpoint. Billing usage supports: streamMinutesViewed, rateLimitingRequestsAllowed, loadBalancingQueries, argoAcceleratedBytes, workersRequests, workersKVReads, imageResizingRequests, spectrumBytesTransferred, mediaUniqueTransformations. Stream/media usage supports: streamMinutesViewed.\n", "in": "query", "name": "metrics", "schema": { "type": "string", "example": "streamMinutesViewed" } }, "usage-analytics_since": { "description": "Start of the time range for the query (inclusive). ISO 8601 timestamp. Defaults to 6 hours before the current time.\n", "in": "query", "name": "since", "schema": { "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" } }, "usage-analytics_time_delta": { "description": "Time unit to aggregate usage observations into. Data retention is approximately 18 months. The effective number of data points returned depends on the time range and granularity selected. For example, requesting hourly granularity over 18 months could produce up to ~13,000 data points; use the limit parameter to cap results and be aware that responses may be truncated.\n", "in": "query", "name": "time_delta", "schema": { "type": "string", "example": "hour", "default": "hour", "enum": [ "hour", "day", "week", "month", "quarter", "year" ] } }, "usage-analytics_until": { "description": "End of the time range for the query (inclusive). ISO 8601 timestamp. Defaults to the current time.\n", "in": "query", "name": "until", "schema": { "type": "string", "format": "date-time", "example": "2023-09-01T06:00:00Z" } }, "usage-analytics_zone_id": { "description": "Standard Cloudflare hex zone identifier. The API gateway resolves this to the owning account and translates it to an internal numeric ID before forwarding to the backend service.\n", "in": "path", "name": "zone_id", "required": true, "schema": { "$ref": "#/components/schemas/usage-analytics_identifier" } }, "vuln_scanner_account_id": { "description": "Account identifier.", "in": "path", "name": "account_id", "required": true, "schema": { "$ref": "#/components/schemas/vuln_scanner_identifier" } }, "vuln_scanner_credential_id": { "description": "Credential identifier.", "in": "path", "name": "credential_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, "vuln_scanner_credential_set_id": { "description": "Credential set identifier.", "in": "path", "name": "credential_set_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, "vuln_scanner_page": { "description": "Page number of paginated results.", "in": "query", "name": "page", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, "vuln_scanner_per_page": { "description": "Number of results per page.", "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 20, "maximum": 50, "minimum": 5 } }, "vuln_scanner_scan_id": { "description": "Scan identifier.", "in": "path", "name": "scan_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, "vuln_scanner_target_environment_id": { "description": "Target environment identifier.", "in": "path", "name": "target_environment_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, "waitingroom_page": { "description": "Page number of paginated results.", "in": "query", "name": "page", "schema": { "type": "number", "default": 1, "minimum": 1 } }, "waitingroom_per_page": { "description": "Maximum number of results per page. Must be a multiple of 5.", "in": "query", "name": "per_page", "schema": { "type": "number", "default": 25, "maximum": 1000, "minimum": 5 } } }, "schemas": { "aaa_account-id": { "description": "The account id", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "aaa_alert-types": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/aaa_description" }, "display_name": { "$ref": "#/components/schemas/aaa_display_name" }, "filter_options": { "$ref": "#/components/schemas/aaa_filter_options" }, "type": { "$ref": "#/components/schemas/aaa_type" } } }, "aaa_alert_body": { "description": "Message body included in the notification sent.", "type": "string", "example": "SSL certificate has expired" }, "aaa_alert_interval": { "description": "Optional specification of how often to re-alert from the same incident, not support on all alert types.", "type": "string", "example": "30m", "x-auditable": true }, "aaa_alert_type": { "description": "Refers to which event will trigger a Notification dispatch. You can use the endpoint to get available alert types which then will give you a list of possible values.", "type": "string", "example": "universal_ssl_event_type", "enum": [ "abuse_report_alert", "access_custom_certificate_expiration_type", "advanced_ddos_attack_l4_alert", "advanced_ddos_attack_l7_alert", "advanced_http_alert_error", "bgp_hijack_notification", "billing_usage_alert", "block_notification_block_removed", "block_notification_new_block", "block_notification_review_rejected", "bot_traffic_basic_alert", "brand_protection_alert", "brand_protection_digest", "clickhouse_alert_fw_anomaly", "clickhouse_alert_fw_ent_anomaly", "cloudforce_one_request_notification", "cni_maintenance_notification", "custom_analytics", "custom_bot_detection_alert", "custom_ssl_certificate_event_type", "dedicated_ssl_certificate_event_type", "device_connectivity_anomaly_alert", "dos_attack_l4", "dos_attack_l7", "expiring_service_token_alert", "failing_logpush_job_disabled_alert", "fbm_auto_advertisement", "fbm_dosd_attack", "fbm_volumetric_attack", "health_check_status_notification", "hostname_aop_custom_certificate_expiration_type", "http_alert_edge_error", "http_alert_origin_error", "image_notification", "image_resizing_notification", "incident_alert", "load_balancing_health_alert", "load_balancing_pool_enablement_alert", "logo_match_alert", "magic_tunnel_health_check_event", "magic_wan_tunnel_health", "maintenance_event_notification", "mtls_certificate_store_certificate_expiration_type", "pages_event_alert", "radar_notification", "real_origin_monitoring", "scriptmonitor_alert_new_code_change_detections", "scriptmonitor_alert_new_hosts", "scriptmonitor_alert_new_malicious_hosts", "scriptmonitor_alert_new_malicious_scripts", "scriptmonitor_alert_new_malicious_url", "scriptmonitor_alert_new_max_length_resource_url", "scriptmonitor_alert_new_resources", "secondary_dns_all_primaries_failing", "secondary_dns_primaries_failing", "secondary_dns_warning", "secondary_dns_zone_successfully_updated", "secondary_dns_zone_validation_warning", "security_insights_alert", "sentinel_alert", "stream_live_notifications", "synthetic_test_latency_alert", "synthetic_test_low_availability_alert", "traffic_anomalies_alert", "tunnel_health_event", "tunnel_update_event", "universal_ssl_event_type", "web_analytics_metrics_update", "zone_aop_custom_certificate_expiration_type" ], "x-auditable": true }, "aaa_alerts-response_collection": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-common-2" }, { "properties": { "result": { "type": "object", "example": { "Origin Monitoring": [ { "description": "High levels of 5xx HTTP errors at your origin.", "display_name": "Origin Error Rate Alert", "filter_options": [ { "AvailableValues": null, "ComparisonOperator": "==", "Key": "zones", "Range": "1-n" }, { "AvailableValues": [ { "Description": "Service-Level Objective of 99.7", "ID": "99.7" }, { "Description": "Service-Level Objective of 99.8", "ID": "99.8" } ], "ComparisonOperator": ">=", "Key": "slo", "Range": "0-1" } ], "type": "http_alert_origin_error" } ] }, "additionalProperties": { "items": { "$ref": "#/components/schemas/aaa_alert-types" }, "type": "array" } } } } ] }, "aaa_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-common-2" }, { "properties": { "result_info": { "$ref": "#/components/schemas/aaa_result_info-2" } } } ] }, "aaa_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/aaa_messages" }, "messages": { "$ref": "#/components/schemas/aaa_messages" }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "aaa_api-response-common-2": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/aaa_messages-3" }, "messages": { "$ref": "#/components/schemas/aaa_messages-3" }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "aaa_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/aaa_messages" } ], "minLength": 1 }, "messages": { "$ref": "#/components/schemas/aaa_messages" }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages" ] }, "aaa_api-response-common-failure-2": { "type": "object", "properties": { "errors": { "description": "A list of error messages.", "type": "array", "items": { "properties": { "message": { "description": "A text description of this message.", "type": "string", "example": "No route for the URI" } }, "required": [ "message" ], "type": "object", "uniqueItems": true } }, "messages": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "type": "object", "uniqueItems": true }, "example": [] }, "success": { "description": "Indicates whether the API call was failed", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors" ] }, "aaa_api-response-common-failure-3": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/aaa_messages-3" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/aaa_messages-3" } ] }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages" ] }, "aaa_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-common-2" } ] }, "aaa_audit-log-action": { "description": "Provides information about the action performed.", "type": "object", "properties": { "description": { "description": "A short description of the action performed.", "type": "string", "example": "Add Member" }, "result": { "description": "The result of the action, indicating success or failure.", "type": "string", "example": "success" }, "time": { "description": "A timestamp indicating when the action was logged.", "type": "string", "format": "date-time", "example": "2024-04-26T17:31:07Z" }, "type": { "description": "A short string that describes the action that was performed.", "type": "string", "example": "create" } } }, "aaa_audit-log-actor-base": { "description": "Provides details about the actor who performed the action.", "type": "object", "properties": { "context": { "description": "The context in which the action was initiated.\n- `api`: The action was performed through the API. The specific credential type was not recorded.\n- `api_key`: The action was authenticated with a Cloudflare Global API Key.\n- `api_token`: The action was authenticated with an API token.\n- `dash`: The action was performed through the Cloudflare dashboard.\n- `oauth`: The action was authenticated with an OAuth token.\n- `origin_ca_key`: The action was authenticated with an Origin CA key.\n", "type": "string", "example": "dash", "enum": [ "api", "api_key", "api_token", "dash", "oauth", "origin_ca_key" ] }, "email": { "description": "The email of the actor who performed the action.", "type": "string", "format": "email", "example": "alice@example.com" }, "id": { "description": "The ID of the actor who performed the action. If a user performed the action, this will be their User ID.", "type": "string", "example": "f6b5de0326bb5182b8a4840ee01ec774" }, "ip_address": { "description": "The IP address of the request that performed the action.", "type": "string", "example": "198.41.129.166" }, "token_id": { "description": "The API token ID when the actor context is an api_token or oauth.", "type": "string" }, "token_name": { "description": "The API token name when the actor context is an api_token or oauth.", "type": "string" } } }, "aaa_audit-log-raw": { "description": "Provides raw information about the request and response.", "type": "object", "properties": { "cf_ray_id": { "description": "The Cloudflare Ray ID for the request.", "type": "string", "example": "8e9b1c60ef9e1c9a" }, "method": { "description": "The HTTP method of the request.", "type": "string", "example": "POST" }, "status_code": { "description": "The HTTP response status code returned by the API.", "type": "integer", "example": 200 }, "uri": { "description": "The URI of the request.", "type": "string", "example": "/accounts/4bb334f7c94c4a29a045f03944f072e5/members" }, "user_agent": { "description": "The client's user agent string sent with the request.", "type": "string", "example": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Safari/605.1.15" } } }, "aaa_audit-logs": { "type": "object", "properties": { "action": { "type": "object", "properties": { "result": { "description": "A boolean that indicates if the action attempted was successful.", "type": "boolean", "example": true }, "type": { "description": "A short string that describes the action that was performed.", "type": "string", "example": "change_setting" } } }, "actor": { "type": "object", "properties": { "email": { "description": "The email of the user that performed the action.", "type": "string", "format": "email", "example": "michelle@example.com" }, "id": { "description": "The ID of the actor that performed the action. If a user performed the action, this will be their User ID.", "type": "string", "example": "f6b5de0326bb5182b8a4840ee01ec774" }, "ip": { "description": "The IP address of the request that performed the action.", "type": "string", "example": "198.41.129.166" }, "type": { "description": "The type of actor, whether a User, Cloudflare Admin, or an Automated System.", "type": "string", "example": "user", "enum": [ "user", "admin", "Cloudflare" ] } } }, "id": { "description": "A string that uniquely identifies the audit log.", "type": "string", "example": "d5b0f326-1232-4452-8858-1089bd7168ef" }, "interface": { "description": "The source of the event.", "type": "string", "example": "API" }, "metadata": { "description": "An object which can lend more context to the action being logged. This is a flexible value and varies between different actions.", "type": "object", "example": { "name": "security_level", "type": "firewall", "value": "high", "zone_name": "example.com" } }, "newValue": { "description": "The new value of the resource that was modified.", "type": "string", "example": "low" }, "oldValue": { "description": "The value of the resource before it was modified.", "type": "string", "example": "high" }, "owner": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/aaa_identifier" } } }, "resource": { "type": "object", "properties": { "id": { "description": "An identifier for the resource that was affected by the action.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" }, "type": { "description": "A short string that describes the resource that was affected by the action.", "type": "string", "example": "zone" } } }, "when": { "description": "A UTC RFC3339 timestamp that specifies when the action being logged occured.", "type": "string", "format": "date-time", "example": "2017-04-26T17:31:07Z" } } }, "aaa_audit-logs-response-collection": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/aaa_messages-2" }, "result_info": { "$ref": "#/components/schemas/aaa_result_info" }, "success": { "description": "Indicates whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } } }, "aaa_audit-logs-v2": { "type": "object", "properties": { "account": { "description": "Contains account related information.", "type": "object", "properties": { "id": { "description": "A unique identifier for the account.", "type": "string", "example": "4bb334f7c94c4a29a045f03944f072e5" }, "name": { "description": "A string that identifies the account name.", "type": "string", "example": "Example Account" } } }, "action": { "$ref": "#/components/schemas/aaa_audit-log-action" }, "actor": { "allOf": [ { "$ref": "#/components/schemas/aaa_audit-log-actor-base" }, { "properties": { "type": { "description": "The type of actor.", "type": "string", "example": "user", "enum": [ "account", "cloudflare_admin", "delegated_service", "system", "user" ] } }, "type": "object" } ] }, "id": { "$ref": "#/components/schemas/aaa_identifier-2" }, "raw": { "$ref": "#/components/schemas/aaa_audit-log-raw" }, "resource": { "description": "Provides details about the affected resource.", "type": "object", "properties": { "id": { "description": "The unique identifier for the affected resource.", "type": "string" }, "product": { "description": "The Cloudflare product associated with the resource.", "type": "string", "example": "members" }, "request": { "type": "object" }, "response": { "type": "object" }, "scope": { "description": "The scope of the resource.", "type": "object", "example": "accounts" }, "type": { "description": "The type of the resource.", "type": "string" } } }, "zone": { "description": "Provides details about the zone affected by the action.", "type": "object", "properties": { "id": { "description": "A string that identifies the zone id.", "type": "string" }, "name": { "description": "A string that identifies the zone name.", "type": "string", "example": "example.com" } } } } }, "aaa_audit-logs-v2-history-not-found": { "description": "Returned when the source audit log entry referenced by `id` cannot be found within the `action_time` window. The `result_info.history_status` is always set to `unavailable` for this response.", "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/aaa_messages-2" }, "result": { "type": "object", "nullable": true }, "result_info": { "$ref": "#/components/schemas/aaa_audit-logs-v2-history-result-info" }, "success": { "description": "Indicates whether the API call was successful", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "result_info" ] }, "aaa_audit-logs-v2-history-response-collection": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/aaa_messages-2" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/aaa_audit-logs-v2" } }, "result_info": { "$ref": "#/components/schemas/aaa_audit-logs-v2-history-result-info" }, "success": { "description": "Indicates whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "result", "result_info" ] }, "aaa_audit-logs-v2-history-result-info": { "description": "Provides information about the result of the request, including count, cursor, and identification quality.", "type": "object", "properties": { "count": { "description": "The number of records returned in the response.", "type": "integer", "example": 1 }, "cursor": { "description": "The cursor token used for pagination.", "type": "string", "example": "ASqdKd7dKgxh-aZ8bm0mZos1BtW4BdEqifCzNkEeGRzi_5SN_-362Y8sF-C1TRn60_6rd3z2dIajf9EAPyQ_NmIeAMkacmaJPXipqvP7PLU4t72wyqBeJfjmjdE=" }, "history_status": { "$ref": "#/components/schemas/aaa_history-status" } }, "required": [ "count", "history_status" ] }, "aaa_audit-logs-v2-org": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/aaa_audit-log-action" }, "actor": { "allOf": [ { "$ref": "#/components/schemas/aaa_audit-log-actor-base" }, { "properties": { "type": { "description": "The type of actor.", "type": "string", "example": "user", "enum": [ "cloudflare_admin", "system", "user" ] } }, "type": "object" } ] }, "id": { "$ref": "#/components/schemas/aaa_identifier-2" }, "organization": { "description": "Contains organization related information.", "type": "object", "properties": { "id": { "description": "A unique identifier for the organization.", "type": "string", "example": "019c4f65e7607d8c9f6f6b58aa3aff50" } } }, "raw": { "$ref": "#/components/schemas/aaa_audit-log-raw" }, "resource": { "description": "Provides details about the affected resource.", "type": "object", "properties": { "id": { "description": "The unique identifier for the affected resource.", "type": "string" }, "product": { "description": "The Cloudflare product associated with the resource.", "type": "string", "example": "organizations" }, "request": { "type": "object" }, "response": { "type": "object" }, "scope": { "description": "The scope of the resource.", "type": "object", "example": "organizations" }, "type": { "description": "The type of the resource.", "type": "string" } } } } }, "aaa_audit-logs-v2-org-history-response-collection": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/aaa_messages-2" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/aaa_audit-logs-v2-org" } }, "result_info": { "$ref": "#/components/schemas/aaa_audit-logs-v2-history-result-info" }, "success": { "description": "Indicates whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "result", "result_info" ] }, "aaa_audit-logs-v2-org-response-collection": { "allOf": [ { "$ref": "#/components/schemas/aaa_audit-logs-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/aaa_audit-logs-v2-org" } } }, "type": "object" } ] }, "aaa_audit-logs-v2-product-categories-response-collection": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/aaa_messages-2" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/aaa_audit-logs-v2-product-category" } }, "success": { "description": "Indicates whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } } }, "aaa_audit-logs-v2-product-category": { "description": "A predefined product category and the resource products it expands to.", "type": "object", "properties": { "label": { "description": "A human-readable label for the product category.", "type": "string", "example": "Zero Trust" }, "products": { "description": "The resource products that the product category expands to.", "type": "array", "items": { "$ref": "#/components/schemas/aaa_audit-logs-v2-product-category-item" } }, "value": { "description": "The product category identifier used with the product_category filter.", "type": "string", "example": "zerotrust" } } }, "aaa_audit-logs-v2-product-category-item": { "description": "A resource product within a product category.", "type": "object", "properties": { "label": { "description": "A human-readable label for the product.", "type": "string", "example": "Gateway" }, "value": { "description": "The resource_product value that the product category expands to.", "type": "string", "example": "gateway" } } }, "aaa_audit-logs-v2-response-collection": { "allOf": [ { "$ref": "#/components/schemas/aaa_audit-logs-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/aaa_audit-logs-v2" } } }, "type": "object" } ] }, "aaa_audit_logs_response_collection": { "oneOf": [ { "properties": { "errors": { "$ref": "#/components/schemas/aaa_messages" }, "messages": { "$ref": "#/components/schemas/aaa_messages" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/aaa_audit-logs" } }, "success": { "type": "boolean", "example": true } } }, { "$ref": "#/components/schemas/aaa_api-response-common" } ] }, "aaa_before": { "description": "Limit the returned results to history records older than the specified date. This must be a timestamp that conforms to RFC3339.", "type": "string", "format": "date-time", "example": "2022-05-20T20:29:58.679897Z" }, "aaa_components-schemas-description": { "description": "Description of the notification policy (if present).", "type": "string", "example": "Universal Certificate validation status, issuance, renewal, and expiration notices" }, "aaa_components-schemas-name": { "description": "The name of the webhook destination. This will be included in the request body when you receive a webhook notification.", "type": "string", "example": "Slack Webhook", "x-auditable": true }, "aaa_components-schemas-response_collection": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-common-2" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/aaa_pagerduty" } } } } ] }, "aaa_components-schemas-type": { "description": "Type of webhook endpoint.", "type": "string", "example": "slack", "enum": [ "datadog", "discord", "feishu", "gchat", "generic", "opsgenie", "slack", "splunk" ], "x-auditable": true }, "aaa_created_at": { "description": "Timestamp of when the webhook destination was created.", "type": "string", "format": "date-time", "example": "2020-10-26T18:25:04.532316Z", "readOnly": true, "x-auditable": true }, "aaa_description": { "description": "Describes the alert type.", "type": "string", "example": "High levels of 5xx HTTP errors at your origin", "x-auditable": true }, "aaa_display_name": { "description": "Alert type name.", "type": "string", "example": "Origin Error Rate Alert", "x-auditable": true }, "aaa_eligibility": { "type": "object", "properties": { "eligible": { "$ref": "#/components/schemas/aaa_eligible" }, "ready": { "$ref": "#/components/schemas/aaa_ready" }, "type": { "$ref": "#/components/schemas/aaa_schemas-type" } } }, "aaa_eligible": { "description": "Determines whether or not the account is eligible for the delivery mechanism.", "type": "boolean", "example": true, "x-auditable": true }, "aaa_enabled": { "description": "Whether or not the Notification policy is enabled.", "type": "boolean", "example": true, "default": true, "x-auditable": true }, "aaa_filter_options": { "description": "Format of additional configuration options (filters) for the alert type. Data type of filters during policy creation: Array of strings.", "type": "array", "items": {}, "example": [ { "AvailableValues": null, "ComparisonOperator": "==", "Key": "zones", "Range": "1-n" }, { "AvailableValues": [ { "Description": "Service-Level Objective of 99.7", "ID": "99.7" }, { "Description": "Service-Level Objective of 99.8", "ID": "99.8" } ], "ComparisonOperator": ">=", "Key": "slo", "Range": "0-1" } ] }, "aaa_filters": { "description": "Optional filters that allow you to be alerted only on a subset of events for that alert type based on some criteria. This is only available for select alert types. See alert type documentation for more details.", "type": "object", "properties": { "actions": { "description": "Usage depends on specific alert type", "type": "array", "items": { "type": "string", "x-auditable": true } }, "affected_asns": { "description": "Used for configuring radar_notification", "type": "array", "items": { "type": "string", "x-auditable": true } }, "affected_components": { "description": "Used for configuring incident_alert", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": "4c231tkdlpcl" }, "affected_locations": { "description": "Used for configuring radar_notification", "type": "array", "items": { "type": "string", "x-auditable": true } }, "airport_code": { "description": "Used for configuring maintenance_event_notification", "type": "array", "items": { "type": "string", "x-auditable": true } }, "alert_trigger_preferences": { "description": "Usage depends on specific alert type", "type": "array", "items": { "type": "string", "x-auditable": true } }, "alert_trigger_preferences_value": { "description": "Usage depends on specific alert type", "type": "array", "items": { "type": "string", "x-auditable": true } }, "enabled": { "description": "Used for configuring load_balancing_pool_enablement_alert", "type": "array", "items": { "minItems": 1, "type": "string", "x-auditable": true } }, "environment": { "description": "Used for configuring pages_event_alert", "type": "array", "items": { "minItems": 1, "type": "string", "x-auditable": true } }, "event": { "description": "Used for configuring pages_event_alert", "type": "array", "items": { "minItems": 1, "type": "string", "x-auditable": true } }, "event_source": { "description": "Used for configuring load_balancing_health_alert", "type": "array", "items": { "type": "string", "x-auditable": true } }, "event_type": { "description": "Usage depends on specific alert type", "type": "array", "items": { "type": "string", "x-auditable": true } }, "group_by": { "description": "Usage depends on specific alert type", "type": "array", "items": { "type": "string", "x-auditable": true } }, "health_check_id": { "description": "Used for configuring health_check_status_notification", "type": "array", "items": { "type": "string", "x-auditable": true } }, "incident_impact": { "description": "Used for configuring incident_alert", "type": "array", "items": { "enum": [ "INCIDENT_IMPACT_NONE", "INCIDENT_IMPACT_MINOR", "INCIDENT_IMPACT_MAJOR", "INCIDENT_IMPACT_CRITICAL" ], "type": "string", "x-auditable": true } }, "input_id": { "description": "Used for configuring stream_live_notifications", "type": "array", "items": { "type": "string", "x-auditable": true } }, "insight_class": { "description": "Used for configuring security_insights_alert", "type": "array", "items": { "type": "string", "x-auditable": true } }, "limit": { "description": "Used for configuring billing_usage_alert", "type": "array", "items": { "minItems": 1, "type": "string", "x-auditable": true } }, "logo_tag": { "description": "Used for configuring logo_match_alert", "type": "array", "items": { "type": "string", "x-auditable": true } }, "megabits_per_second": { "description": "Used for configuring advanced_ddos_attack_l4_alert", "type": "array", "items": { "type": "string", "x-auditable": true } }, "new_health": { "description": "Used for configuring load_balancing_health_alert", "type": "array", "items": { "type": "string", "x-auditable": true } }, "new_status": { "description": "Used for configuring tunnel_health_event", "type": "array", "items": { "type": "string", "x-auditable": true } }, "packets_per_second": { "description": "Used for configuring advanced_ddos_attack_l4_alert", "type": "array", "items": { "type": "string", "x-auditable": true } }, "pool_id": { "description": "Usage depends on specific alert type", "type": "array", "items": { "type": "string", "x-auditable": true } }, "pop_names": { "description": "Usage depends on specific alert type", "type": "array", "items": { "type": "string", "x-auditable": true } }, "product": { "description": "Used for configuring billing_usage_alert", "type": "array", "items": { "minItems": 1, "type": "string", "x-auditable": true } }, "project_id": { "description": "Used for configuring pages_event_alert", "type": "array", "items": { "minItems": 1, "type": "string", "x-auditable": true } }, "protocol": { "description": "Used for configuring advanced_ddos_attack_l4_alert", "type": "array", "items": { "type": "string", "x-auditable": true } }, "query_tag": { "description": "Usage depends on specific alert type", "type": "array", "items": { "type": "string", "x-auditable": true } }, "requests_per_second": { "description": "Used for configuring advanced_ddos_attack_l7_alert", "type": "array", "items": { "type": "string", "x-auditable": true } }, "selectors": { "description": "Usage depends on specific alert type", "type": "array", "items": { "type": "string", "x-auditable": true } }, "services": { "description": "Used for configuring clickhouse_alert_fw_ent_anomaly", "type": "array", "items": { "minItems": 1, "type": "string", "x-auditable": true } }, "slo": { "description": "Usage depends on specific alert type", "type": "array", "items": { "type": "string", "x-auditable": true } }, "status": { "description": "Used for configuring health_check_status_notification", "type": "array", "items": { "minItems": 1, "type": "string", "x-auditable": true } }, "target_hostname": { "description": "Used for configuring advanced_ddos_attack_l7_alert", "type": "array", "items": { "type": "string", "x-auditable": true } }, "target_ip": { "description": "Used for configuring advanced_ddos_attack_l4_alert", "type": "array", "items": { "type": "string", "x-auditable": true } }, "target_zone_name": { "description": "Used for configuring advanced_ddos_attack_l7_alert", "type": "array", "items": { "type": "string", "x-auditable": true } }, "traffic_exclusions": { "description": "Used for configuring traffic_anomalies_alert", "type": "array", "items": { "enum": [ "security_events" ], "maxItems": 1, "type": "string", "x-auditable": true } }, "tunnel_id": { "description": "Used for configuring tunnel_health_event", "type": "array", "items": { "type": "string", "x-auditable": true } }, "tunnel_name": { "description": "Usage depends on specific alert type", "type": "array", "items": { "type": "string", "x-auditable": true } }, "type": { "description": "Usage depends on specific alert type", "type": "array", "items": { "type": "string", "x-auditable": true } }, "where": { "description": "Usage depends on specific alert type", "type": "array", "items": { "type": "string", "x-auditable": true } }, "zones": { "description": "Usage depends on specific alert type", "type": "array", "items": { "type": "string", "x-auditable": true } } }, "example": { "slo": [ "99.9" ] } }, "aaa_history": { "type": "object", "properties": { "alert_body": { "$ref": "#/components/schemas/aaa_alert_body" }, "alert_type": { "$ref": "#/components/schemas/aaa_schemas-alert_type" }, "description": { "$ref": "#/components/schemas/aaa_components-schemas-description" }, "id": { "$ref": "#/components/schemas/aaa_uuid" }, "mechanism": { "$ref": "#/components/schemas/aaa_mechanism" }, "mechanism_type": { "$ref": "#/components/schemas/aaa_mechanism_type" }, "name": { "$ref": "#/components/schemas/aaa_schemas-name" }, "policy_id": { "$ref": "#/components/schemas/aaa_policy-id" }, "sent": { "$ref": "#/components/schemas/aaa_sent" } } }, "aaa_history-status": { "description": "Indicates the quality of the resource identification used to derive the history.\n- `exact`: Resource was identified by the resource URI.\n- `approximate`: Resource was identified without the resource URI.\n- `unavailable`: The source audit log entry did not contain enough information to identify the resource; result is empty.\n", "type": "string", "example": "exact", "enum": [ "exact", "approximate", "unavailable" ] }, "aaa_history_components-schemas-response_collection": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/aaa_history" }, "example": [ { "alert_body": { "data": { "custom_csr_id": "", "expires_on": null, "hosts": [], "id": "11111111111", "issuer": "", "method": "txt", "serial_number": "", "settings": null, "signature": "", "status": "", "type": "", "uploaded_on": null, "validation_errors": [], "validation_records": [ { "cname": "", "cname_target": "", "emails": [], "http_body": "", "http_url": "", "txt_name": "_acme-challenge.example.com", "txt_value": "11111111111" } ] }, "metadata": { "account": null, "event": { "created_at": null, "id": "", "type": "ssl.certificate.validation.failed" }, "zone": { "id": "11111111111" } } }, "alert_type": "universal_ssl_event_type", "description": "Universal Certificate validation status, issuance, renewal, and expiration notices.", "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "mechanism": "test@example.com", "mechanism_type": "email", "name": "SSL Notification Event Policy", "policy_id": "35040955-3102-4710-938c-0f4eaf736e25", "sent": "2021-10-08T17:52:17.571336Z" } ] }, "result_info": { "type": "object", "example": { "count": 1, "page": 1, "per_page": 20 } } } } ] }, "aaa_id_response": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/aaa_uuid" } } } } } ] }, "aaa_identifier": { "description": "Identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "aaa_identifier-2": { "description": "A unique identifier for the audit log entry.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "aaa_integration-token": { "description": "The token integration key", "type": "string", "example": "8c71e667571b4f61b94d9e4b12158038", "maxLength": 32, "readOnly": true }, "aaa_last_failure": { "description": "Timestamp of the last time an attempt to dispatch a notification to this webhook failed.", "type": "string", "format": "date-time", "example": "2020-10-26T18:25:04.532316Z", "readOnly": true, "x-auditable": true }, "aaa_last_success": { "description": "Timestamp of the last time Cloudflare was able to successfully dispatch a notification using this webhook.", "type": "string", "format": "date-time", "example": "2020-10-26T18:25:04.532316Z", "readOnly": true, "x-auditable": true }, "aaa_mechanism": { "description": "The mechanism to which the notification has been dispatched.", "type": "string", "example": "test@example.com", "x-auditable": true }, "aaa_mechanism_type": { "description": "The type of mechanism to which the notification has been dispatched. This can be email/pagerduty/webhook based on the mechanism configured.", "type": "string", "example": "email", "enum": [ "email", "pagerduty", "webhook" ] }, "aaa_mechanisms": { "description": "List of IDs that will be used when dispatching a notification. IDs for email type will be the email address.", "type": "object", "properties": { "email": { "type": "array", "items": { "properties": { "id": { "description": "The email address", "type": "string", "x-auditable": true } }, "type": "object" } }, "pagerduty": { "type": "array", "items": { "properties": { "id": { "$ref": "#/components/schemas/aaa_uuid" } }, "type": "object" } }, "webhooks": { "type": "array", "items": { "properties": { "id": { "$ref": "#/components/schemas/aaa_uuid" } }, "type": "object" } } }, "example": { "email": [ { "id": "test@example.com" } ], "pagerduty": [ { "id": "e8133a15-00a4-4d69-aec1-32f70c51f6e5" } ], "webhooks": [ { "id": "14cc1190-5d2b-4b98-a696-c424cb2ad05f" } ] } }, "aaa_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "aaa_messages-2": { "type": "array", "items": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "aaa_messages-3": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "aaa_name": { "description": "The name of the pagerduty service.", "type": "string", "example": "My PagerDuty Service", "x-auditable": true }, "aaa_pagerduty": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/aaa_uuid" }, "name": { "$ref": "#/components/schemas/aaa_name" } } }, "aaa_per_page": { "description": "Number of items per page.", "type": "number", "default": 25, "maximum": 1000, "minimum": 5 }, "aaa_policies": { "type": "object", "properties": { "alert_interval": { "$ref": "#/components/schemas/aaa_alert_interval" }, "alert_type": { "$ref": "#/components/schemas/aaa_alert_type" }, "created": { "$ref": "#/components/schemas/aaa_timestamp" }, "description": { "$ref": "#/components/schemas/aaa_schemas-description" }, "enabled": { "$ref": "#/components/schemas/aaa_enabled" }, "filters": { "$ref": "#/components/schemas/aaa_filters" }, "id": { "$ref": "#/components/schemas/aaa_policy-id" }, "mechanisms": { "$ref": "#/components/schemas/aaa_mechanisms" }, "modified": { "$ref": "#/components/schemas/aaa_timestamp" }, "name": { "$ref": "#/components/schemas/aaa_schemas-name" } } }, "aaa_policies_components-schemas-response_collection": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-common-2" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/aaa_policies" } } } } ] }, "aaa_policy-id": { "description": "The unique identifier of a notification policy", "type": "string", "example": "0da2b59ef118439d8097bdfb215203c9", "maxLength": 32, "x-auditable": true }, "aaa_ready": { "description": "Beta flag. Users can create a policy with a mechanism that is not ready, but we cannot guarantee successful delivery of notifications.", "type": "boolean", "example": true, "x-auditable": true }, "aaa_result_info": { "description": "Provides information about the result of the request, including count and cursor.", "type": "object", "properties": { "count": { "description": "The number of records returned in the response.", "type": "string", "example": 1 }, "cursor": { "description": "The cursor token used for pagination.", "type": "string", "example": "ASqdKd7dKgxh-aZ8bm0mZos1BtW4BdEqifCzNkEeGRzi_5SN_-362Y8sF-C1TRn60_6rd3z2dIajf9EAPyQ_NmIeAMkacmaJPXipqvP7PLU4t72wyqBeJfjmjdE=" } } }, "aaa_result_info-2": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters", "type": "number", "example": 2000 } } }, "aaa_schemas-alert_type": { "description": "Type of notification that has been dispatched.", "type": "string", "example": "universal_ssl_event_type" }, "aaa_schemas-description": { "description": "Optional description for the Notification policy.", "type": "string", "example": "Something describing the policy.", "x-auditable": true }, "aaa_schemas-name": { "description": "Name of the policy.", "type": "string", "example": "SSL Notification Event Policy", "x-auditable": true }, "aaa_schemas-response_collection": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-common-2" }, { "properties": { "result": { "type": "object", "example": { "email": { "eligible": true, "ready": true, "type": "email" } }, "additionalProperties": { "items": { "$ref": "#/components/schemas/aaa_eligibility" }, "type": "array" } } } } ] }, "aaa_schemas-single_response": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/aaa_webhooks" } } } ] }, "aaa_schemas-type": { "description": "Determines type of delivery mechanism.", "type": "string", "example": "email", "enum": [ "email", "pagerduty", "webhook" ], "x-auditable": true }, "aaa_secret": { "description": "Optional secret that will be passed in the `cf-webhook-auth` header when dispatching generic webhook notifications or formatted for supported destinations. Secrets are not returned in any API response body.", "type": "string", "writeOnly": true, "x-sensitive": true }, "aaa_sensitive_id_response": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/aaa_token" } } } } } ] }, "aaa_sent": { "description": "Timestamp of when the notification was dispatched in ISO 8601 format.", "type": "string", "format": "date-time", "example": "2021-10-08T17:52:17.571336Z" }, "aaa_silence": { "type": "object", "properties": { "created_at": { "description": "When the silence was created.", "type": "string", "example": "2022-01-01T00:00:00Z", "x-auditable": true }, "end_time": { "description": "When the silence ends.", "type": "string", "example": "2022-01-01T00:00:00Z", "x-auditable": true }, "id": { "$ref": "#/components/schemas/aaa_silence-id" }, "policy_id": { "$ref": "#/components/schemas/aaa_policy-id" }, "start_time": { "description": "When the silence starts.", "type": "string", "example": "2022-01-01T00:00:00Z", "x-auditable": true }, "updated_at": { "description": "When the silence was modified.", "type": "string", "example": "2022-01-01T00:00:00Z", "x-auditable": true } } }, "aaa_silence-id": { "description": "Silence ID", "type": "string", "example": "f878e90c23f44126ae3cfc399f646977", "maxLength": 32, "x-auditable": true }, "aaa_silence_components-schemas-response_collection": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-common-2" }, { "properties": { "result": { "$ref": "#/components/schemas/aaa_silence" } } } ] }, "aaa_silence_create_request": { "type": "object", "properties": { "end_time": { "description": "When the silence ends.", "type": "string", "example": "2022-01-01T00:00:00Z", "x-auditable": true }, "policy_id": { "$ref": "#/components/schemas/aaa_policy-id" }, "start_time": { "description": "When the silence starts.", "type": "string", "example": "2022-01-01T00:00:00Z", "x-auditable": true } } }, "aaa_silence_update_request": { "type": "object", "properties": { "end_time": { "description": "When the silence ends.", "type": "string", "example": "2022-01-01T00:00:00Z", "x-auditable": true }, "id": { "$ref": "#/components/schemas/aaa_silence-id" }, "start_time": { "description": "When the silence starts.", "type": "string", "example": "2022-01-01T00:00:00Z", "x-auditable": true } } }, "aaa_silences_components-schemas-response_collection": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-common-2" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/aaa_silence" } } } } ] }, "aaa_single_response": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/aaa_policies" } } } ] }, "aaa_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true, "x-auditable": true }, "aaa_token": { "description": "token in form of UUID", "type": "string", "example": "a313ba7d3e464c0ea40808fafbc3816a", "maxLength": 32, "x-sensitive": true }, "aaa_type": { "description": "Use this value when creating and updating a notification policy.", "type": "string", "example": "http_alert_origin_error", "x-auditable": true }, "aaa_unsubscribe_email": { "description": "Response body for the GET show-unsubscribe-details endpoint. All fields are populated.", "type": "object", "properties": { "account_id": { "$ref": "#/components/schemas/aaa_account-id" }, "email": { "type": "string", "format": "email" }, "id": { "$ref": "#/components/schemas/aaa_policy-id" }, "name": { "$ref": "#/components/schemas/aaa_schemas-name" }, "token": { "type": "string", "x-sensitive": true } } }, "aaa_unsubscribe_email_post": { "description": "Response body for the POST unsubscribe endpoint. name and token are not returned.", "type": "object", "properties": { "account_id": { "$ref": "#/components/schemas/aaa_account-id" }, "email": { "type": "string", "format": "email" }, "id": { "$ref": "#/components/schemas/aaa_policy-id" } } }, "aaa_unsubscribe_email_post_single_response": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/aaa_unsubscribe_email_post" } } } ] }, "aaa_unsubscribe_email_single_response": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/aaa_unsubscribe_email" } } } ] }, "aaa_url": { "description": "The POST endpoint to call when dispatching a notification.", "type": "string", "example": "https://hooks.slack.com/services/Ds3fdBFbV/456464Gdd" }, "aaa_uuid": { "description": "UUID", "type": "string", "example": "f174e90afafe4643bbbc4a0ed4fc8415", "maxLength": 32, "x-auditable": true }, "aaa_webhook-id": { "description": "The unique identifier of a webhook", "type": "string", "example": "b115d5ec15c641ee8b7692c449b5227b", "maxLength": 32, "x-auditable": true }, "aaa_webhooks": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/aaa_created_at" }, "id": { "$ref": "#/components/schemas/aaa_webhook-id" }, "last_failure": { "$ref": "#/components/schemas/aaa_last_failure" }, "last_success": { "$ref": "#/components/schemas/aaa_last_success" }, "name": { "$ref": "#/components/schemas/aaa_components-schemas-name" }, "secret": { "$ref": "#/components/schemas/aaa_secret" }, "type": { "$ref": "#/components/schemas/aaa_components-schemas-type" }, "url": { "$ref": "#/components/schemas/aaa_url" } } }, "aaa_webhooks_components-schemas-response_collection": { "allOf": [ { "$ref": "#/components/schemas/aaa_api-response-common-2" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/aaa_webhooks" } } } } ] }, "abuse-reports_AbuseReport": { "type": "object", "properties": { "cdate": { "description": "Creation date of report. Time in RFC 3339 format (https://www.rfc-editor.org/rfc/rfc3339.html)", "type": "string", "example": "2009-11-10T23:00:00Z" }, "domain": { "description": "Domain that relates to the report.", "type": "string" }, "id": { "description": "Public facing ID of abuse report, aka abuse_rand.", "type": "string" }, "justification": { "description": "Justification for the report.", "type": "string" }, "mitigation_summary": { "$ref": "#/components/schemas/abuse-reports_MitigationSummary" }, "original_work": { "description": "Original work / Targeted brand in the alleged abuse.", "type": "string" }, "status": { "$ref": "#/components/schemas/abuse-reports_ReportStatus" }, "submitter": { "$ref": "#/components/schemas/abuse-reports_SubmitterDetails" }, "type": { "$ref": "#/components/schemas/abuse-reports_ReportType" }, "urls": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "cdate", "domain", "type", "status", "mitigation_summary" ] }, "abuse-reports_AppealEligibility": { "type": "object", "properties": { "appeal_count": { "description": "Number of appeals submitted against the report so far.", "type": "integer" }, "appealable": { "description": "Whether the report can currently be appealed.", "type": "boolean" }, "has_appealable_mitigations": { "description": "Whether the report has at least one mitigation an appeal could reverse.", "type": "boolean" }, "has_open_appeal": { "description": "Whether the report already has an open (undecided) appeal.", "type": "boolean" }, "max_appeals": { "description": "Maximum number of appeals allowed per report.", "type": "integer" } }, "required": [ "appealable", "has_appealable_mitigations", "has_open_appeal", "appeal_count", "max_appeals" ] }, "abuse-reports_AppealReason": { "description": "Reason why the customer is appealing.", "type": "string", "example": "misclassified", "enum": [ "removed", "misclassified" ] }, "abuse-reports_AppealType": { "description": "The type of appeal being submitted.", "type": "string", "example": "counter_notice", "enum": [ "counter_notice", "content_removed" ] }, "abuse-reports_AuthErrorResponse": { "description": "The Abuse Reports API returns this HTTP 401 authorization error after credentials pass authentication but fail the required Abuse Reports permission check or, for report submission, the account entitlement check. Submission entitlement failures return \"Not entitled to use feature: Abuse Report API\". Enterprise accounts have the entitlement by default; other accounts must request access.", "type": "object", "properties": { "err_code": { "description": "Machine-readable error code.", "type": "string", "example": "unknown_err" }, "error_code": { "description": "Legacy alias for err_code.", "type": "string", "example": "unknown_err" }, "msg": { "description": "Human-readable description of the authorization error. Submission entitlement failures return \"Not entitled to use feature: Abuse Report API\".", "type": "string", "example": "Not entitled to use feature: Abuse Report API" }, "result": { "description": "The result is 'error' for an error response.", "type": "string", "example": "error" } }, "example": { "err_code": "unknown_err", "error_code": "unknown_err", "msg": "Not entitled to use feature: Abuse Report API", "result": "error" }, "required": [ "result", "msg", "err_code", "error_code" ] }, "abuse-reports_BadActError": { "description": "Report has invalid type", "type": "string" }, "abuse-reports_BadAddressError": { "description": "Provided value has invalid size", "type": "string" }, "abuse-reports_BadAgentNameError": { "description": "Provided value has invalid size", "type": "string" }, "abuse-reports_BadCityError": { "description": "Provided value has invalid size", "type": "string" }, "abuse-reports_BadCommentsError": { "description": "Comment maximum length of 2000 characters exceeded", "type": "string" }, "abuse-reports_BadCountryError": { "description": "Provided value has invalid size", "type": "string" }, "abuse-reports_BadEmailError": { "description": "Provided email was invalid", "type": "string" }, "abuse-reports_BadIPError": { "description": "Invalid IP passed to api", "type": "string" }, "abuse-reports_BadJustError": { "description": "Please provide a more detailed description of the infringement between 1 and 5000 characters", "type": "string" }, "abuse-reports_BadNameError": { "description": "Missing a required field", "type": "string" }, "abuse-reports_BadPortsProtocolError": { "description": "Invalid Port and Protocol passed to api", "type": "string" }, "abuse-reports_BadStateError": { "description": "Provided value has invalid size", "type": "string" }, "abuse-reports_BadUrlsError": { "description": "Invalid URL (http://example.com/) Invalid URL Scheme (http or https) Missing hostname in url Missing a required field Could not determine encoding of field\n", "type": "string" }, "abuse-reports_BaseReportFields": { "type": "object", "properties": { "act": { "$ref": "#/components/schemas/abuse-reports_SubmissionReportType" }, "comments": { "description": "Any additional comments about the infringement not exceeding 2000 characters", "type": "string", "maxLength": 2000, "minLength": 1 }, "company": { "description": "Text not exceeding 100 characters. This field may be released by Cloudflare to third parties such as the Lumen Database (https://lumendatabase.org/).", "type": "string", "maxLength": 100, "minLength": 1 }, "email": { "description": "A valid email of the abuse reporter. This field may be released by Cloudflare to third parties such as the Lumen Database (https://lumendatabase.org/).", "type": "string" }, "email2": { "description": "Should match the value provided in `email`", "type": "string" }, "name": { "description": "Text not exceeding 255 characters. This field may be released by Cloudflare to third parties such as the Lumen Database (https://lumendatabase.org/).", "type": "string", "maxLength": 255, "minLength": 1 }, "reported_country": { "description": "Text containing 2 characters", "type": "string", "maxLength": 2, "minLength": 2 }, "reported_user_agent": { "description": "Text not exceeding 255 characters", "type": "string", "maxLength": 255, "minLength": 1 }, "tele": { "description": "Text not exceeding 20 characters. This field may be released by Cloudflare to third parties such as the Lumen Database (https://lumendatabase.org/).", "type": "string", "maxLength": 20, "minLength": 1 }, "title": { "description": "Text not exceeding 255 characters", "type": "string", "maxLength": 255, "minLength": 1 }, "urls": { "description": "A list of valid URLs separated by ‘\\n’ (new line character). The list of the URLs should not exceed 250 URLs. All URLs should have the same hostname. Each URL should be unique. This field may be released by Cloudflare to third parties such as the Lumen Database (https://lumendatabase.org/).", "type": "string" } }, "required": [ "act", "email", "email2", "name", "urls" ] }, "abuse-reports_CSAMReport": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/abuse-reports_BaseReportFields" }, { "properties": { "act": { "type": "string", "enum": [ "abuse_children" ] }, "country": { "description": "Text not exceeding 255 characters. This field may be released by Cloudflare to third parties such as the Lumen Database (https://lumendatabase.org/).\n", "type": "string", "maxLength": 255, "minLength": 1 }, "host_notification": { "description": "Notification type based on the abuse type. NOTE: Copyright (DMCA) and Trademark reports cannot be anonymous.\n", "type": "string", "enum": [ "send", "send-anon" ] }, "justification": { "description": "A detailed description of the infringement, including any necessary access details and the exact steps needed to view the content, not exceeding 5000 characters.\n", "type": "string", "maxLength": 5000, "minLength": 1 }, "ncmec_notification": { "description": "Notification type based on the abuse type. NOTE: Copyright (DMCA) and Trademark reports cannot be anonymous.\n", "type": "string", "enum": [ "send", "send-anon" ] }, "owner_notification": { "description": "Notification type based on the abuse type. NOTE: Copyright (DMCA) and Trademark reports cannot be anonymous.\n", "type": "string", "enum": [ "send", "send-anon", "none" ] } }, "required": [ "host_notification", "justification", "ncmec_notification", "owner_notification" ], "title": "Children Abuse Report", "type": "object" } ] }, "abuse-reports_CloudflareAPIErrorResponse": { "description": "Cloudflare's API layer uses this standard error envelope for requests that fail authentication before they reach the Abuse Reports API. The example shows the authentication error for missing or invalid credentials.", "type": "object", "properties": { "errors": { "description": "Cloudflare API error details.", "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_ErrorMessage" }, "example": [ { "code": 10000, "message": "Authentication error" } ] }, "messages": { "description": "Informational messages.", "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" }, "example": [] }, "result": { "description": "Always null for this error response.", "type": "object", "nullable": true }, "success": { "description": "Whether the request succeeded.", "type": "boolean", "example": false } }, "example": { "errors": [ { "code": 10000, "message": "Authentication error" } ], "messages": [], "result": null, "success": false }, "required": [ "success", "errors", "messages", "result" ] }, "abuse-reports_DBError": { "description": "Failed while reading from database Failed while writing to the database This service error will trigger an alert for Cloudflare engineers to investigate the cause resolve it.\n", "type": "string" }, "abuse-reports_DMCACounterNotice": { "description": "Counter-notice details supporting an appeal.", "type": "object", "properties": { "city": { "type": "string" }, "company": { "type": "string" }, "counter_notice_response": { "type": "string" }, "country": { "type": "string" }, "email": { "type": "string", "format": "email" }, "full_name": { "type": "string" }, "jurisdiction_consent": { "type": "boolean" }, "perjury_attestation": { "type": "boolean" }, "phone_number": { "type": "string" }, "signature": { "type": "string" }, "state": { "type": "string" }, "street_address": { "type": "string" }, "urls": { "type": "array", "items": { "format": "uri", "type": "string" } }, "zip_code": { "type": "string" } }, "required": [ "full_name", "street_address", "city", "state", "country", "zip_code", "phone_number", "email", "urls", "perjury_attestation", "jurisdiction_consent", "signature" ] }, "abuse-reports_DMCAReport": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/abuse-reports_BaseReportFields" }, { "properties": { "act": { "type": "string", "enum": [ "abuse_dmca" ] }, "address1": { "description": "Text not exceeding 100 characters. This field may be released by Cloudflare to third parties such as the Lumen Database (https://lumendatabase.org/).", "type": "string", "maxLength": 100, "minLength": 1 }, "agent_name": { "description": "The name of the copyright holder. Text not exceeding 60 characters. This field may be released by Cloudflare to third parties such as the Lumen Database (https://lumendatabase.org/).", "type": "string", "maxLength": 60, "minLength": 1 }, "agree": { "description": "Can be `0` for false or `1` for true. Must be value: 1 for DMCA reports", "type": "integer", "enum": [ 1 ] }, "city": { "description": "Text not exceeding 255 characters. This field may be released by Cloudflare to third parties such as the Lumen Database (https://lumendatabase.org/).", "type": "string", "maxLength": 255, "minLength": 1 }, "country": { "description": "Text not exceeding 255 characters. This field may be released by Cloudflare to third parties such as the Lumen Database (https://lumendatabase.org/).\n", "type": "string", "maxLength": 255, "minLength": 1 }, "host_notification": { "description": "Notification type based on the abuse type. NOTE: Copyright (DMCA) and Trademark reports cannot be anonymous.\n", "type": "string", "enum": [ "send" ] }, "original_work": { "description": "Text not exceeding 255 characters. This field may be released by Cloudflare to third parties such as the Lumen Database (https://lumendatabase.org/).\n", "type": "string", "maxLength": 255, "minLength": 1 }, "owner_notification": { "description": "Notification type based on the abuse type. NOTE: Copyright (DMCA) and Trademark reports cannot be anonymous.\n", "type": "string", "enum": [ "send" ] }, "signature": { "description": "Required for DMCA reports, should be same as Name. An affirmation that all information in the report is true and accurate while agreeing to the policies of Cloudflare's abuse reports", "type": "string" }, "state": { "description": "Text not exceeding 255 characters. This field may be released by Cloudflare to third parties such as the Lumen Database (https://lumendatabase.org/).", "type": "string", "maxLength": 255, "minLength": 1 } }, "required": [ "address1", "agent_name", "agree", "city", "country", "host_notification", "original_work", "owner_notification", "signature", "state" ], "title": "DMCA Report", "type": "object" } ] }, "abuse-reports_DedupeError": { "description": "You have already submitted this URL in the last 7 days", "type": "string" }, "abuse-reports_DiffEmailError": { "description": "Provided emails did not match", "type": "string" }, "abuse-reports_EmailError": { "description": "Failed to send confirmation email", "type": "string" }, "abuse-reports_EmailListItem": { "description": "An email sent to the customer for an abuse report.", "type": "object", "properties": { "body": { "description": "Body content of the email.", "type": "string" }, "id": { "description": "Unique identifier of the email.", "type": "string" }, "recipient": { "description": "Email address of the recipient.", "type": "string" }, "sent_at": { "description": "When the email was sent. Time in RFC 3339 format (https://www.rfc-editor.org/rfc/rfc3339.html)", "type": "string", "example": "2009-11-10T23:00:00Z" }, "subject": { "description": "Subject line of the email.", "type": "string" } }, "required": [ "id", "subject", "body", "recipient", "sent_at" ] }, "abuse-reports_EmailListResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_ErrorMessage" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "result": { "type": "object", "properties": { "emails": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_EmailListItem" } } }, "required": [ "emails" ] }, "result_info": { "$ref": "#/components/schemas/abuse-reports_ResultInfo" }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] }, "abuse-reports_ErrorCode": { "type": "string", "oneOf": [ { "$ref": "#/components/schemas/abuse-reports_BadActError" }, { "$ref": "#/components/schemas/abuse-reports_BadAddressError" }, { "$ref": "#/components/schemas/abuse-reports_BadAgentNameError" }, { "$ref": "#/components/schemas/abuse-reports_BadCityError" }, { "$ref": "#/components/schemas/abuse-reports_BadCountryError" }, { "$ref": "#/components/schemas/abuse-reports_BadPortsProtocolError" }, { "$ref": "#/components/schemas/abuse-reports_BadStateError" }, { "$ref": "#/components/schemas/abuse-reports_MaxIPsError" }, { "$ref": "#/components/schemas/abuse-reports_PortsProtocolError" }, { "$ref": "#/components/schemas/abuse-reports_BadCommentsError" }, { "$ref": "#/components/schemas/abuse-reports_BadEmailError" }, { "$ref": "#/components/schemas/abuse-reports_BadIPError" }, { "$ref": "#/components/schemas/abuse-reports_BadJustError" }, { "$ref": "#/components/schemas/abuse-reports_BadNameError" }, { "$ref": "#/components/schemas/abuse-reports_BadUrlsError" }, { "$ref": "#/components/schemas/abuse-reports_DBError" }, { "$ref": "#/components/schemas/abuse-reports_DedupeError" }, { "$ref": "#/components/schemas/abuse-reports_DiffEmailError" }, { "$ref": "#/components/schemas/abuse-reports_EmailError" }, { "$ref": "#/components/schemas/abuse-reports_InternalError" }, { "$ref": "#/components/schemas/abuse-reports_InvalidNotifyError" }, { "$ref": "#/components/schemas/abuse-reports_MustNotifyError" }, { "$ref": "#/components/schemas/abuse-reports_NoAgreeError" }, { "$ref": "#/components/schemas/abuse-reports_NoOriginalWorkError" }, { "$ref": "#/components/schemas/abuse-reports_NoSigError" }, { "$ref": "#/components/schemas/abuse-reports_UnexpectedActError" }, { "$ref": "#/components/schemas/abuse-reports_UnknownError" }, { "$ref": "#/components/schemas/abuse-reports_UrlNotOrangeError" }, { "$ref": "#/components/schemas/abuse-reports_UrlNotvalidError" } ] }, "abuse-reports_ErrorMessage": { "type": "object", "properties": { "code": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "message": { "type": "string" } }, "required": [ "message" ] }, "abuse-reports_GeneralReport": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/abuse-reports_BaseReportFields" }, { "properties": { "act": { "type": "string", "enum": [ "abuse_general" ] }, "destination_ips": { "description": "A list of IP addresses separated by ‘\\n’ (new line character). The list of destination IPs should not exceed 30 IP addresses. Each one of the IP addresses ought to be unique.", "type": "string" }, "host_notification": { "description": "Notification type based on the abuse type. NOTE: Copyright (DMCA) and Trademark reports cannot be anonymous.\n", "type": "string", "enum": [ "send", "send-anon" ] }, "justification": { "description": "A detailed description of the infringement, including any necessary access details and the exact steps needed to view the content, not exceeding 5000 characters.\n", "type": "string", "maxLength": 5000, "minLength": 1 }, "owner_notification": { "description": "Notification type based on the abuse type. NOTE: Copyright (DMCA) and Trademark reports cannot be anonymous.\n", "type": "string", "enum": [ "send", "send-anon" ] }, "ports_protocols": { "description": "A comma separated list of ports and protocols e.g. 80/TCP, 22/UDP. The total size of the field should not exceed 2000 characters. Each individual port/protocol should not exceed 100 characters. The list should not have more than 30 unique ports and protocols.", "type": "string" }, "source_ips": { "description": "A list of IP addresses separated by ‘\\n’ (new line character). The list of source IPs should not exceed 30 IP addresses. Each one of the IP addresses ought to be unique.", "type": "string" } }, "required": [ "host_notification", "justification", "owner_notification" ], "title": "General Report", "type": "object" } ] }, "abuse-reports_InternalError": { "description": "Failed to translate email", "type": "string" }, "abuse-reports_InvalidNotifyError": { "description": "Invalid value for notification preference", "type": "string" }, "abuse-reports_MaxIPsError": { "description": "Provided value has invalid size", "type": "string" }, "abuse-reports_Message": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "abuse-reports_MitigatedEntityType": { "description": "The type of entity targeted by a mitigation.", "type": "string", "enum": [ "url_pattern", "account", "zone", "custom_expression" ] }, "abuse-reports_MitigationAppeal": { "type": "object", "properties": { "id": { "description": "ID of the mitigation to appeal.", "type": "string" }, "reason": { "$ref": "#/components/schemas/abuse-reports_AppealReason" } }, "required": [ "id", "reason" ] }, "abuse-reports_MitigationAppealRequest": { "description": "Submit an appeal for a report. Provide either a list of mitigations to appeal, or an appeal type with its supporting details, but not both. When type is \"counter_notice\", the counter-notice details are required.", "type": "object", "properties": { "appeals": { "description": "List of mitigations to appeal.", "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_MitigationAppeal" } }, "data": { "$ref": "#/components/schemas/abuse-reports_DMCACounterNotice" }, "type": { "$ref": "#/components/schemas/abuse-reports_AppealType" } }, "oneOf": [ { "required": [ "appeals" ], "type": "object" }, { "required": [ "type" ], "type": "object" } ] }, "abuse-reports_MitigationAppealResult": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_MitigationListItem" } }, "result_info": { "type": "object", "properties": { "count": { "type": "number" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "page", "per_page", "count", "total_count", "total_pages" ] }, "success": { "type": "boolean" } }, "required": [ "success", "result_info" ] }, "abuse-reports_MitigationListItem": { "type": "object", "properties": { "effective_date": { "description": "Date when the mitigation will become active. Time in RFC 3339 format (https://www.rfc-editor.org/rfc/rfc3339.html)", "type": "string", "example": "2009-11-10T23:00:00Z" }, "entity_id": { "type": "string" }, "entity_type": { "$ref": "#/components/schemas/abuse-reports_MitigatedEntityType" }, "id": { "description": "ID of remediation.", "type": "string" }, "status": { "$ref": "#/components/schemas/abuse-reports_MitigationStatus" }, "type": { "$ref": "#/components/schemas/abuse-reports_MitigationType" } }, "required": [ "id", "type", "effective_date", "status", "entity_type", "entity_id" ] }, "abuse-reports_MitigationStatus": { "description": "The status of a mitigation", "type": "string", "enum": [ "pending", "active", "in_review", "cancelled", "removed" ] }, "abuse-reports_MitigationSummary": { "description": "A summary of the mitigations related to this report.", "type": "object", "properties": { "accepted_url_count": { "description": "How many of the reported URLs were confirmed as abusive.", "type": "integer" }, "active_count": { "description": "How many mitigations are active.", "type": "integer" }, "external_host_notified": { "description": "Whether the report has been forwarded to an external hosting provider.", "type": "boolean" }, "in_review_count": { "description": "How many mitigations are under review.", "type": "integer" }, "pending_count": { "description": "How many mitigations are pending their effective date.", "type": "integer" } }, "required": [ "accepted_url_count", "pending_count", "active_count", "in_review_count", "external_host_notified" ] }, "abuse-reports_MitigationType": { "description": "The type of mitigation applied to a reported entity.", "type": "string" }, "abuse-reports_MustNotifyError": { "description": "Please pick one party to notify about this report", "type": "string" }, "abuse-reports_NCSEIReport": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/abuse-reports_BaseReportFields" }, { "properties": { "act": { "type": "string", "enum": [ "abuse_ncsei" ] }, "country": { "description": "Text not exceeding 255 characters. This field may be released by Cloudflare to third parties such as the Lumen Database (https://lumendatabase.org/).\n", "type": "string", "maxLength": 255, "minLength": 1 }, "host_notification": { "description": "Notification type based on the abuse type. NOTE: Copyright (DMCA) and Trademark reports cannot be anonymous.\n", "type": "string", "enum": [ "send", "send-anon" ] }, "ncsei_subject_representation": { "description": "If the submitter is the target of NCSEI in the URLs of the abuse report.", "type": "boolean" }, "owner_notification": { "description": "Notification type based on the abuse type. NOTE: Copyright (DMCA) and Trademark reports cannot be anonymous.\n", "type": "string", "enum": [ "send", "send-anon", "none" ] } }, "required": [ "host_notification", "ncsei_subject_representation", "owner_notification" ], "title": "NCSEI Report", "type": "object" } ] }, "abuse-reports_NoAgreeError": { "description": "Must acknowledge that you are bound by 512(f), that you have a good faith belief about the material, and that you have the authority to act", "type": "string" }, "abuse-reports_NoOriginalWorkError": { "description": "Original Work section must be between 20 and 2000 characters. Please include a description of the original work and a URL to the original content when possible.", "type": "string" }, "abuse-reports_NoSigError": { "description": "Signature must match your name", "type": "string" }, "abuse-reports_PhishingReport": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/abuse-reports_BaseReportFields" }, { "properties": { "act": { "type": "string", "enum": [ "abuse_phishing" ] }, "host_notification": { "description": "Notification type based on the abuse type. NOTE: Copyright (DMCA) and Trademark reports cannot be anonymous.\n", "type": "string", "enum": [ "send", "send-anon" ] }, "justification": { "description": "A detailed description of the infringement, including any necessary access details and the exact steps needed to view the content, not exceeding 5000 characters.\n", "type": "string", "maxLength": 5000, "minLength": 20 }, "original_work": { "description": "Text not exceeding 255 characters. This field may be released by Cloudflare to third parties such as the Lumen Database (https://lumendatabase.org/).\n", "type": "string", "maxLength": 255, "minLength": 1 }, "owner_notification": { "description": "Notification type based on the abuse type. NOTE: Copyright (DMCA) and Trademark reports cannot be anonymous.\n", "type": "string", "enum": [ "send", "send-anon" ] } }, "required": [ "host_notification", "justification", "owner_notification" ], "title": "Phishing Report", "type": "object" } ] }, "abuse-reports_PortsProtocolError": { "description": "Provided value has invalid size", "type": "string" }, "abuse-reports_RegistrarWhoIsFields": { "description": "RDP-mandated fields for registrar WHOIS data disclosure requests.", "type": "object", "properties": { "reg_who_authorization_statement": { "description": "Optional authorization statement or power of attorney per RDP 10.2.1.3.", "type": "string", "maxLength": 5000 }, "reg_who_good_faith_affirmation": { "description": "Affirmation that the request is made in good faith per RDP 10.2.4. Must be true.", "type": "boolean" }, "reg_who_lawful_processing_agreement": { "description": "Agreement to process data lawfully per RDP 10.2.5. Must be true.", "type": "boolean" }, "reg_who_legal_basis": { "description": "Legal rights and rationale for the request per RDP 10.2.3. Required for all WHOIS requests.", "type": "string", "maxLength": 5000 }, "reg_who_request_type": { "description": "The type of WHOIS data request per RDP procedure.", "type": "string", "enum": [ "disclosure", "invalid_whois" ] }, "reg_who_requested_data_elements": { "description": "The specific WHOIS data elements being requested per RDP 10.2.2. Required for all WHOIS requests.", "type": "array", "items": { "enum": [ "registrant_name", "registrant_organization", "registrant_email", "registrant_phone", "registrant_address", "registrant_address_country", "registrant_address_postal_code", "admin_name", "admin_organization", "admin_email", "admin_phone", "admin_address", "tech_name", "tech_organization", "tech_email", "tech_phone", "tech_address" ], "type": "string" }, "maxItems": 17, "minItems": 1 }, "reg_who_requestor_type": { "description": "The nature of the requestor per RDP 10.2.1.2.", "type": "string", "enum": [ "government", "corporation", "individual" ] } }, "required": [ "reg_who_request_type", "reg_who_requested_data_elements", "reg_who_legal_basis", "reg_who_good_faith_affirmation", "reg_who_lawful_processing_agreement" ] }, "abuse-reports_RegistrarWhoisReport": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/abuse-reports_BaseReportFields" }, { "properties": { "act": { "type": "string", "enum": [ "abuse_registrar_whois" ] }, "owner_notification": { "description": "Notification type based on the abuse type. NOTE: Copyright (DMCA) and Trademark reports cannot be anonymous.\n", "type": "string", "enum": [ "send", "send-anon", "none" ] }, "reg_who_request": { "$ref": "#/components/schemas/abuse-reports_RegistrarWhoIsFields" } }, "required": [ "owner_notification" ], "title": "Registrar Whois Report", "type": "object" } ] }, "abuse-reports_ReportStatus": { "description": "An enum value that represents the status of an abuse record", "type": "string", "enum": [ "accepted", "in_review" ] }, "abuse-reports_ReportType": { "description": "The abuse report type", "type": "string", "enum": [ "PHISH", "GEN", "THREAT", "DMCA", "EMER", "TM", "REG_WHO", "NCSEI", "NETWORK" ] }, "abuse-reports_ResultInfo": { "type": "object", "properties": { "count": { "type": "number" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "page", "per_page", "count", "total_count", "total_pages" ] }, "abuse-reports_SubmissionReportType": { "description": "The report type for submitted reports.", "type": "string" }, "abuse-reports_SubmitErrorResponse": { "type": "object", "properties": { "err_code": { "$ref": "#/components/schemas/abuse-reports_ErrorCode" }, "error_code": { "$ref": "#/components/schemas/abuse-reports_ErrorCode" }, "msg": { "description": "The error message for the error", "type": "string" }, "request": { "type": "object", "properties": { "act": { "$ref": "#/components/schemas/abuse-reports_SubmissionReportType" } }, "required": [ "act" ] }, "result": { "description": "The result should be 'error' for successful response", "type": "string" } }, "required": [ "request", "result", "msg", "err_code", "error_code" ] }, "abuse-reports_SubmitReportRequest": { "discriminator": { "mapping": { "abuse_children": "#/components/schemas/abuse-reports_CSAMReport", "abuse_dmca": "#/components/schemas/abuse-reports_DMCAReport", "abuse_general": "#/components/schemas/abuse-reports_GeneralReport", "abuse_ncsei": "#/components/schemas/abuse-reports_NCSEIReport", "abuse_phishing": "#/components/schemas/abuse-reports_PhishingReport", "abuse_registrar_whois": "#/components/schemas/abuse-reports_RegistrarWhoisReport", "abuse_threat": "#/components/schemas/abuse-reports_ThreatReport", "abuse_trademark": "#/components/schemas/abuse-reports_TrademarkReport" }, "propertyName": "act" }, "oneOf": [ { "$ref": "#/components/schemas/abuse-reports_DMCAReport" }, { "$ref": "#/components/schemas/abuse-reports_TrademarkReport" }, { "$ref": "#/components/schemas/abuse-reports_GeneralReport" }, { "$ref": "#/components/schemas/abuse-reports_PhishingReport" }, { "$ref": "#/components/schemas/abuse-reports_CSAMReport" }, { "$ref": "#/components/schemas/abuse-reports_ThreatReport" }, { "$ref": "#/components/schemas/abuse-reports_RegistrarWhoisReport" }, { "$ref": "#/components/schemas/abuse-reports_NCSEIReport" } ] }, "abuse-reports_SubmitReportResponse": { "type": "object", "properties": { "abuse_rand": { "description": "The identifier for the submitted abuse report.", "type": "string" }, "request": { "type": "object", "properties": { "act": { "$ref": "#/components/schemas/abuse-reports_SubmissionReportType" } }, "required": [ "act" ] }, "result": { "description": "The result should be 'success' for successful response", "type": "string" } }, "required": [ "request", "result", "abuse_rand" ] }, "abuse-reports_SubmittedAbuseReportDenialReason": { "description": "Submitter-safe reason that a submitted report was denied.", "type": "string", "enum": [ "unable_to_confirm", "incomplete_report", "not_on_cloudflare", "duplicate_report", "content_removed", "report_details_mismatch", "no_abuse_found", "missing_original_work", "direct_url_required", "wrong_report_category", "content_unavailable", "law_enforcement_referral_required", "domain_dispute_process_required" ] }, "abuse-reports_SubmittedAbuseReportDetail": { "allOf": [ { "$ref": "#/components/schemas/abuse-reports_SubmittedAbuseReportListItem" }, { "properties": { "agent_name": { "description": "Authorized agent name supplied with the report.", "type": "string" }, "comments": { "description": "Additional comments supplied with the report.", "type": "string" }, "court": { "description": "The string \"on\" when a court proceeding applies to the report; otherwise omitted.", "type": "string" }, "destination_ips": { "description": "Destination IP addresses supplied with a network abuse report.", "type": "array", "items": { "type": "string" } }, "dsa_attestation": { "description": "Whether the submitter provided the Digital Services Act attestation.", "type": "boolean" }, "host_notification": { "description": "Submitter preference for notifying the hosting provider.", "type": "string" }, "justification": { "description": "Evidence supplied with the report.", "type": "string" }, "ncmec_notification": { "description": "Submitter preference for notifying NCMEC.", "type": "string" }, "ncsei_subject_representation": { "description": "Representation supplied for an NCSEI report.", "type": "boolean" }, "original_work": { "description": "Original work or targeted brand supplied with the report.", "type": "string" }, "owner_notification": { "description": "Submitter preference for notifying the content owner.", "type": "string" }, "ports_protocols": { "description": "Ports and protocols supplied with a network abuse report.", "type": "array", "items": { "type": "string" } }, "reg_who_request": { "$ref": "#/components/schemas/abuse-reports_RegistrarWhoIsFields" }, "reported_country": { "description": "Country associated with the reported activity.", "type": "string" }, "reported_user_agent": { "description": "User agent associated with the reported activity.", "type": "string" }, "source_ips": { "description": "Source IP addresses supplied with a network abuse report.", "type": "array", "items": { "type": "string" } }, "subtypes": { "description": "Additional abuse classifications supplied with the report.", "type": "array", "items": { "type": "string" } }, "title": { "description": "Title supplied with the report.", "type": "string" }, "udrp": { "description": "The string \"on\" when a UDRP proceeding applies to the report; otherwise omitted.", "type": "string" }, "urls": { "description": "URLs supplied with the report.", "type": "array", "items": { "type": "string" } }, "urs": { "description": "The string \"on\" when a URS proceeding applies to the report; otherwise omitted.", "type": "string" } }, "required": [ "urls", "dsa_attestation" ], "type": "object" } ] }, "abuse-reports_SubmittedAbuseReportDetailResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_ErrorMessage" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "result": { "$ref": "#/components/schemas/abuse-reports_SubmittedAbuseReportDetail" }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] }, "abuse-reports_SubmittedAbuseReportListItem": { "type": "object", "properties": { "cdate": { "description": "Time the report was submitted.", "type": "string", "format": "date-time" }, "denial_reason": { "description": "Submitter-safe reason for a denied report. Null when unavailable.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/abuse-reports_SubmittedAbuseReportDenialReason" } ], "nullable": true }, "domain": { "description": "Domain identified in the report.", "type": "string" }, "id": { "description": "Public report code.", "type": "string" }, "status": { "$ref": "#/components/schemas/abuse-reports_SubmittedAbuseReportStatus" }, "submitter": { "$ref": "#/components/schemas/abuse-reports_SubmitterDetails" }, "type": { "$ref": "#/components/schemas/abuse-reports_ReportType" } }, "required": [ "id", "cdate", "domain", "type", "status", "denial_reason" ] }, "abuse-reports_SubmittedAbuseReportListResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_ErrorMessage" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_Message" } }, "result": { "type": "object", "properties": { "reports": { "type": "array", "items": { "$ref": "#/components/schemas/abuse-reports_SubmittedAbuseReportListItem" } } }, "required": [ "reports" ] }, "result_info": { "$ref": "#/components/schemas/abuse-reports_ResultInfo" }, "success": { "type": "boolean" } }, "required": [ "success", "result" ] }, "abuse-reports_SubmittedAbuseReportStatus": { "description": "Status visible to the account that submitted the report.", "type": "string", "enum": [ "submitted", "accepted", "denied" ] }, "abuse-reports_SubmitterDetails": { "description": "Information about the submitter of the report.", "type": "object", "properties": { "company": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "telephone": { "type": "string" } } }, "abuse-reports_ThreatReport": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/abuse-reports_BaseReportFields" }, { "properties": { "act": { "type": "string", "enum": [ "abuse_threat" ] }, "host_notification": { "description": "Notification type based on the abuse type. NOTE: Copyright (DMCA) and Trademark reports cannot be anonymous.\n", "type": "string", "enum": [ "send", "send-anon" ] }, "justification": { "description": "A detailed description of the infringement, including any necessary access details and the exact steps needed to view the content, not exceeding 5000 characters.\n", "type": "string", "maxLength": 5000, "minLength": 1 }, "owner_notification": { "description": "Notification type based on the abuse type. NOTE: Copyright (DMCA) and Trademark reports cannot be anonymous.\n", "type": "string", "enum": [ "send", "send-anon" ] } }, "required": [ "host_notification", "justification", "owner_notification" ], "title": "Threat Report", "type": "object" } ] }, "abuse-reports_TrademarkReport": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/abuse-reports_BaseReportFields" }, { "properties": { "act": { "type": "string", "enum": [ "abuse_trademark" ] }, "host_notification": { "description": "Notification type based on the abuse type. NOTE: Copyright (DMCA) and Trademark reports cannot be anonymous.\n", "type": "string", "enum": [ "send" ] }, "justification": { "description": "A detailed description of the infringement, including any necessary access details and the exact steps needed to view the content, not exceeding 5000 characters.\n", "type": "string", "maxLength": 5000, "minLength": 1 }, "owner_notification": { "description": "Notification type based on the abuse type. NOTE: Copyright (DMCA) and Trademark reports cannot be anonymous.\n", "type": "string", "enum": [ "send" ] }, "trademark_number": { "description": "Text not exceeding 1000 characters", "type": "string", "maxLength": 1000, "minLength": 1 }, "trademark_office": { "description": "Text not exceeding 1000 characters", "type": "string", "maxLength": 1000, "minLength": 1 }, "trademark_symbol": { "description": "Text not exceeding 1000 characters", "type": "string", "maxLength": 1000, "minLength": 1 } }, "required": [ "host_notification", "justification", "owner_notification", "trademark_number", "trademark_office", "trademark_symbol" ], "title": "Trademark Report", "type": "object" } ] }, "abuse-reports_UnauthorizedErrorResponse": { "description": "For HTTP 401 responses, use one of these error shapes. Cloudflare's API layer rejects requests with missing or invalid credentials before they reach the Abuse Reports API and returns the standard Cloudflare API error envelope. The Abuse Reports API returns its authorization error shape when valid credentials fail the Abuse Reports permission check or the submission entitlement check.", "oneOf": [ { "$ref": "#/components/schemas/abuse-reports_CloudflareAPIErrorResponse" }, { "$ref": "#/components/schemas/abuse-reports_AuthErrorResponse" } ] }, "abuse-reports_UnexpectedActError": { "description": "Report has the wrong type", "type": "string" }, "abuse-reports_UnknownError": { "description": "An unexpected error occurred", "type": "string" }, "abuse-reports_UrlNotOrangeError": { "description": "A URL contains a domain that is not active on Cloudflare", "type": "string" }, "abuse-reports_UrlNotvalidError": { "description": "You have entered URLs that contain more than 1 unique hostname. A single report may only include 1 unique hostname (i.e, www.example.com). To report URLs related to another hostname (i.e. other.example.com) you'll need to file a separate report.", "type": "string" }, "access_aaguid": { "description": "The Authenticator Attestation GUID (AAGUID) uniquely identifying a FIDO2 authenticator model", "type": "string", "format": "uuid", "example": "2fc0579f-8113-47ea-b116-bb5a8db9202a" }, "access_access-requests": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/access_action" }, "allowed": { "$ref": "#/components/schemas/access_allowed" }, "app_domain": { "$ref": "#/components/schemas/access_app_domain" }, "app_uid": { "$ref": "#/components/schemas/access_app_uid" }, "connection": { "$ref": "#/components/schemas/access_connection" }, "created_at": { "$ref": "#/components/schemas/access_timestamp" }, "ip_address": { "$ref": "#/components/schemas/access_ip" }, "ray_id": { "$ref": "#/components/schemas/access_ray_id" }, "user_email": { "$ref": "#/components/schemas/access_email-3" } } }, "access_access_group_rule": { "description": "Matches an Access group.", "type": "object", "properties": { "group": { "type": "object", "properties": { "id": { "description": "The ID of a previously created Access group.", "type": "string", "example": "aa0a4aab-672b-4bdb-bc33-a59f1130a11f" } }, "required": [ "id" ] } }, "required": [ "group" ], "title": "Access groups" }, "access_access_seat": { "description": "True if the seat is part of Access.", "type": "boolean", "example": false, "x-auditable": true }, "access_access_seat-2": { "description": "True if the user has authenticated with Cloudflare Access.", "type": "boolean", "example": false }, "access_action": { "description": "The event that occurred, such as a login attempt.", "type": "string", "example": "login" }, "access_active_device_count": { "description": "The number of active devices registered to the user.", "type": "number", "example": 2 }, "access_active_session_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity" }, { "properties": { "isActive": { "type": "boolean", "example": true } }, "type": "object" } ] } }, "type": "object" } ] }, "access_active_sessions_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "properties": { "expiration": { "type": "integer", "example": 1694813506 }, "metadata": { "type": "object", "properties": { "apps": { "type": "object", "additionalProperties": { "properties": { "hostname": { "type": "string", "example": "test.example.com" }, "name": { "type": "string", "example": "app name" }, "type": { "type": "string", "example": "self_hosted" }, "uid": { "type": "string", "example": "cc2a8145-0128-4429-87f3-872c4d380c4e" } }, "type": "object" } }, "expires": { "type": "integer", "example": 1694813506 }, "iat": { "type": "integer", "example": 1694791905 }, "nonce": { "type": "string", "example": "X1aXj1lFVcqqyoXF" }, "ttl": { "type": "integer", "example": 21600 } } }, "name": { "type": "string" } }, "type": "object" } } }, "type": "object" } ] }, "access_allow_all_headers": { "description": "Allows all HTTP request headers.", "type": "boolean", "example": true }, "access_allow_all_methods": { "description": "Allows all HTTP request methods.", "type": "boolean" }, "access_allow_all_origins": { "description": "Allows all origins.", "type": "boolean" }, "access_allow_authenticate_via_warp": { "description": "When set to true, users can authenticate via WARP for any application in your organization. Application settings will take precedence over this value.", "type": "boolean", "example": "false", "default": false, "x-auditable": true }, "access_allow_authenticate_via_warp-2": { "description": "When set to true, users can authenticate to this application using their WARP session. When set to false this application will always require direct IdP authentication. This setting always overrides the organization setting for WARP authentication.", "type": "boolean", "example": true }, "access_allow_credentials": { "description": "When set to `true`, includes credentials (cookies, authorization headers, or TLS client certificates) with requests.", "type": "boolean" }, "access_allow_email_alias": { "description": "Enables using Identity Provider email alias as SSH username.", "type": "boolean", "x-auditable": true }, "access_allow_iframe": { "description": "Enables loading application content in an iFrame.", "type": "boolean", "example": true }, "access_allowed": { "description": "The result of the authentication event.", "type": "boolean", "default": false }, "access_allowed_clipboard_local_to_remote_formats": { "description": "Clipboard formats allowed when copying from local machine to remote RDP session.", "type": "array", "items": { "$ref": "#/components/schemas/access_rdp_clipboard_format" }, "example": [ "text", "file" ] }, "access_allowed_clipboard_remote_to_local_formats": { "description": "Clipboard formats allowed when copying from remote RDP session to local machine.", "type": "array", "items": { "$ref": "#/components/schemas/access_rdp_clipboard_format" }, "example": [ "text", "file" ] }, "access_allowed_headers": { "description": "Allowed HTTP request headers.", "type": "array", "items": { "type": "string" } }, "access_allowed_idps": { "description": "The identity providers your users can select when connecting to this application. Defaults to all IdPs configured in your account.", "type": "array", "items": { "description": "The identity providers selected for application.", "example": "699d98642c564d2e855e9661899b7252", "type": "string" } }, "access_allowed_methods": { "description": "Allowed HTTP request methods.", "type": "array", "items": { "enum": [ "GET", "POST", "HEAD", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH" ], "type": "string" }, "example": [ "GET" ] }, "access_allowed_origins": { "description": "Allowed origins.", "type": "array", "items": { "type": "string" }, "example": [ "https://example.com" ] }, "access_any_valid_service_token_rule": { "description": "Matches any valid Access Service Token", "type": "object", "properties": { "any_valid_service_token": { "description": "An empty object which matches on all service tokens.", "type": "object", "example": {}, "x-stainless-empty-object": true } }, "required": [ "any_valid_service_token" ], "title": "Any Valid Service Token" }, "access_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "access_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/access_messages" }, "messages": { "$ref": "#/components/schemas/access_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "access_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/access_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/access_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "access_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-common" } ] }, "access_app_count": { "description": "Number of access applications currently using this policy.", "type": "integer", "example": 2, "x-auditable": true }, "access_app_count-2": { "description": "Number of apps the custom page is assigned to.", "type": "integer", "x-auditable": true, "x-stainless-skip": true }, "access_app_domain": { "description": "The URL of the Access application.", "type": "string", "example": "test.example.com/admin" }, "access_app_id": { "oneOf": [ { "$ref": "#/components/schemas/access_identifier" }, { "$ref": "#/components/schemas/access_uuid" } ] }, "access_app_launcher_logo_url": { "description": "The image URL of the logo shown in the App Launcher header.", "type": "string", "example": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg" }, "access_app_launcher_props": { "allOf": [ { "$ref": "#/components/schemas/access_feature_app_props" }, { "properties": { "app_launcher_logo_url": { "$ref": "#/components/schemas/access_app_launcher_logo_url" }, "bg_color": { "$ref": "#/components/schemas/access_bg_color" }, "domain": { "type": "string", "example": "authdomain.cloudflareaccess.com", "readOnly": true }, "footer_links": { "$ref": "#/components/schemas/access_footer_links" }, "header_bg_color": { "$ref": "#/components/schemas/access_header_bg_color" }, "landing_page_design": { "$ref": "#/components/schemas/access_landing_page_design" }, "name": { "type": "string", "example": "App Launcher", "default": "App Launcher", "readOnly": true }, "skip_app_launcher_login_page": { "$ref": "#/components/schemas/access_skip_app_launcher_login_page" }, "type": { "allOf": [ { "$ref": "#/components/schemas/access_type" }, { "example": "app_launcher", "type": "string" } ] } }, "type": "object" } ] }, "access_app_launcher_props-2": { "allOf": [ { "$ref": "#/components/schemas/access_feature_app_props-2" }, { "properties": { "domain": { "type": "string", "example": "authdomain.cloudflareaccess.com", "readOnly": true }, "name": { "type": "string", "example": "App Launcher", "default": "App Launcher", "readOnly": true }, "type": { "description": "The application type.", "type": "string", "example": "app_launcher" } }, "type": "object" } ] }, "access_app_launcher_visible": { "description": "Displays the application in the App Launcher.", "type": "boolean", "example": true, "default": true }, "access_app_launcher_visible-2": { "description": "Displays the application in the App Launcher.", "type": "boolean", "example": true, "x-auditable": true }, "access_app_policy_link": { "description": "A JSON that links a reusable policy to an application.", "type": "object", "properties": { "account_id": { "$ref": "#/components/schemas/access_identifier" }, "id": { "$ref": "#/components/schemas/access_uuid-2" }, "precedence": { "$ref": "#/components/schemas/access_precedence" } } }, "access_app_policy_request": { "type": "object", "allOf": [ { "properties": { "precedence": { "$ref": "#/components/schemas/access_precedence" } }, "type": "object" }, { "$ref": "#/components/schemas/access_policy_req" } ] }, "access_app_policy_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_policy_resp" }, { "properties": { "account_id": { "$ref": "#/components/schemas/access_identifier" }, "precedence": { "$ref": "#/components/schemas/access_precedence" } }, "type": "object" } ] }, "access_app_policy_result": { "anyOf": [ { "$ref": "#/components/schemas/access_app_policy_response" }, { "$ref": "#/components/schemas/access_infra_policy_resp" } ] }, "access_app_policy_write_request": { "anyOf": [ { "$ref": "#/components/schemas/access_app_policy_request" }, { "$ref": "#/components/schemas/access_infra_policy_req" } ] }, "access_app_req_embedded_policies": { "type": "object", "properties": { "policies": { "description": "The policies that Access applies to the application, in ascending order of precedence. Items can reference existing policies or create new policies exclusive to the application. Reusable and inline policies are mutually exclusive.", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/access_app_policy_link" }, { "allOf": [ { "description": "A policy UID to link to this application.", "type": "string" }, { "$ref": "#/components/schemas/access_uuid-2" } ] }, { "allOf": [ { "type": "object" }, { "description": "An application-scoped policy JSON. If the policy does not yet exist, it will be created.", "properties": { "id": { "$ref": "#/components/schemas/access_uuid-2" } }, "type": "object" }, { "$ref": "#/components/schemas/access_app_policy_request" } ] } ] } } } }, "access_app_req_embedded_scim_config": { "type": "object", "properties": { "scim_config": { "$ref": "#/components/schemas/access_scim_config" } } }, "access_app_request": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/access_self_hosted_props" }, { "$ref": "#/components/schemas/access_app_req_embedded_policies" }, { "$ref": "#/components/schemas/access_app_req_embedded_scim_config" } ], "title": "Self Hosted Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_saas_props" }, { "$ref": "#/components/schemas/access_app_req_embedded_policies" }, { "$ref": "#/components/schemas/access_app_req_embedded_scim_config" } ], "title": "SaaS Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_ssh_props" }, { "$ref": "#/components/schemas/access_app_req_embedded_policies" }, { "$ref": "#/components/schemas/access_app_req_embedded_scim_config" } ], "title": "Browser SSH Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_vnc_props" }, { "$ref": "#/components/schemas/access_app_req_embedded_policies" }, { "$ref": "#/components/schemas/access_app_req_embedded_scim_config" } ], "title": "Browser VNC Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_app_launcher_props" }, { "$ref": "#/components/schemas/access_app_req_embedded_policies" } ], "title": "App Launcher Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_warp_props" }, { "$ref": "#/components/schemas/access_app_req_embedded_policies" } ], "title": "Device Enrollment Permissions Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_biso_props" }, { "$ref": "#/components/schemas/access_app_req_embedded_policies" } ], "title": "Browser Isolation Permissions Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_proxy_endpoint_props" }, { "$ref": "#/components/schemas/access_app_req_embedded_policies" } ], "title": "Gateway Identity Proxy Endpoint Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_bookmark_props" }, { "$ref": "#/components/schemas/access_app_req_embedded_policies" } ], "title": "Bookmark application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_infra_props" }, { "$ref": "#/components/schemas/access_infra_app_req_embedded_policies" } ], "title": "Infrastructure application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_rdp_props" }, { "$ref": "#/components/schemas/access_app_req_embedded_policies" } ], "title": "Browser RDP Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_mcp_props" }, { "$ref": "#/components/schemas/access_app_req_embedded_policies" } ], "title": "MCP Server Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_mcp_portal_props" }, { "$ref": "#/components/schemas/access_app_req_embedded_policies" } ], "title": "MCP Server Portal Application", "type": "object" } ] }, "access_app_resp_embedded_policies": { "description": "The policies that Access applies to the application.", "type": "object", "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/access_app_policy_response" } } } }, "access_app_resp_embedded_target_criteria_infra": { "description": "Contains the targets secured by the application.", "type": "object", "properties": { "target_criteria": { "type": "array", "items": { "$ref": "#/components/schemas/access_target_criteria_infra_app" } } } }, "access_app_resp_embedded_target_criteria_self_hosted": { "description": "Contains the targets secured by the application.", "type": "object", "properties": { "target_criteria": { "type": "array", "items": { "$ref": "#/components/schemas/access_target_criteria_self_hosted_app" } } } }, "access_app_response": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props" }, { "$ref": "#/components/schemas/access_self_hosted_props" }, { "$ref": "#/components/schemas/access_app_resp_embedded_policies" } ], "title": "Self Hosted Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props" }, { "$ref": "#/components/schemas/access_saas_props" }, { "$ref": "#/components/schemas/access_app_resp_embedded_policies" } ], "title": "SaaS Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props" }, { "$ref": "#/components/schemas/access_ssh_props" }, { "$ref": "#/components/schemas/access_app_resp_embedded_policies" } ], "title": "Browser SSH Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props" }, { "$ref": "#/components/schemas/access_vnc_props" }, { "$ref": "#/components/schemas/access_app_resp_embedded_policies" } ], "title": "Browser VNC Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props" }, { "$ref": "#/components/schemas/access_app_launcher_props" }, { "$ref": "#/components/schemas/access_app_resp_embedded_policies" } ], "title": "App Launcher Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props" }, { "$ref": "#/components/schemas/access_warp_props" }, { "$ref": "#/components/schemas/access_app_resp_embedded_policies" } ], "title": "Device Enrollment Permissions Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props" }, { "$ref": "#/components/schemas/access_biso_props" }, { "$ref": "#/components/schemas/access_app_resp_embedded_policies" } ], "title": "Browser Isolation Permissions Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props" }, { "$ref": "#/components/schemas/access_proxy_endpoint_props" }, { "$ref": "#/components/schemas/access_app_resp_embedded_policies" } ], "title": "Gateway Identity Proxy Endpoint Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props" }, { "$ref": "#/components/schemas/access_bookmark_props" }, { "$ref": "#/components/schemas/access_app_resp_embedded_policies" } ], "title": "Bookmark application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props" }, { "$ref": "#/components/schemas/access_infra_props" }, { "$ref": "#/components/schemas/access_infra_app_resp_embedded_policies" } ], "title": "Infrastructure application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props" }, { "$ref": "#/components/schemas/access_rdp_props" }, { "$ref": "#/components/schemas/access_app_resp_embedded_policies" } ], "title": "Browser RDP Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props" }, { "$ref": "#/components/schemas/access_mcp_props" }, { "$ref": "#/components/schemas/access_app_resp_embedded_policies" } ], "title": "MCP Server Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props" }, { "$ref": "#/components/schemas/access_mcp_portal_props" }, { "$ref": "#/components/schemas/access_app_resp_embedded_policies" } ], "title": "MCP Server Portal Application", "type": "object" } ] }, "access_app_settings_request": { "type": "object", "properties": { "allow_iframe": { "$ref": "#/components/schemas/access_allow_iframe" }, "skip_interstitial": { "$ref": "#/components/schemas/access_skip_interstitial" } } }, "access_app_settings_response": { "type": "object", "properties": { "allow_iframe": { "$ref": "#/components/schemas/access_allow_iframe" }, "skip_interstitial": { "$ref": "#/components/schemas/access_skip_interstitial" } } }, "access_app_uid": { "description": "The unique identifier for the Access application.", "type": "string", "example": "df7e2w5f-02b7-4d9d-af26-8d1988fca630" }, "access_approval_group": { "description": "A group of email addresses that can approve a temporary authentication request.", "type": "object", "properties": { "approvals_needed": { "description": "The number of approvals needed to obtain access.", "type": "number", "example": 1, "minimum": 0 }, "email_addresses": { "description": "A list of emails that can approve the access request.", "type": "array", "items": { "type": "string" }, "example": [ "test@cloudflare.com", "test2@cloudflare.com" ] }, "email_list_uuid": { "description": "The UUID of an re-usable email list.", "type": "string" } }, "required": [ "approvals_needed" ] }, "access_approval_groups": { "description": "Administrators who can approve a temporary authentication request.", "type": "array", "items": { "$ref": "#/components/schemas/access_approval_group" }, "example": [ { "approvals_needed": 1, "email_addresses": [ "test1@cloudflare.com", "test2@cloudflare.com" ] }, { "approvals_needed": 3, "email_list_uuid": "597147a1-976b-4ef2-9af0-81d5d007fc34" } ], "x-stainless-collection-type": "set" }, "access_approval_groups-2": { "description": "Administrators who can approve a temporary authentication request.", "type": "array", "items": { "$ref": "#/components/schemas/access_approval_group" }, "example": [ { "approvals_needed": 1, "email_addresses": [ "test1@cloudflare.com", "test2@cloudflare.com" ] }, { "approvals_needed": 3, "email_list_uuid": "597147a1-976b-4ef2-9af0-81d5d007fc34" } ] }, "access_approval_required": { "description": "Requires the user to request access from an administrator at the start of each session.", "type": "boolean", "example": true }, "access_approval_required-2": { "description": "Requires the user to request access from an administrator at the start of each session.", "type": "boolean", "example": true, "default": false }, "access_apps": { "type": "object", "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props-2" }, { "$ref": "#/components/schemas/access_self_hosted_props-2" } ], "title": "Self Hosted Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props-2" }, { "$ref": "#/components/schemas/access_saas_props-2" } ], "title": "SaaS Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props-2" }, { "$ref": "#/components/schemas/access_ssh_props-2" } ], "title": "Browser SSH Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props-2" }, { "$ref": "#/components/schemas/access_vnc_props-2" } ], "title": "Browser VNC Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props-2" }, { "$ref": "#/components/schemas/access_app_launcher_props-2" } ], "title": "App Launcher Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props-2" }, { "$ref": "#/components/schemas/access_warp_props-2" } ], "title": "Device Enrollment Permissions Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props-2" }, { "$ref": "#/components/schemas/access_biso_props-2" } ], "title": "Browser Isolation Permissions Application", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/access_basic_app_response_props-2" }, { "$ref": "#/components/schemas/access_bookmark_props-2" } ], "title": "Bookmark application", "type": "object" } ] }, "access_associated_hostnames": { "description": "The hostnames of the applications that will use this certificate.", "type": "array", "items": { "description": "A fully-qualified domain name (FQDN).", "example": "admin.example.com", "type": "string", "x-auditable": true } }, "access_associated_hostnames-2": { "description": "The hostnames of the applications that will use this certificate.", "type": "array", "items": { "description": "A fully-qualified domain name (FQDN).", "example": "admin.example.com", "type": "string" } }, "access_aud": { "description": "The Application Audience (AUD) tag. Identifies the application associated with the CA.", "type": "string", "example": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893", "maxLength": 64, "readOnly": true, "x-auditable": true }, "access_aud-2": { "description": "Audience tag.", "type": "string", "example": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893", "maxLength": 64, "readOnly": true }, "access_aud-3": { "description": "The Application Audience (AUD) tag. Identifies the application associated with the CA.", "type": "string", "example": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe3893", "maxLength": 64, "readOnly": true }, "access_auth_context_rule": { "description": "Matches an Azure Authentication Context.\nRequires an Azure identity provider.", "type": "object", "properties": { "auth_context": { "type": "object", "properties": { "ac_id": { "description": "The ACID of an Authentication context.", "type": "string", "example": "ea85612a-29c8-46c2-bacb-669d65136971" }, "id": { "description": "The ID of an Authentication context.", "type": "string", "example": "aa0a4aab-672b-4bdb-bc33-a59f1130a11f" }, "identity_provider_id": { "description": "The ID of your Azure identity provider.", "type": "string", "example": "ea85612a-29c8-46c2-bacb-669d65136971" } }, "required": [ "id", "identity_provider_id", "ac_id" ] } }, "required": [ "auth_context" ], "title": "Authentication Context" }, "access_auth_domain": { "description": "The unique subdomain assigned to your Zero Trust organization.", "type": "string", "example": "test.cloudflareaccess.com", "x-auditable": true }, "access_auth_domain-2": { "description": "The unique subdomain assigned to your Zero Trust organization.", "type": "string", "example": "test.cloudflareaccess.com" }, "access_authentication_method_rule": { "description": "Enforce different MFA options", "type": "object", "properties": { "auth_method": { "type": "object", "properties": { "auth_method": { "description": "The type of authentication method https://datatracker.ietf.org/doc/html/rfc8176#section-2.", "type": "string", "example": "mfa" } }, "required": [ "auth_method" ] } }, "required": [ "auth_method" ], "title": "Authentication method" }, "access_authenticator_device_aaguid": { "description": "A FIDO2 authenticator device AAGUID entry", "type": "object", "properties": { "aaguid": { "$ref": "#/components/schemas/access_aaguid" }, "name": { "$ref": "#/components/schemas/access_name-14" } }, "required": [ "aaguid", "name" ] }, "access_authenticator_id": { "description": "The unique identifier for the MFA device.", "type": "string", "example": "test-authenticator-id-123" }, "access_auto_redirect_to_identity": { "description": "When set to `true`, users skip the identity provider selection step during login.", "type": "boolean", "default": false, "x-auditable": true }, "access_auto_redirect_to_identity-2": { "description": "When set to `true`, users skip the identity provider selection step during login. You must specify only one identity provider in allowed_idps.", "type": "boolean", "default": false }, "access_azureAD": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider" }, { "properties": { "config": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_generic-oauth-config" }, { "$ref": "#/components/schemas/access_custom-claims-support" }, { "properties": { "conditional_access_enabled": { "description": "Should Cloudflare try to load authentication contexts from your account", "type": "boolean", "x-auditable": true }, "directory_id": { "description": "Your Azure directory uuid", "type": "string", "example": "", "x-auditable": true }, "prompt": { "description": "Indicates the type of user interaction that is required. prompt=login forces the user to enter their credentials on that request, negating single-sign on. prompt=none is the opposite. It ensures that the user isn't presented with any interactive prompt. If the request can't be completed silently by using single-sign on, the Microsoft identity platform returns an interaction_required error. prompt=select_account interrupts single sign-on providing account selection experience listing all the accounts either in session or any remembered account or an option to choose to use a different account altogether.", "type": "string", "enum": [ "login", "select_account", "none" ], "x-auditable": true }, "support_groups": { "description": "Should Cloudflare try to load groups from your account", "type": "boolean", "x-auditable": true } }, "type": "object" } ] } }, "type": "object" } ], "title": "Azure AD" }, "access_azureAD-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider-2" }, { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/access_generic-oauth-config-2" }, { "properties": { "conditional_access_enabled": { "description": "Should Cloudflare try to load authentication contexts from your account", "type": "boolean" }, "directory_id": { "description": "Your Azure directory uuid", "type": "string", "example": "" }, "prompt": { "description": "Indicates the type of user interaction that is required. prompt=login forces the user to enter their credentials on that request, negating single-sign on. prompt=none is the opposite. It ensures that the user isn't presented with any interactive prompt. If the request can't be completed silently by using single-sign on, the Microsoft identity platform returns an interaction_required error. prompt=select_account interrupts single sign-on providing account selection experience listing all the accounts either in session or any remembered account or an option to choose to use a different account altogether.", "type": "string", "enum": [ "login", "select_account", "none" ] }, "support_groups": { "description": "Should Cloudflare try to load groups from your account", "type": "boolean" } }, "type": "object" } ] } }, "type": "object" } ], "title": "Azure AD" }, "access_azure_group_rule": { "description": "Matches an Azure group.\nRequires an Azure identity provider.", "type": "object", "properties": { "azureAD": { "type": "object", "properties": { "id": { "description": "The ID of an Azure group.", "type": "string", "example": "aa0a4aab-672b-4bdb-bc33-a59f1130a11f" }, "identity_provider_id": { "description": "The ID of your Azure identity provider.", "type": "string", "example": "ea85612a-29c8-46c2-bacb-669d65136971" } }, "required": [ "id", "identity_provider_id" ] } }, "required": [ "azureAD" ], "title": "Azure group" }, "access_base_policy_req": { "type": "object", "properties": { "decision": { "$ref": "#/components/schemas/access_decision" }, "exclude": { "$ref": "#/components/schemas/access_exclude-2" }, "include": { "$ref": "#/components/schemas/access_include-2" }, "name": { "$ref": "#/components/schemas/access_name-9" }, "require": { "$ref": "#/components/schemas/access_require-2" } }, "required": [ "name", "decision", "include" ] }, "access_base_policy_resp": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/access_timestamp" }, "decision": { "$ref": "#/components/schemas/access_decision" }, "exclude": { "$ref": "#/components/schemas/access_exclude-2" }, "id": { "$ref": "#/components/schemas/access_uuid-2" }, "include": { "$ref": "#/components/schemas/access_include-2" }, "name": { "$ref": "#/components/schemas/access_name-9" }, "require": { "$ref": "#/components/schemas/access_require-2" }, "updated_at": { "$ref": "#/components/schemas/access_timestamp" } } }, "access_basic_app_response_props": { "type": "object", "properties": { "aud": { "$ref": "#/components/schemas/access_aud-2" }, "created_at": { "$ref": "#/components/schemas/access_created_at" }, "id": { "$ref": "#/components/schemas/access_uuid" }, "updated_at": { "$ref": "#/components/schemas/access_updated_at" } } }, "access_basic_app_response_props-2": { "type": "object", "properties": { "aud": { "$ref": "#/components/schemas/access_aud-2" }, "created_at": { "$ref": "#/components/schemas/access_timestamp" }, "id": { "$ref": "#/components/schemas/access_uuid" }, "scim_config": { "$ref": "#/components/schemas/access_scim_config-2" }, "updated_at": { "$ref": "#/components/schemas/access_timestamp" } } }, "access_bg_color": { "description": "The background color of the App Launcher page.", "type": "string", "example": "#ff0000" }, "access_biso_props": { "allOf": [ { "$ref": "#/components/schemas/access_feature_app_props" }, { "properties": { "domain": { "type": "string", "example": "authdomain.cloudflareaccess.com/browser", "readOnly": true }, "name": { "type": "string", "example": "Clientless Web Isolation", "default": "Clientless Web Isolation", "readOnly": true }, "type": { "allOf": [ { "$ref": "#/components/schemas/access_type" }, { "example": "biso", "type": "string" } ] } }, "type": "object" } ] }, "access_biso_props-2": { "allOf": [ { "$ref": "#/components/schemas/access_feature_app_props-2" }, { "properties": { "domain": { "type": "string", "example": "authdomain.cloudflareaccess.com/browser", "readOnly": true }, "name": { "type": "string", "example": "Clientless Web Isolation", "default": "Clientless Web Isolation", "readOnly": true }, "type": { "description": "The application type.", "type": "string", "example": "biso" } }, "type": "object" } ] }, "access_bookmark_props": { "type": "object", "properties": { "app_launcher_visible": { "$ref": "#/components/schemas/access_app_launcher_visible" }, "domain": { "description": "The URL or domain of the bookmark.", "type": "string", "example": "https://mybookmark.com" }, "logo_url": { "$ref": "#/components/schemas/access_logo_url" }, "name": { "$ref": "#/components/schemas/access_name-8" }, "tags": { "$ref": "#/components/schemas/access_tags" }, "type": { "allOf": [ { "$ref": "#/components/schemas/access_type" }, { "example": "bookmark", "type": "string" } ] } }, "title": "Bookmark application" }, "access_bookmark_props-2": { "type": "object", "properties": { "app_launcher_visible": { "type": "boolean", "default": true }, "domain": { "description": "The URL or domain of the bookmark.", "type": "string", "example": "https://mybookmark.com" }, "logo_url": { "$ref": "#/components/schemas/access_logo_url" }, "name": { "$ref": "#/components/schemas/access_name-8" }, "type": { "description": "The application type.", "type": "string", "example": "bookmark" } }, "required": [ "type", "domain" ], "title": "Bookmark Application" }, "access_bookmarks": { "type": "object", "properties": { "app_launcher_visible": { "$ref": "#/components/schemas/access_app_launcher_visible-2" }, "created_at": { "$ref": "#/components/schemas/access_created_at" }, "domain": { "$ref": "#/components/schemas/access_domain-2" }, "id": { "description": "The unique identifier for the Bookmark application.", "type": "string" }, "logo_url": { "$ref": "#/components/schemas/access_logo_url-2" }, "name": { "$ref": "#/components/schemas/access_name-12" }, "updated_at": { "$ref": "#/components/schemas/access_updated_at" } } }, "access_button_color": { "description": "The background color of the log in button on the landing page.", "type": "string", "example": "#ff0000" }, "access_button_text_color": { "description": "The color of the text in the log in button on the landing page.", "type": "string", "example": "#ff0000" }, "access_ca": { "type": "object", "properties": { "aud": { "$ref": "#/components/schemas/access_aud" }, "id": { "$ref": "#/components/schemas/access_id-2" }, "public_key": { "$ref": "#/components/schemas/access_public_key" } } }, "access_ca-2": { "type": "object", "properties": { "aud": { "$ref": "#/components/schemas/access_aud-3" }, "id": { "$ref": "#/components/schemas/access_id-3" }, "public_key": { "$ref": "#/components/schemas/access_public_key" } } }, "access_centrify": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider" }, { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/access_generic-oauth-config" }, { "$ref": "#/components/schemas/access_custom-claims-support" }, { "properties": { "centrify_account": { "description": "Your centrify account url", "type": "string", "example": "https://abc123.my.centrify.com/", "x-auditable": true }, "centrify_app_id": { "description": "Your centrify app id", "type": "string", "example": "exampleapp", "x-auditable": true } }, "type": "object" } ] } }, "type": "object" } ], "title": "Centrify" }, "access_centrify-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider-2" }, { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/access_generic-oauth-config-2" }, { "properties": { "centrify_account": { "description": "Your centrify account url", "type": "string", "example": "https://abc123.my.centrify.com/" }, "centrify_app_id": { "description": "Your centrify app id", "type": "string", "example": "exampleapp" } }, "type": "object" } ] } }, "type": "object" } ], "title": "Centrify" }, "access_certificate_rule": { "description": "Matches any valid client certificate.", "type": "object", "properties": { "certificate": { "type": "object", "example": {}, "x-stainless-empty-object": true } }, "example": { "certificate": {} }, "required": [ "certificate" ], "title": "Valid certificate" }, "access_certificate_set_list_response": { "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_saml_certificate_set-2" } } }, "type": "object" } ] }, "access_certificate_set_response": { "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_saml_certificate_set-2" } }, "type": "object" } ] }, "access_certificates": { "type": "object", "properties": { "associated_hostnames": { "$ref": "#/components/schemas/access_associated_hostnames" }, "created_at": { "$ref": "#/components/schemas/access_created_at" }, "expires_on": { "$ref": "#/components/schemas/access_timestamp" }, "fingerprint": { "$ref": "#/components/schemas/access_fingerprint" }, "id": { "description": "The ID of the application that will use this certificate.", "type": "string", "x-auditable": true }, "name": { "$ref": "#/components/schemas/access_name-7" }, "updated_at": { "$ref": "#/components/schemas/access_updated_at" } } }, "access_certificates-2": { "type": "object", "properties": { "id": { "description": "The key ID of this certificate.", "type": "string", "x-auditable": true }, "public_key": { "description": "The public key of this certificate.", "type": "string" } } }, "access_certificates-3": { "type": "object", "properties": { "associated_hostnames": { "$ref": "#/components/schemas/access_associated_hostnames-2" }, "created_at": { "$ref": "#/components/schemas/access_timestamp" }, "expires_on": { "$ref": "#/components/schemas/access_timestamp" }, "fingerprint": { "$ref": "#/components/schemas/access_fingerprint" }, "id": { "description": "The ID of the application that will use this certificate.", "type": "string" }, "name": { "$ref": "#/components/schemas/access_name-18" }, "updated_at": { "$ref": "#/components/schemas/access_timestamp" } } }, "access_cf_resource_id": { "description": "The unique Cloudflare-generated Id of the SCIM Group resource; also known as the \"Id\".\nPass once for a single lookup (`?cf_resource_id=A`) or repeat the parameter\n(`?cf_resource_id=A&cf_resource_id=B`) to look up multiple groups in one request,\nup to 50 values. Mutually exclusive with `idp_resource_id`, `name`,\n`search_contains`, and `search_starts_with`.", "type": "array", "items": { "type": "string" }, "example": [ "a2abeb50-59c9-4c01-8c5c-963d3bf5700f" ], "maxItems": 50 }, "access_cf_resource_id-2": { "description": "The unique Cloudflare-generated Id of the SCIM User resource; also known as the \"Id\".\nPass once for a single lookup (`?cf_resource_id=A`) or repeat the parameter\n(`?cf_resource_id=A&cf_resource_id=B`) to look up multiple users in one request,\nup to 50 values. Mutually exclusive with `idp_resource_id`, `username`, `email`,\n`name`, `search_contains`, and `search_starts_with`.", "type": "array", "items": { "type": "string" }, "example": [ "bd97ef8d-7986-43e3-9ee0-c25dda33e4b0" ], "maxItems": 50 }, "access_cf_resource_id-3": { "description": "The unique Cloudflare-generated Id of the SCIM resource. Pass once for\na single lookup (`?cf_resource_id=A`) or repeat the parameter\n(`?cf_resource_id=A&cf_resource_id=B`) to filter by multiple resources\nin one request.", "type": "array", "items": { "type": "string" }, "example": [ "bd97ef8d-7986-43e3-9ee0-c25dda33e4b0" ] }, "access_client_id": { "description": "The Client ID for the service token. Access will check for this value in the `CF-Access-Client-ID` request header.", "type": "string", "example": "88bf3b6d86161464f6509f7219099e57.access.example.com" }, "access_client_secret": { "description": "The Client Secret for the service token. Access will check for this value in the `CF-Access-Client-Secret` request header.", "type": "string", "example": "bdd31cbc4dec990953e39163fbbb194c93313ca9f0a6e420346af9d326b1d2a5", "x-sensitive": true }, "access_client_secret_version": { "description": "A version number identifying the current `client_secret` associated with the service token. Incrementing it triggers a rotation; the previous secret will still be accepted until the time indicated by `previous_client_secret_expires_at`.", "type": "number", "default": 1, "x-auditable": true }, "access_cloudflare": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider" }, { "properties": { "config": { "type": "object", "properties": { "redirect_url": { "type": "string", "readOnly": true }, "restrict_to_account_members": { "description": "When enabled, only users who are members of your Cloudflare account can authenticate through this identity provider. When disabled, any user with a Cloudflare account can authenticate, subject to your Access policies.", "type": "boolean", "default": false } } }, "type": { "type": "string", "enum": [ "cloudflare" ] } }, "type": "object" } ], "title": "Cloudflare" }, "access_cloudflare-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider-2" }, { "properties": { "config": { "type": "object", "properties": { "redirect_url": { "type": "string", "readOnly": true }, "restrict_to_account_members": { "description": "When enabled, only users who are members of your Cloudflare account can authenticate through this identity provider. When disabled, any user with a Cloudflare account can authenticate, subject to your Access policies.", "type": "boolean", "default": false } } }, "type": { "type": "string", "enum": [ "cloudflare" ] } }, "type": "object" } ], "title": "Cloudflare" }, "access_cloudflare_account_member_rule": { "description": "Matches users who are members of a specific Cloudflare account.\nRequires a Cloudflare identity provider.", "type": "object", "properties": { "cloudflare_account_member": { "type": "object", "properties": { "account_id": { "$ref": "#/components/schemas/access_identifier" } } } }, "required": [ "cloudflare_account_member" ], "title": "Cloudflare Account Member" }, "access_common_name_rule": { "description": "Matches a specific common name.", "type": "object", "properties": { "common_name": { "type": "object", "properties": { "common_name": { "description": "The common name to match.", "type": "string", "example": "james@example.com" } }, "required": [ "common_name" ] } }, "required": [ "common_name" ], "title": "Common Name" }, "access_connection": { "description": "The IdP used to authenticate.", "type": "string", "example": "saml" }, "access_connection_rules": { "description": "The rules that define how users may connect to targets secured by your application.", "type": "object", "properties": { "rdp": { "$ref": "#/components/schemas/access_connection_rules_rdp" } }, "title": "Connection Rules" }, "access_connection_rules_infra": { "description": "The rules that define how users may connect to the targets secured by your application.", "type": "object", "properties": { "ssh": { "$ref": "#/components/schemas/access_connection_rules_ssh" } }, "title": "Connection Rules" }, "access_connection_rules_rdp": { "description": "The RDP-specific rules that define clipboard behavior for RDP connections.", "type": "object", "properties": { "allowed_clipboard_local_to_remote_formats": { "$ref": "#/components/schemas/access_allowed_clipboard_local_to_remote_formats" }, "allowed_clipboard_remote_to_local_formats": { "$ref": "#/components/schemas/access_allowed_clipboard_remote_to_local_formats" } }, "title": "RDP Connection Rules" }, "access_connection_rules_ssh": { "description": "The SSH-specific rules that define how users may connect to the targets secured by your application.", "type": "object", "properties": { "allow_email_alias": { "$ref": "#/components/schemas/access_allow_email_alias" }, "usernames": { "$ref": "#/components/schemas/access_usernames" } }, "required": [ "usernames" ], "title": "SSH Connection Rules" }, "access_contract_version": { "description": "Contract version of the page's Liquid template. Present (>= 1) marks a sanitized template; absent or 0 marks a legacy page served verbatim.", "type": "integer", "x-auditable": true }, "access_cors_headers": { "type": "object", "properties": { "allow_all_headers": { "$ref": "#/components/schemas/access_allow_all_headers" }, "allow_all_methods": { "$ref": "#/components/schemas/access_allow_all_methods" }, "allow_all_origins": { "$ref": "#/components/schemas/access_allow_all_origins" }, "allow_credentials": { "$ref": "#/components/schemas/access_allow_credentials" }, "allowed_headers": { "$ref": "#/components/schemas/access_allowed_headers" }, "allowed_methods": { "$ref": "#/components/schemas/access_allowed_methods" }, "allowed_origins": { "$ref": "#/components/schemas/access_allowed_origins" }, "max_age": { "$ref": "#/components/schemas/access_max_age" } } }, "access_country_rule": { "description": "Matches a specific country", "type": "object", "properties": { "geo": { "type": "object", "properties": { "country_code": { "description": "The country code that should be matched.", "type": "string", "example": "US" } }, "required": [ "country_code" ] } }, "required": [ "geo" ], "title": "Country" }, "access_create_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "client_id": { "$ref": "#/components/schemas/access_client_id" }, "client_secret": { "$ref": "#/components/schemas/access_client_secret" }, "created_at": { "$ref": "#/components/schemas/access_created_at" }, "duration": { "$ref": "#/components/schemas/access_duration" }, "enabled": { "$ref": "#/components/schemas/access_enabled" }, "id": { "description": "The ID of the service token.", "type": "string" }, "name": { "$ref": "#/components/schemas/access_name-2" }, "updated_at": { "$ref": "#/components/schemas/access_updated_at" } } } }, "type": "object" } ] }, "access_create_response-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "client_id": { "$ref": "#/components/schemas/access_client_id" }, "client_secret": { "$ref": "#/components/schemas/access_client_secret" }, "created_at": { "$ref": "#/components/schemas/access_timestamp" }, "duration": { "$ref": "#/components/schemas/access_duration-2" }, "enabled": { "$ref": "#/components/schemas/access_enabled" }, "id": { "description": "The ID of the service token.", "type": "string" }, "name": { "$ref": "#/components/schemas/access_name-17" }, "updated_at": { "$ref": "#/components/schemas/access_timestamp" } } } }, "type": "object" } ] }, "access_created_at": { "allOf": [ { "type": "string", "x-stainless-skip": true }, { "$ref": "#/components/schemas/access_timestamp" } ] }, "access_custom-claims-support": { "type": "object", "properties": { "claims": { "description": "Custom claims", "type": "array", "items": { "type": "string" }, "example": [ "email_verified", "preferred_username", "custom_claim_name" ], "x-auditable": true }, "email_claim_name": { "description": "The claim name for email in the id_token response.", "type": "string", "example": "custom_claim_name", "x-auditable": true } } }, "access_custom_deny_message": { "description": "The custom error message shown to a user when they are denied access to the application.", "type": "string" }, "access_custom_deny_url": { "description": "The custom URL a user is redirected to when they are denied access to the application when failing identity-based rules.", "type": "string" }, "access_custom_deny_url-2": { "description": "The custom URL a user is redirected to when they are denied access to the application.", "type": "string" }, "access_custom_non_identity_deny_url": { "description": "The custom URL a user is redirected to when they are denied access to the application when failing non-identity rules.", "type": "string" }, "access_custom_page": { "type": "object", "properties": { "app_count": { "$ref": "#/components/schemas/access_app_count-2" }, "contract_version": { "$ref": "#/components/schemas/access_contract_version" }, "created_at": { "$ref": "#/components/schemas/access_created_at" }, "custom_html": { "description": "Custom page HTML.", "type": "string", "example": "

Access Denied

", "x-auditable": true }, "name": { "$ref": "#/components/schemas/access_name-11" }, "type": { "$ref": "#/components/schemas/access_type-2" }, "uid": { "$ref": "#/components/schemas/access_uuid" }, "updated_at": { "$ref": "#/components/schemas/access_updated_at" } }, "required": [ "name", "custom_html", "type" ] }, "access_custom_page_validate": { "description": "A template to validate without persisting it.", "type": "object", "properties": { "template": { "description": "The Liquid template to validate.", "type": "string", "x-auditable": true }, "type": { "$ref": "#/components/schemas/access_type-2" }, "version": { "description": "Contract version to validate against; omit for the latest.", "type": "integer", "x-auditable": true } }, "required": [ "type", "template" ] }, "access_custom_page_without_html": { "type": "object", "properties": { "app_count": { "$ref": "#/components/schemas/access_app_count-2" }, "contract_version": { "$ref": "#/components/schemas/access_contract_version" }, "created_at": { "$ref": "#/components/schemas/access_created_at" }, "name": { "$ref": "#/components/schemas/access_name-11" }, "type": { "$ref": "#/components/schemas/access_type-2" }, "uid": { "$ref": "#/components/schemas/access_uuid" }, "updated_at": { "$ref": "#/components/schemas/access_updated_at" }, "warnings": { "description": "Advisory validation findings returned when creating or updating a template. Omitted when empty.", "type": "array", "items": { "$ref": "#/components/schemas/access_template_violation" } } }, "required": [ "name", "type" ] }, "access_custom_pages": { "type": "object", "properties": { "forbidden": { "description": "The uid of the custom page to use when a user is denied access after failing a non-identity rule.", "type": "string", "example": "699d98642c564d2e855e9661899b7252" }, "identity_denied": { "description": "The uid of the custom page to use when a user is denied access.", "type": "string", "example": "699d98642c564d2e855e9661899b7252" } } }, "access_custom_pages-2": { "description": "The custom pages that will be displayed when applicable for this application", "type": "array", "items": { "description": "The custom pages selected for application.", "example": "699d98642c564d2e855e9661899b7252", "type": "string" } }, "access_days_until_next_rotation": { "description": "The number of days until the next key rotation.", "type": "number", "example": 1, "readOnly": true, "x-auditable": true }, "access_decision": { "description": "The action Access will take if a user matches this policy. Infrastructure application policies can only use the Allow action.", "type": "string", "example": "allow", "enum": [ "allow", "deny", "non_identity", "bypass" ] }, "access_decision-2": { "description": "The action Access will take if a user matches this policy.", "type": "string", "example": "allow", "enum": [ "allow", "deny", "non_identity", "bypass" ] }, "access_delete_authenticator_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, "access_delete_user_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, "access_deny_unmatched_requests": { "description": "Determines whether to deny all requests to Cloudflare-protected resources that lack an associated Access application. If enabled, you must explicitly configure an Access application and policy to allow traffic to your Cloudflare-protected resources. For domains you want to be public across all subdomains, add the domain to the `deny_unmatched_requests_exempted_zone_names` array.", "type": "boolean", "example": "true", "x-auditable": true }, "access_deny_unmatched_requests_exempted_zone_names": { "description": "Contains zone names to exempt from the `deny_unmatched_requests` feature. Requests to a subdomain in an exempted zone will block unauthenticated traffic by default if there is a configured Access application and policy that matches the request.", "type": "array", "items": { "type": "string" }, "example": [ "example.com" ], "x-auditable": true }, "access_destinations": { "description": "List of destinations secured by Access. This supersedes `self_hosted_domains` to allow for more flexibility in defining different types of domains. If `destinations` are provided, then `self_hosted_domains` will be ignored.\n", "type": "array", "items": { "oneOf": [ { "description": "A public hostname that Access will secure. Public destinations support sub-domain and path. Wildcard '*' can be used in the definition.\n", "properties": { "type": { "type": "string", "enum": [ "public" ] }, "uri": { "description": "The URI of the destination. Public destinations' URIs can include a domain and path with [wildcards](https://developers.cloudflare.com/cloudflare-one/policies/access/app-paths/).\n", "type": "string" } }, "title": "Public destination", "type": "object" }, { "properties": { "cidr": { "description": "The CIDR range of the destination. Single IPs will be computed as /32.", "type": "string" }, "hostname": { "description": "The hostname of the destination. Matches a valid SNI served by an HTTPS origin.", "type": "string" }, "l4_protocol": { "description": "The L4 protocol of the destination. When omitted, both UDP and TCP traffic will match.", "type": "string", "enum": [ "tcp", "udp" ] }, "port_range": { "description": "The port range of the destination. Can be a single port or a range of ports. When omitted, all ports will match.\n", "type": "string" }, "type": { "type": "string", "enum": [ "private" ] }, "vnet_id": { "description": "The VNET ID to match the destination. When omitted, all VNETs will match.", "type": "string" } }, "title": "Private destination", "type": "object" }, { "description": "A MCP server id configured in ai-controls. Access will secure the MCP server if accessed through a MCP portal.\n", "properties": { "mcp_server_id": { "description": "The MCP server id configured in ai-controls.", "type": "string" }, "type": { "type": "string", "enum": [ "via_mcp_server_portal" ] } }, "title": "Via MCP Server Portal destination", "type": "object" }, { "description": "A specific Cloudflare Worker that Access will secure. All requests routed to the specified Worker, including its preview deployments, will be protected. The `preview_worker` and `public` destination types takes precedence, so you can create separate applications to override the policies for the Worker's previews or specific paths.\n", "properties": { "type": { "type": "string", "enum": [ "worker" ] }, "worker_id": { "description": "The ID of the Cloudflare Worker to protect with Access.", "type": "string" } }, "required": [ "type", "worker_id" ], "title": "Worker destination", "type": "object" }, { "description": "A specific Cloudflare Worker whose preview deployments Access will secure. Only requests routed to the preview deployments of the specified Worker will be protected. The `public` destination type takes precedence, so you can create separate applications to override the policies for specific paths.\n", "properties": { "type": { "type": "string", "enum": [ "preview_worker" ] }, "worker_id": { "description": "The ID of the Cloudflare Worker whose preview deployments to protect with Access.", "type": "string" } }, "required": [ "type", "worker_id" ], "title": "Preview Worker destination", "type": "object" }, { "description": "Protects all Cloudflare Workers on the account with Access, including their preview deployments. At most one destination of this type can exist per account. The `worker`, `preview_worker`, `all_preview_workers`, and `public` destination types take precedence, so you can create separate applications to override the policies for specific Workers, their previews, or specific paths.\n", "properties": { "type": { "type": "string", "enum": [ "all_workers" ] } }, "required": [ "type" ], "title": "All Workers destination", "type": "object" }, { "description": "Protects the preview deployments of all Cloudflare Workers on the account with Access. At most one destination of this type can exist per account. The `worker`, `preview_worker`, and `public` destination types take precedence, so you can create separate applications to override the policies for specific Workers, their previews, or specific paths.\n", "properties": { "type": { "type": "string", "enum": [ "all_preview_workers" ] } }, "required": [ "type" ], "title": "All Preview Workers destination", "type": "object" } ] }, "example": [ { "type": "public", "uri": "test.example.com/admin" }, { "type": "public", "uri": "test.anotherexample.com/staff" }, { "cidr": "10.5.0.0/24", "port_range": "80-90", "type": "private" }, { "cidr": "10.5.0.3/32", "port_range": "80", "type": "private" }, { "hostname": "private-sni.example.com", "type": "private" }, { "mcp_server_id": "mcp-server-1", "type": "via_mcp_server_portal" }, { "type": "worker", "worker_id": "617f1d0431a98306ff61e336d79fce86" }, { "type": "preview_worker", "worker_id": "617f1d0431a98306ff61e336d79fce86" }, { "type": "all_workers" }, { "type": "all_preview_workers" } ], "default": [] }, "access_device_posture_check": { "type": "object", "properties": { "exists": { "type": "boolean", "x-auditable": true }, "path": { "type": "string", "x-auditable": true } } }, "access_device_posture_rule": { "description": "Enforces a device posture rule has run successfully", "type": "object", "properties": { "device_posture": { "type": "object", "properties": { "account_id": { "description": "The ID of the account that owns the device posture integration.", "allOf": [ { "$ref": "#/components/schemas/access_identifier" } ] }, "integration_uid": { "description": "The ID of a device posture integration.", "type": "string", "example": "aa0a4aab-672b-4bdb-bc33-a59f1130a11f" } }, "required": [ "integration_uid" ] } }, "required": [ "device_posture" ], "title": "Device Posture" }, "access_device_posture_rule-2": { "type": "object", "properties": { "check": { "$ref": "#/components/schemas/access_device_posture_check" }, "data": { "type": "object" }, "description": { "type": "string", "x-auditable": true }, "error": { "type": "string" }, "id": { "type": "string", "x-auditable": true }, "rule_name": { "type": "string", "x-auditable": true }, "success": { "type": "boolean", "x-auditable": true }, "timestamp": { "type": "string", "x-auditable": true }, "type": { "type": "string", "x-auditable": true } } }, "access_device_session": { "type": "object", "properties": { "last_authenticated": { "type": "number", "x-auditable": true } }, "example": { "last_authenticated": 1638832687 } }, "access_direction": { "description": "The chronological order used to sort the logs.", "type": "string", "example": "desc", "default": "desc", "enum": [ "desc", "asc" ] }, "access_doh_jwt_duration": { "description": "The duration the DoH JWT is valid for. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. Note that the maximum duration for this setting is the same as the key rotation period on the account. Default expiration is 24h", "type": "string", "example": "800h", "x-auditable": true }, "access_domain": { "description": "The primary hostname and path secured by Access. This domain will be displayed if the app is visible in the App Launcher.", "type": "string", "example": "test.example.com/admin" }, "access_domain-2": { "description": "The domain of the Bookmark application.", "type": "string", "example": "example.com", "x-auditable": true }, "access_domain-3": { "description": "The domain and path that Access will secure.", "type": "string", "example": "test.example.com/admin" }, "access_domain_rule": { "description": "Match an entire email domain.", "type": "object", "properties": { "email_domain": { "type": "object", "properties": { "domain": { "description": "The email domain to match.", "type": "string", "example": "example.com" } }, "required": [ "domain" ] } }, "required": [ "email_domain" ], "title": "Email domain" }, "access_duration": { "description": "The duration for how long the service token will be valid. Must be in the format `300ms` or `2h45m`, or the special value `forever` for non-expiring tokens. Valid time units are: ns, us (or µs), ms, s, m, h. The default is 1 year in hours (8760h).", "type": "string", "example": "60m", "default": "8760h", "x-auditable": true }, "access_duration-2": { "description": "The duration for how long the service token will be valid. Must be in the format `300ms` or `2h45m`, or the special value `forever` for non-expiring tokens. Valid time units are: ns, us (or µs), ms, s, m, h. The default is 1 year in hours (8760h).", "type": "string", "example": "60m", "default": "8760h" }, "access_eager_redirect_cookie_setting": { "description": "Preemptively sets the Access session cookie on every hostname in a multi-hostname self-hosted application during the initial redirect chain, rather than setting it lazily on first visit. Defaults to true. Set to false to disable the eager redirect cookie behavior.", "type": "boolean", "example": true, "default": true }, "access_email": { "description": "The email address of the SCIM User resource.", "type": "string", "example": "john.smith@example.com" }, "access_email-2": { "description": "The email of the user.", "type": "string", "format": "email", "example": "jdoe@example.com" }, "access_email-3": { "description": "The email address of the authenticating user.", "type": "string", "format": "email", "example": "user@example.com" }, "access_email_list_rule": { "description": "Matches an email address from a list.", "type": "object", "properties": { "email_list": { "type": "object", "properties": { "id": { "description": "The ID of a previously created email list.", "type": "string", "example": "aa0a4aab-672b-4bdb-bc33-a59f1130a11f" } }, "required": [ "id" ] } }, "required": [ "email_list" ], "title": "Email list" }, "access_email_rule": { "description": "Matches a specific email.", "type": "object", "properties": { "email": { "type": "object", "properties": { "email": { "description": "The email of the user.", "type": "string", "format": "email", "example": "test@example.com" } }, "required": [ "email" ] } }, "required": [ "email" ], "title": "Email" }, "access_empty_response": { "type": "object", "allOf": [ { "properties": { "result": { "type": "boolean", "example": true, "enum": [ true, false ] }, "success": { "type": "boolean", "example": true, "enum": [ true, false ] } }, "type": "object" } ] }, "access_empty_response-2": { "type": "object", "allOf": [ { "properties": { "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "example": true, "enum": [ true, false ] } }, "type": "object" } ] }, "access_enable_binding_cookie": { "description": "Enables the binding cookie, which increases security against compromised authorization tokens and CSRF attacks.", "type": "boolean", "default": false }, "access_enabled": { "description": "Whether the service token is enabled. A disabled service token cannot be used to authenticate; both its current and previous `client_secret` stop being accepted, but the token itself is preserved and can be re-enabled at any time. Defaults to enabled when omitted on create.", "type": "boolean", "x-auditable": true }, "access_everyone_rule": { "description": "Matches everyone.", "type": "object", "properties": { "everyone": { "description": "An empty object which matches on all users.", "type": "object", "example": {}, "x-stainless-empty-object": true } }, "required": [ "everyone" ], "title": "Everyone" }, "access_exclude": { "description": "Rules evaluated with a NOT logical operator. To match a policy, a user cannot meet any of the Exclude rules.", "type": "array", "items": { "$ref": "#/components/schemas/access_rule" } }, "access_exclude-2": { "description": "Rules evaluated with a NOT logical operator. To match the policy, a user cannot meet any of the Exclude rules.", "type": "array", "items": { "$ref": "#/components/schemas/access_rule" }, "default": [], "x-stainless-collection-type": "set" }, "access_exclude-3": { "description": "Rules evaluated with a NOT logical operator. To match the policy, a user cannot meet any of the Exclude rules.", "type": "array", "items": { "$ref": "#/components/schemas/access_rule" } }, "access_externalId": { "description": "The IdP-generated Id of the SCIM resource.", "type": "string", "example": "all_employees" }, "access_external_evaluation_rule": { "description": "Create Allow or Block policies which evaluate the user based on custom criteria.", "type": "object", "properties": { "external_evaluation": { "type": "object", "properties": { "evaluate_url": { "description": "The API endpoint containing your business logic.", "type": "string", "example": "https://eval.example.com" }, "keys_url": { "description": "The API endpoint containing the key that Access uses to verify that the response came from your API.", "type": "string", "example": "https://eval.example.com/keys" } }, "required": [ "evaluate_url", "keys_url" ] } }, "required": [ "external_evaluation" ], "title": "External Evaluation" }, "access_facebook": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider" }, { "properties": { "config": { "$ref": "#/components/schemas/access_generic-oauth-config" } }, "type": "object" } ], "title": "Facebook" }, "access_facebook-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider-2" }, { "properties": { "config": { "$ref": "#/components/schemas/access_generic-oauth-config-2" } }, "type": "object" } ], "title": "Facebook" }, "access_failed_login_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "properties": { "expiration": { "type": "integer" }, "metadata": { "type": "object", "example": { "app_name": "Test App", "aud": "39691c1480a2352a18ece567debc2b32552686cbd38eec0887aa18d5d3f00c04", "datetime": "2022-02-02T21:54:34.914Z", "ray_id": "6d76a8a42ead4133", "user_email": "test@cloudflare.com", "user_uuid": "57171132-e453-4ee8-b2a5-8cbaad333207" } } }, "type": "object" } } }, "type": "object" } ] }, "access_feature_app_props": { "type": "object", "properties": { "allowed_idps": { "$ref": "#/components/schemas/access_allowed_idps" }, "auto_redirect_to_identity": { "$ref": "#/components/schemas/access_auto_redirect_to_identity-2" }, "custom_deny_url": { "$ref": "#/components/schemas/access_custom_deny_url" }, "custom_non_identity_deny_url": { "$ref": "#/components/schemas/access_custom_non_identity_deny_url" }, "custom_pages": { "$ref": "#/components/schemas/access_custom_pages-2" }, "domain": { "$ref": "#/components/schemas/access_domain" }, "name": { "$ref": "#/components/schemas/access_name-8" }, "session_duration": { "$ref": "#/components/schemas/access_session_duration-2" }, "type": { "$ref": "#/components/schemas/access_type" } }, "required": [ "type" ] }, "access_feature_app_props-2": { "type": "object", "properties": { "allowed_idps": { "$ref": "#/components/schemas/access_allowed_idps" }, "auto_redirect_to_identity": { "$ref": "#/components/schemas/access_auto_redirect_to_identity-2" }, "domain": { "$ref": "#/components/schemas/access_domain-3" }, "name": { "$ref": "#/components/schemas/access_name-8" }, "session_duration": { "$ref": "#/components/schemas/access_session_duration-4" }, "type": { "$ref": "#/components/schemas/access_type-3" } }, "required": [ "type" ] }, "access_fingerprint": { "description": "The MD5 fingerprint of the certificate.", "type": "string", "example": "MD5 Fingerprint=1E:80:0F:7A:FD:31:55:96:DE:D5:CB:E2:F0:91:F6:91" }, "access_footer_links": { "description": "The links in the App Launcher footer.", "type": "array", "items": { "properties": { "name": { "description": "The hypertext in the footer link.", "type": "string", "example": "Cloudflare's Privacy Policy" }, "url": { "description": "the hyperlink in the footer link.", "type": "string", "example": "https://www.cloudflare.com/privacypolicy/" } }, "required": [ "name", "url" ], "type": "object" }, "example": [ { "name": "Cloudflare's Privacy Policy", "url": "https://www.cloudflare.com/privacypolicy/" } ] }, "access_gateway_seat": { "description": "True if the seat is part of Gateway.", "type": "boolean", "example": false, "x-auditable": true }, "access_gateway_seat-2": { "description": "True if the user has logged into the WARP client.", "type": "boolean", "example": false }, "access_generic-oauth-config": { "type": "object", "properties": { "client_id": { "description": "Your OAuth Client ID", "type": "string", "example": "" }, "client_secret": { "description": "Your OAuth Client Secret", "type": "string", "example": "", "x-sensitive": true } } }, "access_generic-oauth-config-2": { "type": "object", "properties": { "client_id": { "description": "Your OAuth Client ID", "type": "string", "example": "" }, "client_secret": { "description": "Your OAuth Client Secret", "type": "string", "example": "", "writeOnly": true, "x-sensitive": true } } }, "access_geo": { "type": "object", "properties": { "country": { "type": "string", "x-auditable": true } }, "example": { "country": "US" } }, "access_get_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "allOf": [ { "$ref": "#/components/schemas/access_organizations" }, { "properties": { "trusted_accounts": { "description": "The account tags of organizations trusted by this organization for policy and device posture sharing.", "type": "array", "items": { "type": "string" }, "example": [ "023e105f4ecef8ad9ca31a8372d0c353" ], "readOnly": true } }, "type": "object" } ] } }, "type": "object" } ] }, "access_get_response-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "allOf": [ { "$ref": "#/components/schemas/access_organizations-2" }, { "properties": { "trusted_accounts": { "description": "The account tags of organizations trusted by this organization for policy and device posture sharing.", "type": "array", "items": { "type": "string" }, "example": [ "023e105f4ecef8ad9ca31a8372d0c353" ], "readOnly": true } }, "type": "object" } ] } }, "type": "object" } ] }, "access_github": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider" }, { "properties": { "config": { "$ref": "#/components/schemas/access_generic-oauth-config" } }, "type": "object" } ], "title": "GitHub" }, "access_github-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider-2" }, { "properties": { "config": { "$ref": "#/components/schemas/access_generic-oauth-config-2" } }, "type": "object" } ], "title": "GitHub" }, "access_github_organization_rule": { "description": "Matches a Github organization.\nRequires a Github identity provider.", "type": "object", "properties": { "github-organization": { "type": "object", "properties": { "identity_provider_id": { "description": "The ID of your Github identity provider.", "type": "string", "example": "ea85612a-29c8-46c2-bacb-669d65136971" }, "name": { "description": "The name of the organization.", "type": "string", "example": "cloudflare" }, "team": { "description": "The name of the team", "type": "string", "example": "api-team" } }, "required": [ "name", "identity_provider_id" ] } }, "required": [ "github-organization" ], "title": "Github organization" }, "access_google": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider" }, { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/access_generic-oauth-config" }, { "$ref": "#/components/schemas/access_custom-claims-support" } ] } }, "type": "object" } ], "title": "Google" }, "access_google-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider-2" }, { "properties": { "config": { "$ref": "#/components/schemas/access_generic-oauth-config-2" } }, "type": "object" } ], "title": "Google" }, "access_google-apps": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider" }, { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/access_generic-oauth-config" }, { "$ref": "#/components/schemas/access_custom-claims-support" }, { "properties": { "apps_domain": { "description": "Your companies TLD", "type": "string", "example": "mycompany.com" }, "prompt": { "description": "Configures the prompt behavior for Google authentication.", "type": "string", "example": "select_account", "enum": [ "none", "consent", "select_account" ], "x-auditable": true }, "use_login_hint": { "description": "Whether to use a previously authenticated Access email as a Google login hint when exactly one email matches the Workspace domain.", "type": "boolean", "example": true, "x-auditable": true } }, "type": "object" } ] } }, "type": "object" } ], "title": "Google Workspace" }, "access_google-apps-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider-2" }, { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/access_generic-oauth-config-2" }, { "properties": { "apps_domain": { "description": "Your companies TLD", "type": "string", "example": "mycompany.com" }, "prompt": { "description": "Configures the prompt behavior for Google authentication.", "type": "string", "example": "select_account", "enum": [ "none", "consent", "select_account" ] }, "use_login_hint": { "description": "Whether to use a previously authenticated Access email as a Google login hint when exactly one email matches the Workspace domain.", "type": "boolean", "example": true } }, "type": "object" } ] } }, "type": "object" } ], "title": "Google Workspace" }, "access_groups": { "type": "object", "properties": { "displayName": { "description": "The display name of the SCIM Group resource.", "type": "string", "example": "ALL EMPLOYEES" }, "externalId": { "$ref": "#/components/schemas/access_externalId" }, "id": { "$ref": "#/components/schemas/access_id" }, "meta": { "$ref": "#/components/schemas/access_meta" }, "schemas": { "description": "The list of URIs which indicate the attributes contained within a SCIM resource.", "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ] } } }, "access_groups-2": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/access_created_at" }, "exclude": { "$ref": "#/components/schemas/access_exclude" }, "id": { "$ref": "#/components/schemas/access_uuid" }, "include": { "$ref": "#/components/schemas/access_include" }, "is_default": { "$ref": "#/components/schemas/access_require" }, "name": { "$ref": "#/components/schemas/access_name-6" }, "require": { "$ref": "#/components/schemas/access_require" }, "updated_at": { "$ref": "#/components/schemas/access_updated_at" } } }, "access_groups-3": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/access_timestamp" }, "exclude": { "$ref": "#/components/schemas/access_exclude" }, "id": { "$ref": "#/components/schemas/access_uuid" }, "include": { "$ref": "#/components/schemas/access_include" }, "name": { "$ref": "#/components/schemas/access_name-16" }, "require": { "$ref": "#/components/schemas/access_require" }, "updated_at": { "$ref": "#/components/schemas/access_timestamp" } } }, "access_gsuite_group_rule": { "description": "Matches a group in Google Workspace.\nRequires a Google Workspace identity provider.", "type": "object", "properties": { "gsuite": { "type": "object", "properties": { "email": { "description": "The email of the Google Workspace group.", "type": "string", "example": "devs@cloudflare.com" }, "identity_provider_id": { "description": "The ID of your Google Workspace identity provider.", "type": "string", "example": "ea85612a-29c8-46c2-bacb-669d65136971" } }, "required": [ "email", "identity_provider_id" ] } }, "required": [ "gsuite" ], "title": "Google Workspace group" }, "access_header_bg_color": { "description": "The background color of the App Launcher header.", "type": "string", "example": "#ff0000" }, "access_http_only_cookie_attribute": { "description": "Enables the HttpOnly cookie attribute, which increases security against XSS attacks.", "type": "boolean", "example": true, "default": true }, "access_id": { "description": "The unique Cloudflare-generated Id of the SCIM resource.", "type": "string", "example": "bd97ef8d-7986-43e3-9ee0-c25dda33e4b0" }, "access_id-2": { "description": "The ID of the CA.", "type": "string", "example": "7eddae4619b50ab1361ba8ae9bd72269a432fea041529ed9", "maxLength": 48, "readOnly": true, "x-auditable": true }, "access_id-3": { "description": "The ID of the CA.", "type": "string", "example": "7eddae4619b50ab1361ba8ae9bd72269a432fea041529ed9", "maxLength": 48, "readOnly": true }, "access_id_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/access_uuid" } } } }, "type": "object" } ] }, "access_id_response-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/access_id-2" } } } }, "type": "object" } ] }, "access_id_response-3": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/access_uuid" } } } }, "type": "object" } ] }, "access_id_response-4": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/access_uuid-2" } } } }, "type": "object" } ] }, "access_id_response-5": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/access_id-3" } } } }, "type": "object" } ] }, "access_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "access_identifier-2": { "allOf": [ { "$ref": "#/components/schemas/access_identifier" }, { "example": "699d98642c564d2e855e9661899b7252", "type": "string" } ] }, "access_identifier-3": { "type": "string", "example": "699d98642c564d2e855e9661899b7252", "x-auditable": true }, "access_identifier-4": { "type": "string", "example": "699d98642c564d2e855e9661899b7252" }, "access_identity": { "type": "object", "properties": { "account_id": { "type": "string", "example": "1234567890", "x-auditable": true }, "auth_status": { "type": "string", "example": "NONE", "x-auditable": true }, "common_name": { "type": "string", "example": "" }, "devicePosture": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/access_device_posture_rule-2" } }, "device_id": { "type": "string", "example": "" }, "device_sessions": { "$ref": "#/components/schemas/access_string_key_map_device_session" }, "email": { "type": "string", "example": "test@cloudflare.com" }, "geo": { "$ref": "#/components/schemas/access_geo" }, "iat": { "type": "number", "example": 1694791905 }, "idp": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } } }, "ip": { "type": "string", "example": "127.0.0.0" }, "is_gateway": { "type": "boolean", "example": false }, "is_warp": { "type": "boolean", "example": false }, "mtls_auth": { "type": "object", "properties": { "auth_status": { "type": "string" }, "cert_issuer_dn": { "type": "string" }, "cert_issuer_ski": { "type": "string" }, "cert_presented": { "type": "boolean" }, "cert_serial": { "type": "string" } } }, "service_token_id": { "type": "string", "example": "" }, "service_token_status": { "type": "boolean", "example": false }, "user_uuid": { "type": "string", "example": "57cf8cf2-f55a-4588-9ac9-f5e41e9f09b4" }, "version": { "type": "number", "example": 2 } } }, "access_identity-provider": { "type": "object", "properties": { "config": { "description": "The configuration parameters for the identity provider. To view the required parameters for a specific provider, refer to our [developer documentation](https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/).", "type": "object" }, "id": { "$ref": "#/components/schemas/access_uuid" }, "name": { "$ref": "#/components/schemas/access_name-3" }, "read_only": { "description": "Indicates that the identity provider is immutable and cannot be updated or deleted via the API.\n", "type": "boolean", "example": true, "readOnly": true }, "saml_certificate_set": { "description": "The SAML encryption certificate set details, including current and previous certificates.\nOnly present for SAML identity providers with a certificate set assigned.\n", "allOf": [ { "$ref": "#/components/schemas/access_saml_certificate_set" } ], "readOnly": true }, "saml_certificate_set_id": { "description": "The UID of the SAML encryption certificate set assigned to this Identity Provider.\nOnly present for SAML identity providers with encryption configured.\nCreate a certificate set via POST to `/identity_providers/{id}/saml_certificate`.\n", "type": "string", "format": "uuid", "example": "c409ef44-e72c-41c8-8c0b-278c8a6f4fd8" }, "scim_config": { "description": "The configuration settings for enabling a System for Cross-Domain Identity Management (SCIM) with the identity provider.", "type": "object", "properties": { "enabled": { "description": "A flag to enable or disable SCIM for the identity provider.", "type": "boolean", "default": false, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "identity_update_behavior": { "description": "Indicates how a SCIM event updates a user identity used for policy evaluation. Use \"automatic\" to automatically update a user's identity and augment it with fields from the SCIM user resource. Use \"reauth\" to force re-authentication on group membership updates, user identity update will only occur after successful re-authentication. With \"reauth\" identities will not contain fields from the SCIM user resource. With \"no_action\" identities will not be changed by SCIM updates in any way and users will not be prompted to reauthenticate.", "type": "string", "default": "no_action", "enum": [ "automatic", "reauth", "no_action" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "scim_base_url": { "description": "The base URL of Cloudflare's SCIM V2.0 API endpoint.", "type": "string", "readOnly": true, "x-auditable": true }, "seat_deprovision": { "description": "A flag to remove a user's seat in Zero Trust when they have been deprovisioned in the Identity Provider. This cannot be enabled unless user_deprovision is also enabled.", "type": "boolean", "default": false, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "secret": { "description": "A read-only token generated when the SCIM integration is enabled for the first time. It is redacted on subsequent requests. If you lose this you will need to refresh it at /access/identity_providers/:idpID/refresh_scim_secret.", "type": "string", "readOnly": true, "x-sensitive": true }, "user_deprovision": { "description": "A flag to enable revoking a user's session in Access and Gateway when they have been deprovisioned in the Identity Provider.", "type": "boolean", "default": false, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } } }, "type": { "description": "The type of identity provider. To determine the value for a specific provider, refer to our [developer documentation](https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/).", "type": "string", "example": "onetimepin", "enum": [ "onetimepin", "azureAD", "saml", "centrify", "facebook", "github", "google-apps", "google", "linkedin", "oidc", "okta", "onelogin", "pingone", "yandex", "cloudflare" ] } }, "required": [ "name", "type", "config" ] }, "access_identity-provider-2": { "type": "object", "properties": { "config": { "description": "The configuration parameters for the identity provider. To view the required parameters for a specific provider, refer to our [developer documentation](https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/).", "type": "object" }, "id": { "$ref": "#/components/schemas/access_uuid" }, "name": { "$ref": "#/components/schemas/access_name-3" }, "scim_config": { "description": "The configuration settings for enabling a System for Cross-Domain Identity Management (SCIM) with the identity provider.", "type": "object", "properties": { "enabled": { "description": "A flag to enable or disable SCIM for the identity provider.", "type": "boolean", "default": false, "x-stainless-terraform-configurability": "computed_optional" }, "identity_update_behavior": { "description": "Indicates how a SCIM event updates a user identity used for policy evaluation. Use \"automatic\" to automatically update a user's identity and augment it with fields from the SCIM user resource. Use \"reauth\" to force re-authentication on group membership updates, user identity update will only occur after successful re-authentication. With \"reauth\" identities will not contain fields from the SCIM user resource. With \"no_action\" identities will not be changed by SCIM updates in any way and users will not be prompted to reauthenticate.", "type": "string", "default": "no_action", "enum": [ "automatic", "reauth", "no_action" ], "x-stainless-terraform-configurability": "computed_optional" }, "scim_base_url": { "description": "The base URL of Cloudflare's SCIM V2.0 API endpoint.", "type": "string", "readOnly": true }, "seat_deprovision": { "description": "A flag to remove a user's seat in Zero Trust when they have been deprovisioned in the Identity Provider. This cannot be enabled unless user_deprovision is also enabled.", "type": "boolean", "default": false, "x-stainless-terraform-configurability": "computed_optional" }, "secret": { "description": "A read-only token generated when the SCIM integration is enabled for the first time. It is redacted on subsequent requests. If you lose this you will need to refresh it at /access/identity_providers/:idpID/refresh_scim_secret.", "type": "string", "readOnly": true, "x-sensitive": true }, "user_deprovision": { "description": "A flag to enable revoking a user's session in Access and Gateway when they have been deprovisioned in the Identity Provider.", "type": "boolean", "default": false, "x-stainless-terraform-configurability": "computed_optional" } } }, "type": { "description": "The type of identity provider. To determine the value for a specific provider, refer to our [developer documentation](https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/).", "type": "string", "example": "onetimepin", "enum": [ "onetimepin", "azureAD", "saml", "centrify", "facebook", "github", "google-apps", "google", "linkedin", "oidc", "okta", "onelogin", "pingone", "yandex", "cloudflare" ] } }, "required": [ "name", "type", "config" ] }, "access_identity-providers": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/access_azureAD" }, { "$ref": "#/components/schemas/access_centrify" }, { "$ref": "#/components/schemas/access_facebook" }, { "$ref": "#/components/schemas/access_github" }, { "$ref": "#/components/schemas/access_google" }, { "$ref": "#/components/schemas/access_google-apps" }, { "$ref": "#/components/schemas/access_linkedin" }, { "$ref": "#/components/schemas/access_oidc" }, { "$ref": "#/components/schemas/access_okta" }, { "$ref": "#/components/schemas/access_onelogin" }, { "$ref": "#/components/schemas/access_pingone" }, { "$ref": "#/components/schemas/access_saml" }, { "$ref": "#/components/schemas/access_yandex" }, { "$ref": "#/components/schemas/access_onetimepin" }, { "$ref": "#/components/schemas/access_cloudflare" } ] }, "access_identity-providers-2": { "anyOf": [ { "$ref": "#/components/schemas/access_azureAD-2" }, { "$ref": "#/components/schemas/access_centrify-2" }, { "$ref": "#/components/schemas/access_facebook-2" }, { "$ref": "#/components/schemas/access_github-2" }, { "$ref": "#/components/schemas/access_google-2" }, { "$ref": "#/components/schemas/access_google-apps-2" }, { "$ref": "#/components/schemas/access_linkedin-2" }, { "$ref": "#/components/schemas/access_oidc-2" }, { "$ref": "#/components/schemas/access_okta-2" }, { "$ref": "#/components/schemas/access_onelogin-2" }, { "$ref": "#/components/schemas/access_pingone-2" }, { "$ref": "#/components/schemas/access_saml-2" }, { "$ref": "#/components/schemas/access_yandex-2" }, { "$ref": "#/components/schemas/access_cloudflare-2" } ] }, "access_idp_federation_grant": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/access_created_at" }, "id": { "description": "UID of the IdP federation grant.", "allOf": [ { "$ref": "#/components/schemas/access_identifier" } ], "readOnly": true, "x-auditable": true }, "idp_id": { "description": "UID of the identity provider being federated.", "type": "string", "format": "uuid", "example": "a79de439-0e7f-4ebb-8a02-222222222222", "x-auditable": true } }, "required": [ "id", "idp_id", "created_at" ] }, "access_idp_federation_grant_create_request": { "type": "object", "properties": { "idp_id": { "description": "UID of the identity provider to federate. Must be an existing identity provider in this account. One-time pin and Cloudflare-managed identity providers cannot be federated.", "type": "string", "format": "uuid", "example": "a79de439-0e7f-4ebb-8a02-222222222222", "x-auditable": true } }, "required": [ "idp_id" ] }, "access_idp_federation_grant_id_response": { "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "description": "UID of the deleted IdP federation grant.", "allOf": [ { "$ref": "#/components/schemas/access_identifier" } ] } } } }, "type": "object" } ] }, "access_idp_federation_grant_list_response": { "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_idp_federation_grant" } } }, "type": "object" } ] }, "access_idp_federation_grant_response": { "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_idp_federation_grant" } }, "type": "object" } ] }, "access_idp_id": { "description": "The unique Id of the IdP that has SCIM enabled.", "type": "array", "items": { "type": "string" }, "example": [ "df7e2w5f-02b7-4d9d-af26-8d1988fca630", "0194ae2c-efcf-7cfb-8884-055f1a161fa5" ] }, "access_idp_resource_id": { "description": "The IdP-generated Id of the SCIM Group resource; also known as the \"external Id\".\nPass once for a single lookup (`?idp_resource_id=A`) or repeat the parameter\n(`?idp_resource_id=A&idp_resource_id=B`) to look up multiple groups in one request,\nup to 50 values. Mutually exclusive with `cf_resource_id`, `name`,\n`search_contains`, and `search_starts_with`.", "type": "array", "items": { "type": "string" }, "example": [ "all_employees" ], "maxItems": 50 }, "access_idp_resource_id-2": { "description": "The IdP-generated Id of the SCIM User resource; also known as the \"external Id\".\nPass once for a single lookup (`?idp_resource_id=A`) or repeat the parameter\n(`?idp_resource_id=A&idp_resource_id=B`) to look up multiple users in one request,\nup to 50 values. Mutually exclusive with `cf_resource_id`, `username`, `email`,\n`name`, `search_contains`, and `search_starts_with`.", "type": "array", "items": { "type": "string" }, "example": [ "john_smith_01" ], "maxItems": 50 }, "access_idp_resource_id-3": { "description": "The IdP-generated Id of the SCIM resource. Pass once for a single\nlookup (`?idp_resource_id=A`) or repeat the parameter\n(`?idp_resource_id=A&idp_resource_id=B`) to filter by multiple\nresources in one request.", "type": "array", "items": { "type": "string" }, "example": [ "all_employees" ] }, "access_image_url": { "description": "The URL of the image shown on the landing page.", "type": "string", "example": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg" }, "access_include": { "description": "Rules evaluated with an OR logical operator. A user needs to meet only one of the Include rules.", "type": "array", "items": { "$ref": "#/components/schemas/access_rule" } }, "access_include-2": { "description": "Rules evaluated with an OR logical operator. A user needs to meet only one of the Include rules.", "type": "array", "items": { "$ref": "#/components/schemas/access_rule" }, "default": [], "x-stainless-collection-type": "set" }, "access_infra_app_req_embedded_policies": { "type": "object", "properties": { "policies": { "description": "The policies that Access applies to the application.", "type": "array", "items": { "$ref": "#/components/schemas/access_infra_policy_req" } } } }, "access_infra_app_resp_embedded_policies": { "description": "The policies that Access applies to the application.", "type": "object", "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/access_infra_policy_resp" } } } }, "access_infra_mfa_config": { "description": "Configures multi-factor authentication (MFA) settings for infrastructure applications.", "type": "object", "properties": { "allowed_authenticators": { "description": "Lists the MFA methods that users can authenticate with. For infrastructure applications, supported values are `piv_key` and `ssh_fido2_key`.", "type": "array", "items": { "enum": [ "piv_key", "ssh_fido2_key" ], "type": "string" }, "example": [ "piv_key", "ssh_fido2_key" ] }, "mfa_disabled": { "description": "Indicates whether to disable MFA for this resource. This option is available at the application and policy level.", "type": "boolean", "example": false }, "session_duration": { "description": "Defines the duration of an MFA session. Must be in minutes (m) or hours (h). Minimum: 0m. Maximum: 720h (30 days). Examples: `5m` or `24h`.", "type": "string", "example": "24h" } }, "x-auditable": true }, "access_infra_policy_req": { "type": "object", "properties": { "connection_rules": { "$ref": "#/components/schemas/access_connection_rules_infra" }, "mfa_config": { "$ref": "#/components/schemas/access_infra_mfa_config" } }, "allOf": [ { "$ref": "#/components/schemas/access_base_policy_req" } ] }, "access_infra_policy_resp": { "type": "object", "properties": { "connection_rules": { "$ref": "#/components/schemas/access_connection_rules_infra" }, "mfa_config": { "$ref": "#/components/schemas/access_infra_mfa_config" } }, "allOf": [ { "$ref": "#/components/schemas/access_base_policy_resp" } ] }, "access_infra_props": { "type": "object", "allOf": [ { "properties": { "mfa_config": { "$ref": "#/components/schemas/access_infra_mfa_config" }, "name": { "$ref": "#/components/schemas/access_name-8" }, "type": { "allOf": [ { "$ref": "#/components/schemas/access_type" }, { "example": "infrastructure", "type": "string" } ] } }, "type": "object" }, { "$ref": "#/components/schemas/access_app_resp_embedded_target_criteria_infra" } ], "required": [ "type", "target_criteria" ], "title": "Infrastructure Application" }, "access_ip": { "description": "The IP address of the authenticating user.", "type": "string", "example": "198.41.129.166" }, "access_ip_list_rule": { "description": "Matches an IP address from a list.", "type": "object", "properties": { "ip_list": { "type": "object", "properties": { "id": { "description": "The ID of a previously created IP list.", "type": "string", "example": "aa0a4aab-672b-4bdb-bc33-a59f1130a11f" } }, "required": [ "id" ] } }, "required": [ "ip_list" ], "title": "IP list" }, "access_ip_rule": { "description": "Matches an IP address block.", "type": "object", "properties": { "ip": { "type": "object", "properties": { "ip": { "description": "An IPv4 or IPv6 CIDR block.", "type": "string", "example": "2400:cb00:21:10a::/64" } }, "required": [ "ip" ] } }, "required": [ "ip" ], "title": "IP ranges" }, "access_is_default": { "description": "Whether this is the default group", "type": "boolean", "x-auditable": true }, "access_is_ui_read_only": { "description": "Lock all settings as Read-Only in the Dashboard, regardless of user permission. Updates may only be made via the API or Terraform for this account when enabled.", "type": "boolean", "example": "false", "default": false, "x-auditable": true }, "access_is_ui_read_only-2": { "description": "Lock all settings as Read-Only in the Dashboard, regardless of user permission. Updates may only be made via the API or Terraform for this account when enabled.", "type": "boolean", "example": "false" }, "access_isolation_required": { "description": "Require this application to be served in an isolated browser for users matching this policy. 'Client Web Isolation' must be on for the account in order to use this feature.", "type": "boolean", "example": false }, "access_isolation_required-2": { "description": "Require this application to be served in an isolated browser for users matching this policy.", "type": "boolean", "example": false, "default": false }, "access_jit_request_event": { "type": "object", "properties": { "actor_email": { "type": "string", "format": "email" }, "actor_idp": { "type": "string" }, "actor_uuid": { "type": "string", "format": "uuid" }, "decision_outcome": { "type": "string" }, "ray_id": { "type": "string" }, "session_duration_seconds": { "type": "integer" }, "success": { "type": "boolean" }, "timestamp": { "$ref": "#/components/schemas/access_timestamp" }, "type": { "$ref": "#/components/schemas/access_jit_request_event_type" } } }, "access_jit_request_event_type": { "type": "string", "enum": [ "CREATED", "APPROVER_DECISION", "COMMITTED", "CANCELED", "LOGIN_SUCCESS", "REDIRECT_TO_ACTIVE" ] }, "access_jit_request_log": { "type": "object", "properties": { "app_aud": { "description": "Audience of the Access application.", "type": "string" }, "app_hostname": { "type": "string" }, "approvals_received": { "description": "Number of unique actors who approved the request.", "type": "integer" }, "approver_emails": { "description": "Unique actors who approved the request.", "type": "array", "items": { "format": "email", "type": "string" } }, "created_at": { "$ref": "#/components/schemas/access_timestamp" }, "expires_at": { "$ref": "#/components/schemas/access_timestamp" }, "knock_request_id": { "description": "Unique identifier for the JIT request.", "type": "string" }, "purpose_justification": { "type": "string" }, "requester_email": { "type": "string", "format": "email" }, "status": { "$ref": "#/components/schemas/access_jit_request_status" } } }, "access_jit_request_log_detail": { "allOf": [ { "$ref": "#/components/schemas/access_jit_request_log" }, { "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/access_jit_request_event" } } }, "type": "object" } ] }, "access_jit_request_status": { "description": "JIT request status. `SPENT` is deprecated and interpreted as `APPROVED`.", "type": "string", "enum": [ "PENDING", "APPROVED", "DENIED", "CANCELED", "SPENT" ] }, "access_key_config": { "type": "object", "properties": { "days_until_next_rotation": { "$ref": "#/components/schemas/access_days_until_next_rotation" }, "key_rotation_interval_days": { "$ref": "#/components/schemas/access_key_rotation_interval_days" }, "last_key_rotation_at": { "$ref": "#/components/schemas/access_last_key_rotation_at" } } }, "access_key_rotation_interval_days": { "description": "The number of days between key rotations.", "type": "number", "example": 30, "maximum": 365, "minimum": 21, "x-auditable": true }, "access_landing_page_design": { "description": "The design of the App Launcher landing page shown to users when they log in.", "type": "object", "properties": { "button_color": { "$ref": "#/components/schemas/access_button_color" }, "button_text_color": { "$ref": "#/components/schemas/access_button_text_color" }, "image_url": { "$ref": "#/components/schemas/access_image_url" }, "message": { "$ref": "#/components/schemas/access_message" }, "title": { "$ref": "#/components/schemas/access_title" } } }, "access_last_key_rotation_at": { "description": "The timestamp of the previous key rotation.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "x-auditable": true }, "access_last_seen_identity_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity" } ] } }, "type": "object" } ] }, "access_last_successful_login": { "description": "The time at which the user last successfully logged in.", "type": "string", "format": "date-time", "example": "2020-07-01T05:20:00Z" }, "access_limit": { "description": "The maximum number of update logs to retrieve.", "type": "integer", "example": 10, "default": 20 }, "access_linked_app_token_rule": { "description": "Matches OAuth 2.0 access tokens issued by the specified Access OIDC SaaS application. Only compatible with non_identity and bypass decisions.", "type": "object", "properties": { "linked_app_token": { "type": "object", "properties": { "app_uid": { "description": "The ID of an Access OIDC SaaS application", "type": "string", "example": "aa0a4aab-672b-4bdb-bc33-a59f1130a11f" } }, "required": [ "app_uid" ] } }, "required": [ "linked_app_token" ], "title": "Linked App Token" }, "access_linkedin": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider" }, { "properties": { "config": { "$ref": "#/components/schemas/access_generic-oauth-config" } }, "type": "object" } ], "title": "LinkedIn" }, "access_linkedin-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider-2" }, { "properties": { "config": { "$ref": "#/components/schemas/access_generic-oauth-config-2" } }, "type": "object" } ], "title": "LinkedIn" }, "access_login_design": { "type": "object", "properties": { "background_color": { "description": "The background color on your login page.", "type": "string", "example": "#c5ed1b" }, "footer_text": { "description": "The text at the bottom of your login page.", "type": "string", "example": "This is an example description." }, "header_text": { "description": "The text at the top of your login page.", "type": "string", "example": "This is an example description." }, "logo_path": { "description": "The URL of the logo on your login page.", "type": "string", "example": "https://example.com/logo.png" }, "text_color": { "description": "The text color on your login page.", "type": "string", "example": "#c5ed1b" } } }, "access_login_method_rule": { "description": "Matches a specific identity provider id.", "type": "object", "properties": { "login_method": { "type": "object", "properties": { "id": { "description": "The ID of an identity provider.", "type": "string", "example": "aa0a4aab-672b-4bdb-bc33-a59f1130a11f" } }, "required": [ "id" ] } }, "required": [ "login_method" ], "title": "Login Method" }, "access_logo_url": { "description": "The image URL for the logo shown in the App Launcher dashboard.", "type": "string", "example": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg" }, "access_logo_url-2": { "description": "The image URL for the logo shown in the App Launcher dashboard.", "type": "string", "example": "https://www.cloudflare.com/img/logo-web-badges/cf-logo-on-white-bg.svg", "x-auditable": true }, "access_max_age": { "description": "The maximum number of seconds the results of a preflight request can be cached.", "type": "number", "example": -1, "maximum": 86400, "minimum": -1 }, "access_mcp_portal_props": { "type": "object", "properties": { "allow_authenticate_via_warp": { "$ref": "#/components/schemas/access_allow_authenticate_via_warp-2" }, "allowed_idps": { "$ref": "#/components/schemas/access_allowed_idps" }, "auto_redirect_to_identity": { "$ref": "#/components/schemas/access_auto_redirect_to_identity-2" }, "custom_deny_message": { "$ref": "#/components/schemas/access_custom_deny_message" }, "custom_deny_url": { "$ref": "#/components/schemas/access_custom_deny_url" }, "custom_non_identity_deny_url": { "$ref": "#/components/schemas/access_custom_non_identity_deny_url" }, "custom_pages": { "$ref": "#/components/schemas/access_custom_pages-2" }, "destinations": { "$ref": "#/components/schemas/access_destinations" }, "domain": { "$ref": "#/components/schemas/access_domain" }, "http_only_cookie_attribute": { "$ref": "#/components/schemas/access_http_only_cookie_attribute" }, "logo_url": { "$ref": "#/components/schemas/access_logo_url" }, "name": { "$ref": "#/components/schemas/access_name-8" }, "oauth_configuration": { "$ref": "#/components/schemas/access_oauth_configuration" }, "options_preflight_bypass": { "$ref": "#/components/schemas/access_options_preflight_bypass" }, "same_site_cookie_attribute": { "$ref": "#/components/schemas/access_same_site_cookie_attribute" }, "scim_config": { "$ref": "#/components/schemas/access_scim_config" }, "session_duration": { "$ref": "#/components/schemas/access_session_duration-2" }, "tags": { "$ref": "#/components/schemas/access_tags" }, "type": { "allOf": [ { "$ref": "#/components/schemas/access_type" }, { "example": "mcp_portal", "type": "string" } ] } }, "required": [ "type" ], "title": "MCP Server Portal Application" }, "access_mcp_props": { "type": "object", "properties": { "allow_authenticate_via_warp": { "$ref": "#/components/schemas/access_allow_authenticate_via_warp-2" }, "allowed_idps": { "$ref": "#/components/schemas/access_allowed_idps" }, "auto_redirect_to_identity": { "$ref": "#/components/schemas/access_auto_redirect_to_identity-2" }, "custom_deny_message": { "$ref": "#/components/schemas/access_custom_deny_message" }, "custom_deny_url": { "$ref": "#/components/schemas/access_custom_deny_url" }, "custom_non_identity_deny_url": { "$ref": "#/components/schemas/access_custom_non_identity_deny_url" }, "custom_pages": { "$ref": "#/components/schemas/access_custom_pages-2" }, "destinations": { "$ref": "#/components/schemas/access_destinations" }, "http_only_cookie_attribute": { "$ref": "#/components/schemas/access_http_only_cookie_attribute" }, "logo_url": { "$ref": "#/components/schemas/access_logo_url" }, "name": { "$ref": "#/components/schemas/access_name-8" }, "oauth_configuration": { "$ref": "#/components/schemas/access_oauth_configuration" }, "options_preflight_bypass": { "$ref": "#/components/schemas/access_options_preflight_bypass" }, "same_site_cookie_attribute": { "$ref": "#/components/schemas/access_same_site_cookie_attribute" }, "scim_config": { "$ref": "#/components/schemas/access_scim_config" }, "session_duration": { "$ref": "#/components/schemas/access_session_duration-2" }, "tags": { "$ref": "#/components/schemas/access_tags" }, "type": { "allOf": [ { "$ref": "#/components/schemas/access_type" }, { "example": "mcp", "type": "string" } ] } }, "required": [ "type" ], "title": "MCP Server Application" }, "access_message": { "description": "The message shown on the landing page.", "type": "string", "example": "Log in below to reach your applications behind Access." }, "access_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "access_meta": { "description": "The metadata of the SCIM resource.", "type": "object", "properties": { "created": { "description": "The timestamp of when the SCIM resource was created.", "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z" }, "lastModified": { "description": "The timestamp of when the SCIM resource was last modified.", "type": "string", "format": "date-time", "example": "2025-01-02T00:00:00Z" } } }, "access_mfa_config": { "description": "Configures multi-factor authentication (MFA) settings.", "type": "object", "properties": { "allowed_authenticators": { "description": "Lists the MFA methods that users can authenticate with.", "type": "array", "items": { "enum": [ "totp", "biometrics", "security_key" ], "type": "string" }, "example": [ "totp", "biometrics", "security_key" ] }, "mfa_disabled": { "description": "Indicates whether to disable MFA for this resource. This option is available at the application and policy level.", "type": "boolean", "example": false }, "session_duration": { "description": "Defines the duration of an MFA session. Must be in minutes (m) or hours (h). Minimum: 0m. Maximum: 720h (30 days). Examples:`5m` or `24h`.", "type": "string", "example": "24h" } }, "x-auditable": true }, "access_mfa_piv_key_requirements": { "description": "Configures PIV key requirements for MFA using hardware security keys.", "type": "object", "properties": { "pin_policy": { "description": "Defines when a PIN is required to use the SSH key. Valid values: `never` (no PIN required), `once` (PIN required once per session), `always` (PIN required for each use).", "type": "string", "example": "always", "enum": [ "never", "once", "always" ] }, "require_fips_device": { "description": "Requires the PIV key to be stored on a FIPS 140-2 Level 1 or higher validated device.", "type": "boolean", "example": true }, "ssh_key_size": { "description": "Specifies the allowed SSH key sizes in bits. Valid sizes depend on key type. Ed25519 has a fixed key size and does not accept this parameter.", "type": "array", "items": { "enum": [ 256, 384, 521, 2048, 3072, 4096 ], "type": "integer" }, "example": [ 256, 2048 ] }, "ssh_key_type": { "description": "Specifies the allowed SSH key types. Valid values are `ecdsa`, `ed25519`, and `rsa`.", "type": "array", "items": { "enum": [ "ecdsa", "ed25519", "rsa" ], "type": "string" }, "example": [ "ecdsa", "rsa" ] }, "touch_policy": { "description": "Defines when physical touch is required to use the SSH key. Valid values: `never` (no touch required), `always` (touch required for each use), `cached` (touch cached for 15 seconds).", "type": "string", "example": "always", "enum": [ "never", "always", "cached" ] } }, "x-auditable": true }, "access_mfa_required_for_all_apps": { "description": "Determines whether global MFA settings apply to applications by default. The organization must have MFA enabled with at least one authentication method and a session duration configured. Note: 'allowed_authenticators' cannot contain only the infrastructure SSH authenticators ('piv_key' and 'ssh_fido2_key') if the organization has any non-infrastructure applications.", "type": "boolean", "example": false, "default": false, "x-auditable": true }, "access_name": { "description": "The name of your Zero Trust organization.", "type": "string", "example": "Widget Corps Internal Applications", "x-auditable": true }, "access_name-10": { "description": "The name of the user.", "type": "string", "example": "Jane Doe" }, "access_name-11": { "description": "Custom page name.", "type": "string", "x-auditable": true }, "access_name-12": { "description": "The name of the Bookmark application.", "type": "string", "example": "My Website", "x-auditable": true }, "access_name-13": { "description": "The name of the tag", "type": "string", "example": "engineers" }, "access_name-14": { "description": "The human-readable name of the FIDO2 authenticator", "type": "string", "example": "YubiKey 5 NFC" }, "access_name-15": { "description": "The name of your Zero Trust organization.", "type": "string", "example": "Widget Corps Internal Applications" }, "access_name-16": { "description": "The name of the Access group.", "type": "string", "example": "Allow devs" }, "access_name-17": { "description": "The name of the service token.", "type": "string", "example": "CI/CD token" }, "access_name-18": { "description": "The name of the certificate.", "type": "string", "example": "Allow devs" }, "access_name-2": { "description": "The name of the service token.", "type": "string", "example": "CI/CD token", "x-auditable": true }, "access_name-3": { "description": "The name of the identity provider, shown to users on the login page.", "type": "string", "example": "Widget Corps IDP" }, "access_name-4": { "description": "The display name of the SCIM Group resource.", "type": "string", "example": "ALL_EMPLOYEES" }, "access_name-5": { "description": "The name of the SCIM User resource.", "type": "string", "example": "John Smith" }, "access_name-6": { "description": "The name of the Access group.", "type": "string", "example": "Allow devs", "x-auditable": true }, "access_name-7": { "description": "The name of the certificate.", "type": "string", "example": "Allow devs", "x-auditable": true }, "access_name-8": { "description": "The name of the application.", "type": "string", "example": "Admin Site" }, "access_name-9": { "description": "The name of the Access policy.", "type": "string", "example": "Allow devs" }, "access_name_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/access_name-13" } } } }, "type": "object" } ] }, "access_nonce": { "type": "string", "example": "X1aXj1lFVcqqyoXF" }, "access_oauth_configuration": { "description": "**Beta:** Optional configuration for managing an OAuth authorization flow controlled by Access. When set, Access will act as the OAuth authorization server for this application. Only compatible with OAuth clients that support [RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707) (Resource Indicators for OAuth 2.0). This feature is currently in beta.\n", "type": "object", "properties": { "dynamic_client_registration": { "description": "Settings for OAuth dynamic client registration.", "type": "object", "properties": { "allow_any_on_localhost": { "description": "Allows any client with redirect URIs on localhost.", "type": "boolean" }, "allow_any_on_loopback": { "description": "Allows any client with redirect URIs on 127.0.0.1.", "type": "boolean" }, "allowed_uris": { "description": "The URIs that are allowed as redirect URIs for dynamically registered clients. HTTP and HTTPS paths may end in `/*` to match all sub-paths. Custom-scheme URIs must be explicitly configured and match exactly.\n", "type": "array", "items": { "type": "string" }, "example": [ "https://example.com/callback", "com.example.app:/oauth/callback" ] }, "enabled": { "description": "Whether dynamic client registration is enabled.", "type": "boolean" } } }, "enabled": { "description": "Whether the OAuth configuration is enabled for this application. When set to `false`, Access will not handle OAuth for this application. Defaults to `true` if omitted.\n", "type": "boolean", "default": true }, "grant": { "description": "Settings for OAuth grant behavior.", "type": "object", "properties": { "access_token_lifetime": { "description": "The lifetime of the access token. Must be in the format `300ms` or `2h45m`. Valid time units are ns, us (or µs), ms, s, m, h.", "type": "string", "example": "5m" }, "session_duration": { "description": "The duration of the OAuth session. Must be in the format `300ms` or `2h45m`. Valid time units are ns, us (or µs), ms, s, m, h.", "type": "string", "example": "24h" } } } } }, "access_oidc": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider" }, { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/access_generic-oauth-config" }, { "$ref": "#/components/schemas/access_custom-claims-support" }, { "properties": { "auth_url": { "description": "The authorization_endpoint URL of your IdP", "type": "string", "example": "https://accounts.google.com/o/oauth2/auth" }, "certs_url": { "description": "The jwks_uri endpoint of your IdP to allow the IdP keys to sign the tokens", "type": "string", "example": "https://www.googleapis.com/oauth2/v3/certs" }, "pkce_enabled": { "description": "Enable Proof Key for Code Exchange (PKCE)", "type": "boolean" }, "scopes": { "description": "OAuth scopes", "type": "array", "items": { "type": "string" }, "example": [ "openid", "email", "profile" ] }, "token_url": { "description": "The token_endpoint URL of your IdP", "type": "string", "example": "https://accounts.google.com/o/oauth2/token" } }, "type": "object" } ] } }, "type": "object" } ], "title": "Generic OAuth" }, "access_oidc-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider-2" }, { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/access_generic-oauth-config-2" }, { "properties": { "auth_url": { "description": "The authorization_endpoint URL of your IdP", "type": "string", "example": "https://accounts.google.com/o/oauth2/auth" }, "certs_url": { "description": "The jwks_uri endpoint of your IdP to allow the IdP keys to sign the tokens", "type": "string", "example": "https://www.googleapis.com/oauth2/v3/certs" }, "claims": { "description": "List of custom claims that will be pulled from your id_token and added to your signed Access JWT token.", "type": "array", "items": { "type": "string" }, "example": [ "given_name", "locale" ] }, "scopes": { "description": "OAuth scopes", "type": "array", "items": { "type": "string" }, "example": [ "openid", "email", "profile" ] }, "token_url": { "description": "The token_endpoint URL of your IdP", "type": "string", "example": "https://accounts.google.com/o/oauth2/token" } }, "type": "object" } ] } }, "type": "object" } ], "title": "Generic OAuth" }, "access_oidc_claim_rule": { "description": "Matches an OIDC claim.\nRequires an OIDC identity provider.", "type": "object", "properties": { "oidc": { "type": "object", "properties": { "claim_name": { "description": "The name of the OIDC claim.", "type": "string", "example": "group" }, "claim_value": { "description": "The OIDC claim value to look for.", "type": "string", "example": "devs@cloudflare.com" }, "identity_provider_id": { "description": "The ID of your OIDC identity provider.", "type": "string", "example": "ea85612a-29c8-46c2-bacb-669d65136971" } }, "required": [ "claim_name", "claim_value", "identity_provider_id" ] } }, "required": [ "oidc" ], "title": "OIDC claim" }, "access_oidc_saas_app": { "type": "object", "properties": { "access_token_lifetime": { "description": "The lifetime of the OIDC Access Token after creation. Valid units are m,h. Must be greater than or equal to 1m and less than or equal to 24h.", "type": "string", "example": "5m" }, "allow_pkce_without_client_secret": { "description": "If client secret should be required on the token endpoint when authorization_code_with_pkce grant is used.", "type": "boolean", "example": true }, "app_launcher_url": { "description": "The URL where this applications tile redirects users", "type": "string", "example": "https://example.com/login" }, "auth_type": { "description": "Identifier of the authentication protocol used for the saas app. Required for OIDC.", "type": "string", "example": "oidc", "enum": [ "saml", "oidc" ] }, "client_id": { "description": "The application client id", "type": "string", "example": "oidc client id" }, "client_secret": { "description": "The application client secret, only returned on POST request.", "type": "string", "example": "oidc client secret", "x-sensitive": true }, "created_at": { "$ref": "#/components/schemas/access_created_at" }, "custom_claims": { "type": "array", "items": { "properties": { "name": { "description": "The name of the claim.", "type": "string", "example": "family_name" }, "required": { "description": "If the claim is required when building an OIDC token.", "type": "boolean", "example": true }, "scope": { "description": "The scope of the claim.", "type": "string", "example": "profile", "enum": [ "groups", "profile", "email", "openid" ] }, "source": { "type": "object", "properties": { "name": { "description": "The name of the IdP claim.", "type": "string", "example": "last_name" }, "name_by_idp": { "description": "A mapping from IdP ID to claim name.", "type": "object", "example": { "exampleIdPID1": "ClaimName1", "exampleIdPID2": "ClaimName2" }, "additionalProperties": { "type": "string" } } } } }, "type": "object" } }, "grant_types": { "description": "The OIDC flows supported by this application", "type": "array", "items": { "enum": [ "authorization_code", "authorization_code_with_pkce", "refresh_tokens", "hybrid", "implicit" ], "type": "string" }, "example": [ "authorization_code" ] }, "group_filter_regex": { "description": "A regex to filter Cloudflare groups returned in ID token and userinfo endpoint", "type": "string", "example": "^GROUP_FILTER-*$" }, "hybrid_and_implicit_options": { "type": "object", "properties": { "return_access_token_from_authorization_endpoint": { "description": "If an Access Token should be returned from the OIDC Authorization endpoint", "type": "boolean" }, "return_id_token_from_authorization_endpoint": { "description": "If an ID Token should be returned from the OIDC Authorization endpoint", "type": "boolean" } } }, "public_key": { "description": "The Access public certificate that will be used to verify your identity.", "type": "string", "example": "example unique name" }, "redirect_uris": { "description": "The permitted URL's for Cloudflare to return Authorization codes and Access/ID tokens", "type": "array", "items": { "type": "string" }, "example": [ "https://example.com" ] }, "refresh_token_options": { "type": "object", "properties": { "lifetime": { "description": "How long a refresh token will be valid for after creation. Valid units are m,h,d. Must be longer than 1m.", "type": "string", "example": "30d" } } }, "scopes": { "description": "Define the user information shared with access, \"offline_access\" scope will be automatically enabled if refresh tokens are enabled", "type": "array", "items": { "enum": [ "openid", "groups", "email", "profile" ], "type": "string" }, "example": [ "openid", "groups", "email", "profile" ] }, "updated_at": { "$ref": "#/components/schemas/access_updated_at" } }, "title": "OIDC SaaS App" }, "access_oidc_saas_app-2": { "type": "object", "properties": { "access_token_lifetime": { "description": "The lifetime of the OIDC Access Token after creation. Valid units are m,h. Must be greater than or equal to 1m and less than or equal to 24h.", "type": "string", "example": "5m" }, "allow_pkce_without_client_secret": { "description": "If client secret should be required on the token endpoint when authorization_code_with_pkce grant is used.", "type": "boolean", "example": true }, "app_launcher_url": { "description": "The URL where this applications tile redirects users", "type": "string", "example": "https://example.com/login" }, "auth_type": { "description": "Identifier of the authentication protocol used for the saas app. Required for OIDC.", "type": "string", "example": "oidc", "enum": [ "saml", "oidc" ] }, "client_id": { "description": "The application client id", "type": "string", "example": "oidc client id" }, "client_secret": { "description": "The application client secret, only returned on POST request.", "type": "string", "example": "oidc client secret", "x-sensitive": true }, "created_at": { "$ref": "#/components/schemas/access_timestamp" }, "custom_claims": { "type": "array", "items": { "properties": { "name": { "description": "The name of the claim.", "type": "string", "example": "family_name" }, "required": { "description": "If the claim is required when building an OIDC token.", "type": "boolean", "example": true }, "scope": { "description": "The scope of the claim.", "type": "string", "example": "profile", "enum": [ "groups", "profile", "email", "openid" ] }, "source": { "type": "object", "properties": { "name": { "description": "The name of the IdP claim.", "type": "string", "example": "last_name" }, "name_by_idp": { "description": "A mapping from IdP ID to attribute name.", "type": "array", "items": { "properties": { "idp_id": { "description": "The UID of the IdP.", "type": "string", "example": "exampleIdPID1" }, "source_name": { "description": "The name of the IdP provided attribute.", "type": "string", "example": "AttributeName1" } }, "type": "object" } } } } }, "type": "object" } }, "grant_types": { "description": "The OIDC flows supported by this application", "type": "array", "items": { "enum": [ "authorization_code", "authorization_code_with_pkce", "refresh_tokens", "hybrid", "implicit" ], "type": "string" }, "example": [ "authorization_code" ] }, "group_filter_regex": { "description": "A regex to filter Cloudflare groups returned in ID token and userinfo endpoint.", "type": "string", "example": "^GROUP_FILTER-*$" }, "hybrid_and_implicit_options": { "type": "object", "properties": { "return_access_token_from_authorization_endpoint": { "description": "If an Access Token should be returned from the OIDC Authorization endpoint", "type": "boolean" }, "return_id_token_from_authorization_endpoint": { "description": "If an ID Token should be returned from the OIDC Authorization endpoint", "type": "boolean" } } }, "public_key": { "description": "The Access public certificate that will be used to verify your identity.", "type": "string", "example": "example unique name" }, "redirect_uris": { "description": "The permitted URL's for Cloudflare to return Authorization codes and Access/ID tokens", "type": "array", "items": { "type": "string" }, "example": [ "https://example.com" ] }, "refresh_token_options": { "type": "object", "properties": { "lifetime": { "description": "How long a refresh token will be valid for after creation. Valid units are m,h,d. Must be longer than 1m.", "type": "string", "example": "30d" } } }, "scopes": { "description": "Define the user information shared with access, \"offline_access\" scope will be automatically enabled if refresh tokens are enabled", "type": "array", "items": { "enum": [ "openid", "groups", "email", "profile" ], "type": "string" }, "example": [ "openid", "groups", "email", "profile" ] }, "updated_at": { "$ref": "#/components/schemas/access_timestamp" } }, "title": "OIDC SaaS App" }, "access_okta": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider" }, { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/access_generic-oauth-config" }, { "$ref": "#/components/schemas/access_custom-claims-support" }, { "properties": { "authorization_server_id": { "description": "Your okta authorization server id", "type": "string", "example": "aus9o8wzkhckw9TLa0h7z" }, "okta_account": { "description": "Your okta account url", "type": "string", "example": "https://dev-abc123.oktapreview.com", "x-auditable": true } }, "type": "object" } ] } }, "type": "object" } ], "title": "Okta" }, "access_okta-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider-2" }, { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/access_generic-oauth-config-2" }, { "properties": { "okta_account": { "description": "Your okta account url", "type": "string", "example": "https://dev-abc123.oktapreview.com" } }, "type": "object" } ] } }, "type": "object" } ], "title": "Okta" }, "access_okta_group_rule": { "description": "Matches an Okta group.\nRequires an Okta identity provider.", "type": "object", "properties": { "okta": { "type": "object", "properties": { "identity_provider_id": { "description": "The ID of your Okta identity provider.", "type": "string", "example": "ea85612a-29c8-46c2-bacb-669d65136971" }, "name": { "description": "The name of the Okta group.", "type": "string", "example": "devs" } }, "required": [ "name", "identity_provider_id" ] } }, "required": [ "okta" ], "title": "Okta group" }, "access_onelogin": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider" }, { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/access_generic-oauth-config" }, { "$ref": "#/components/schemas/access_custom-claims-support" }, { "properties": { "onelogin_account": { "description": "Your OneLogin account url", "type": "string", "example": "https://mycompany.onelogin.com", "x-auditable": true } }, "type": "object" } ] } }, "type": "object" } ], "title": "OneLogin" }, "access_onelogin-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider-2" }, { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/access_generic-oauth-config-2" }, { "properties": { "onelogin_account": { "description": "Your OneLogin account url", "type": "string", "example": "https://mycompany.onelogin.com" } }, "type": "object" } ] } }, "type": "object" } ], "title": "OneLogin" }, "access_onetimepin": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider" }, { "properties": { "config": { "type": "object", "properties": { "redirect_url": { "type": "string", "readOnly": true } } }, "type": { "type": "string", "enum": [ "onetimepin" ] } }, "type": "object" } ], "title": "One Time Pin" }, "access_onetimepin-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider-2" }, { "properties": { "config": { "type": "object", "properties": { "redirect_url": { "type": "string", "readOnly": true } } }, "type": { "type": "string", "enum": [ "onetimepin" ] } }, "type": "object" } ], "title": "One Time Pin" }, "access_options_preflight_bypass": { "description": "Allows options preflight requests to bypass Access authentication and go directly to the origin. Cannot turn on if cors_headers is set.", "type": "boolean", "example": true }, "access_options_preflight_bypass-2": { "description": "Allows options preflight requests to bypass Access authentication and go directly to the origin. Cannot turn on if cors_headers is set.", "type": "boolean", "example": true, "default": false }, "access_org_mfa_config": { "description": "Configures multi-factor authentication (MFA) settings for an organization.", "type": "object", "properties": { "allowed_authenticators": { "description": "Lists the MFA methods that users can authenticate with. The `piv_key` and `ssh_fido2_key` values are supported only for infrastructure applications.", "type": "array", "items": { "enum": [ "totp", "biometrics", "security_key", "piv_key", "ssh_fido2_key" ], "type": "string" }, "example": [ "totp", "biometrics", "security_key" ] }, "amr_matching_session_duration": { "description": "Allows a user to skip MFA via Authentication Method Reference (AMR) matching when the AMR claim provided by the IdP the user used to authenticate contains \"mfa\". Must be in minutes (m) or hours (h). Minimum: 0m. Maximum: 720h (30 days).", "type": "string", "example": "12h" }, "required_aaguids": { "description": "Specifies a Cloudflare List of required FIDO2 authenticator device AAGUIDs.", "type": "string", "format": "uuid", "example": "2fc0579f-8113-47ea-b116-bb5a8db9202a" }, "session_duration": { "description": "Defines the duration of an MFA session. Must be in minutes (m) or hours (h). Minimum: 0m. Maximum: 720h (30 days). Examples:`5m` or `24h`.", "type": "string", "example": "24h" } }, "x-auditable": true }, "access_organizations": { "type": "object", "properties": { "allow_authenticate_via_warp": { "$ref": "#/components/schemas/access_allow_authenticate_via_warp" }, "auth_domain": { "$ref": "#/components/schemas/access_auth_domain" }, "auto_redirect_to_identity": { "$ref": "#/components/schemas/access_auto_redirect_to_identity" }, "created_at": { "$ref": "#/components/schemas/access_created_at" }, "custom_pages": { "$ref": "#/components/schemas/access_custom_pages" }, "deny_unmatched_requests": { "$ref": "#/components/schemas/access_deny_unmatched_requests" }, "deny_unmatched_requests_exempted_zone_names": { "$ref": "#/components/schemas/access_deny_unmatched_requests_exempted_zone_names" }, "is_ui_read_only": { "$ref": "#/components/schemas/access_is_ui_read_only" }, "login_design": { "$ref": "#/components/schemas/access_login_design" }, "mfa_config": { "$ref": "#/components/schemas/access_org_mfa_config" }, "mfa_piv_key_requirements": { "$ref": "#/components/schemas/access_mfa_piv_key_requirements" }, "mfa_required_for_all_apps": { "$ref": "#/components/schemas/access_mfa_required_for_all_apps" }, "name": { "$ref": "#/components/schemas/access_name" }, "session_duration": { "$ref": "#/components/schemas/access_session_duration" }, "ui_read_only_toggle_reason": { "$ref": "#/components/schemas/access_ui_read_only_toggle_reason" }, "updated_at": { "$ref": "#/components/schemas/access_updated_at" }, "user_seat_expiration_inactive_time": { "$ref": "#/components/schemas/access_user_seat_expiration_inactive_time" }, "warp_auth_non_browser_401": { "$ref": "#/components/schemas/access_warp_auth_non_browser_401" }, "warp_auth_session_duration": { "$ref": "#/components/schemas/access_warp_auth_session_duration" } } }, "access_organizations-2": { "type": "object", "properties": { "auth_domain": { "$ref": "#/components/schemas/access_auth_domain-2" }, "created_at": { "$ref": "#/components/schemas/access_timestamp" }, "deny_unmatched_requests": { "$ref": "#/components/schemas/access_deny_unmatched_requests" }, "deny_unmatched_requests_exempted_zone_names": { "$ref": "#/components/schemas/access_deny_unmatched_requests_exempted_zone_names" }, "is_ui_read_only": { "$ref": "#/components/schemas/access_is_ui_read_only-2" }, "login_design": { "$ref": "#/components/schemas/access_login_design" }, "name": { "$ref": "#/components/schemas/access_name-15" }, "ui_read_only_toggle_reason": { "$ref": "#/components/schemas/access_ui_read_only_toggle_reason" }, "updated_at": { "$ref": "#/components/schemas/access_timestamp" }, "user_seat_expiration_inactive_time": { "$ref": "#/components/schemas/access_user_seat_expiration_inactive_time-2" } } }, "access_path_cookie_attribute": { "description": "Enables cookie paths to scope an application's JWT to the application path. If disabled, the JWT will scope to the hostname by default", "type": "boolean", "example": true, "default": false }, "access_percent_approved": { "description": "The percentage of (processed) users approved based on policy evaluation results.", "type": "integer", "example": 25, "x-auditable": true }, "access_percent_blocked": { "description": "The percentage of (processed) users blocked based on policy evaluation results.", "type": "integer", "example": 25, "x-auditable": true }, "access_percent_errored": { "description": "The percentage of (processed) users errored based on policy evaluation results.", "type": "integer", "example": 25, "x-auditable": true }, "access_percent_users_processed": { "description": "The percentage of users processed so far (of the entire user base).", "type": "integer", "example": 50 }, "access_pingone": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider" }, { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/access_generic-oauth-config" }, { "$ref": "#/components/schemas/access_custom-claims-support" }, { "properties": { "ping_env_id": { "description": "Your PingOne environment identifier", "type": "string", "example": "342b5660-0c32-4936-a5a4-ce21fae57b0a", "x-auditable": true } }, "type": "object" } ] } }, "type": "object" } ], "title": "PingOne" }, "access_pingone-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider-2" }, { "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/access_generic-oauth-config-2" }, { "properties": { "ping_env_id": { "description": "Your PingOne environment identifier", "type": "string", "example": "342b5660-0c32-4936-a5a4-ce21fae57b0a" } }, "type": "object" } ] } }, "type": "object" } ], "title": "PingOne" }, "access_policies": { "type": "object", "properties": { "approval_groups": { "$ref": "#/components/schemas/access_approval_groups-2" }, "approval_required": { "$ref": "#/components/schemas/access_approval_required-2" }, "created_at": { "$ref": "#/components/schemas/access_timestamp" }, "decision": { "$ref": "#/components/schemas/access_decision-2" }, "exclude": { "$ref": "#/components/schemas/access_exclude-3" }, "id": { "$ref": "#/components/schemas/access_uuid" }, "include": { "$ref": "#/components/schemas/access_include" }, "isolation_required": { "$ref": "#/components/schemas/access_isolation_required-2" }, "name": { "$ref": "#/components/schemas/access_name-9" }, "precedence": { "$ref": "#/components/schemas/access_precedence-2" }, "purpose_justification_prompt": { "$ref": "#/components/schemas/access_purpose_justification_prompt" }, "purpose_justification_required": { "$ref": "#/components/schemas/access_purpose_justification_required-2" }, "require": { "$ref": "#/components/schemas/access_require-3" }, "updated_at": { "$ref": "#/components/schemas/access_timestamp" } } }, "access_policy_check_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "app_state": { "type": "object", "properties": { "app_uid": { "$ref": "#/components/schemas/access_uuid" }, "aud": { "type": "string", "example": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe389" }, "hostname": { "type": "string", "example": "test.com" }, "name": { "type": "string", "example": "Test App" }, "policies": { "type": "array", "items": { "type": "object" }, "example": [ { "decision": "allow", "exclude": [], "include": [ { "_type": "email", "email": "testuser@gmail.com" } ], "precedence": 1, "require": [], "status": "Success" } ] }, "status": { "type": "string", "example": "Success" } } }, "user_identity": { "type": "object", "properties": { "account_id": { "type": "string", "example": "41ecfbb341f033e52b46742756aabb8b" }, "device_sessions": { "type": "object", "example": {} }, "email": { "type": "string", "example": "testuser@gmail.com" }, "geo": { "type": "object", "properties": { "country": { "type": "string", "example": "US" } } }, "iat": { "type": "integer" }, "id": { "type": "string", "example": "1164449231815010287495" }, "is_gateway": { "type": "boolean", "example": false }, "is_warp": { "type": "boolean", "example": false }, "name": { "type": "string", "example": "Test User" }, "user_uuid": { "$ref": "#/components/schemas/access_uuid" }, "version": { "type": "integer" } } } } } }, "type": "object" } ] }, "access_policy_check_response-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "app_state": { "type": "object", "properties": { "app_uid": { "$ref": "#/components/schemas/access_uuid" }, "aud": { "type": "string", "example": "737646a56ab1df6ec9bddc7e5ca84eaf3b0768850f3ffb5d74f1534911fe389" }, "hostname": { "type": "string", "example": "test.com" }, "name": { "type": "string", "example": "Test App" }, "policies": { "type": "array", "items": { "type": "object" }, "example": [ { "decision": "allow", "exclude": [], "include": [ { "_type": "email", "email": "testuser@gmail.com" } ], "precedence": 0, "require": [], "status": "Success" } ] }, "status": { "type": "string", "example": "Success" } } }, "user_identity": { "type": "object", "properties": { "account_id": { "type": "string", "example": "41ecfbb341f033e52b46742756aabb8b" }, "device_sessions": { "type": "object", "example": {} }, "email": { "type": "string", "example": "testuser@gmail.com" }, "geo": { "type": "object", "properties": { "country": { "type": "string", "example": "US" } } }, "iat": { "type": "integer" }, "id": { "type": "string", "example": "1164449231815010287495" }, "is_gateway": { "type": "boolean", "example": false }, "is_warp": { "type": "boolean", "example": false }, "name": { "type": "string", "example": "Test User" }, "user_uuid": { "$ref": "#/components/schemas/access_uuid" }, "version": { "type": "integer" } } } } } }, "type": "object" } ] }, "access_policy_init_req": { "type": "object", "properties": { "policies": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/access_policy_req" }, { "description": "The UUID of the reusable policy you wish to test", "example": "f1a8b3c9d4e5f6789a0b1c2d3e4f5678a9b0c1d2e3f4a5b67890c1d2e3f4b5a6", "type": "string" } ] } } } }, "access_policy_init_resp": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/access_policy_test_id" }, "status": { "$ref": "#/components/schemas/access_status" } } } }, "type": "object" } ] }, "access_policy_req": { "type": "object", "properties": { "approval_groups": { "$ref": "#/components/schemas/access_approval_groups" }, "approval_required": { "$ref": "#/components/schemas/access_approval_required" }, "connection_rules": { "$ref": "#/components/schemas/access_connection_rules" }, "isolation_required": { "$ref": "#/components/schemas/access_isolation_required" }, "mfa_config": { "$ref": "#/components/schemas/access_mfa_config" }, "purpose_justification_prompt": { "$ref": "#/components/schemas/access_purpose_justification_prompt" }, "purpose_justification_required": { "$ref": "#/components/schemas/access_purpose_justification_required" }, "session_duration": { "$ref": "#/components/schemas/access_session_duration-3" } }, "allOf": [ { "$ref": "#/components/schemas/access_base_policy_req" } ] }, "access_policy_resp": { "type": "object", "properties": { "approval_groups": { "$ref": "#/components/schemas/access_approval_groups" }, "approval_required": { "$ref": "#/components/schemas/access_approval_required" }, "connection_rules": { "$ref": "#/components/schemas/access_connection_rules" }, "isolation_required": { "$ref": "#/components/schemas/access_isolation_required" }, "mfa_config": { "$ref": "#/components/schemas/access_mfa_config" }, "purpose_justification_prompt": { "$ref": "#/components/schemas/access_purpose_justification_prompt" }, "purpose_justification_required": { "$ref": "#/components/schemas/access_purpose_justification_required" }, "session_duration": { "$ref": "#/components/schemas/access_session_duration-3" } }, "allOf": [ { "$ref": "#/components/schemas/access_base_policy_resp" } ] }, "access_policy_test_id": { "description": "The UUID of the policy test.", "type": "string", "example": "f1a8b3c9d4e5f6789a0b1c2d3e4f5678a9b0c1d2e3f4a5b67890c1d2e3f4b5a6", "maxLength": 64, "x-auditable": true }, "access_policy_update_resp": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/access_policy_test_id" }, "percent_approved": { "$ref": "#/components/schemas/access_percent_approved" }, "percent_blocked": { "$ref": "#/components/schemas/access_percent_blocked" }, "percent_errored": { "$ref": "#/components/schemas/access_percent_errored" }, "percent_users_processed": { "$ref": "#/components/schemas/access_percent_users_processed" }, "status": { "$ref": "#/components/schemas/access_update_status" }, "total_users": { "$ref": "#/components/schemas/access_total_users" }, "users_approved": { "$ref": "#/components/schemas/access_users_approved" }, "users_blocked": { "$ref": "#/components/schemas/access_users_blocked" }, "users_errored": { "$ref": "#/components/schemas/access_users_errored" } } } }, "type": "object" } ] }, "access_policy_users": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/access_email-2" }, "id": { "$ref": "#/components/schemas/access_uuid" }, "name": { "$ref": "#/components/schemas/access_name-10" }, "status": { "$ref": "#/components/schemas/access_user_result" } } }, "access_policy_users_resp": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "description": "Page of processed users.", "type": "array", "items": { "$ref": "#/components/schemas/access_policy_users" } } }, "type": "object" } ] }, "access_port": { "description": "The port that the targets use for the chosen communication protocol. A port cannot be assigned to multiple protocols.", "type": "integer", "example": 22 }, "access_precedence": { "description": "The order of execution for this policy. Must be unique for each policy within an app.\n", "type": "integer" }, "access_precedence-2": { "description": "The order of execution for this policy. Must be unique for each policy.", "type": "integer" }, "access_previous_client_secret_expires_at": { "description": "The expiration of the previous `client_secret`. This can be modified at any point after a rotation. For example, you may extend it further into the future if you need more time to update services with the new secret; or move it into the past to immediately invalidate the previous token in case of compromise.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "x-auditable": true }, "access_protocol_infra_app": { "description": "The communication protocol your application secures.", "type": "string", "example": "SSH", "enum": [ "SSH" ], "x-auditable": true }, "access_protocol_self_hosted_app": { "description": "The communication protocol your application secures.", "type": "string", "example": "RDP", "enum": [ "RDP" ], "x-auditable": true }, "access_proxy_endpoint_props": { "allOf": [ { "$ref": "#/components/schemas/access_feature_app_props" }, { "properties": { "domain": { "description": "The proxy endpoint domain in the format: 10 alphanumeric characters followed by .proxy.cloudflare-gateway.com", "type": "string", "example": "abcd123456.proxy.cloudflare-gateway.com", "pattern": "^[A-Za-z0-9]{10}\\.proxy\\.cloudflare-gateway\\.com$" }, "name": { "type": "string", "example": "Gateway Proxy", "default": "Gateway Proxy" }, "type": { "allOf": [ { "$ref": "#/components/schemas/access_type" }, { "example": "proxy_endpoint", "type": "string" } ] } }, "type": "object" } ] }, "access_public_key": { "description": "The public key to add to your SSH server configuration.", "type": "string", "example": "ecdsa-sha2-nistp256 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx= open-ssh-ca@cloudflareaccess.org", "readOnly": true }, "access_purpose_justification_prompt": { "description": "A custom message that will appear on the purpose justification screen.", "type": "string", "example": "Please enter a justification for entering this protected domain." }, "access_purpose_justification_required": { "description": "Require users to enter a justification when they log in to the application.", "type": "boolean", "example": true }, "access_purpose_justification_required-2": { "description": "Require users to enter a justification when they log in to the application.", "type": "boolean", "example": true, "default": false }, "access_ray_id": { "description": "The unique identifier for the request to Cloudflare.", "type": "string", "example": "187d944c61940c77", "maxLength": 16 }, "access_rdp_clipboard_format": { "description": "Clipboard format for RDP connections.", "type": "string", "enum": [ "text", "file" ], "x-auditable": true }, "access_rdp_props": { "allOf": [ { "$ref": "#/components/schemas/access_app_resp_embedded_target_criteria_self_hosted" }, { "$ref": "#/components/schemas/access_self_hosted_props" }, { "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/access_type" }, { "example": "rdp", "type": "string" } ] } }, "type": "object" } ], "required": [ "target_criteria" ] }, "access_read_service_tokens_from_header": { "description": "Allows matching Access Service Tokens passed HTTP in a single header with this name.\nThis works as an alternative to the (CF-Access-Client-Id, CF-Access-Client-Secret) pair of headers.\nThe header value will be interpreted as a json object similar to:\n {\n \"cf-access-client-id\": \"88bf3b6d86161464f6509f7219099e57.access.example.com\",\n \"cf-access-client-secret\": \"bdd31cbc4dec990953e39163fbbb194c93313ca9f0a6e420346af9d326b1d2a5\"\n }\n", "type": "string", "example": "Authorization" }, "access_request_method": { "description": "The request method of the SCIM request.", "type": "array", "items": { "enum": [ "DELETE", "PATCH", "POST", "PUT" ], "type": "string" }, "example": [ "DELETE", "PATCH" ] }, "access_require": { "description": "Rules evaluated with an AND logical operator. To match a policy, a user must meet all of the Require rules.", "type": "array", "items": { "$ref": "#/components/schemas/access_rule" } }, "access_require-2": { "description": "Rules evaluated with an AND logical operator. To match the policy, a user must meet all of the Require rules.", "type": "array", "items": { "$ref": "#/components/schemas/access_rule" }, "default": [], "x-stainless-collection-type": "set" }, "access_require-3": { "description": "Rules evaluated with an AND logical operator. To match the policy, a user must meet all of the Require rules.", "type": "array", "items": { "$ref": "#/components/schemas/access_rule" } }, "access_resource_group_name": { "description": "The display name of the SCIM Group resource. Pass once for a single\nlookup (`?resource_group_name=A`) or repeat the parameter\n(`?resource_group_name=A&resource_group_name=B`) to filter by multiple\ngroup names in one request.", "type": "array", "items": { "type": "string" }, "example": [ "ALL_EMPLOYEES" ] }, "access_resource_type": { "description": "The resource type of the SCIM request.", "type": "array", "items": { "enum": [ "USER", "GROUP" ], "type": "string" }, "example": [ "USER", "GROUP" ] }, "access_resource_user_email": { "description": "The email address of the SCIM User resource. Pass once for a single\nlookup (`?resource_user_email=A`) or repeat the parameter\n(`?resource_user_email=A&resource_user_email=B`) to filter by multiple\nemails in one request.", "type": "array", "items": { "format": "email", "type": "string" }, "example": [ "john.smith@example.com" ] }, "access_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/access_azureAD" }, { "$ref": "#/components/schemas/access_centrify" }, { "$ref": "#/components/schemas/access_facebook" }, { "$ref": "#/components/schemas/access_github" }, { "$ref": "#/components/schemas/access_google" }, { "$ref": "#/components/schemas/access_google-apps" }, { "$ref": "#/components/schemas/access_linkedin" }, { "$ref": "#/components/schemas/access_oidc" }, { "$ref": "#/components/schemas/access_okta" }, { "$ref": "#/components/schemas/access_onelogin" }, { "$ref": "#/components/schemas/access_pingone" }, { "$ref": "#/components/schemas/access_saml" }, { "$ref": "#/components/schemas/access_yandex" }, { "$ref": "#/components/schemas/access_onetimepin" }, { "$ref": "#/components/schemas/access_cloudflare" } ] } } }, "type": "object" } ] }, "access_response_collection-10": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_custom_page_without_html" } } }, "type": "object" } ] }, "access_response_collection-11": { "allOf": [ { "$ref": "#/components/schemas/access_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_access-requests" } } }, "type": "object" } ] }, "access_response_collection-12": { "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_jit_request_log" } } }, "type": "object" } ] }, "access_response_collection-13": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_seats" } } }, "type": "object" } ] }, "access_response_collection-14": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_bookmarks" } } }, "type": "object" } ] }, "access_response_collection-15": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_tag" } } }, "type": "object" } ] }, "access_response_collection-16": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_authenticator_device_aaguid" }, "example": [ { "aaguid": "2fc0579f-8113-47ea-b116-bb5a8db9202a", "name": "YubiKey 5 NFC" }, { "aaguid": "fcb1bcb4-f370-078c-6993-bc24d0ae3fbe", "name": "Ledger Nano X FIDO2 Authenticator" } ] } }, "type": "object" } ] }, "access_response_collection-17": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/access_azureAD-2" }, { "$ref": "#/components/schemas/access_centrify-2" }, { "$ref": "#/components/schemas/access_facebook-2" }, { "$ref": "#/components/schemas/access_github-2" }, { "$ref": "#/components/schemas/access_google-2" }, { "$ref": "#/components/schemas/access_google-apps-2" }, { "$ref": "#/components/schemas/access_linkedin-2" }, { "$ref": "#/components/schemas/access_oidc-2" }, { "$ref": "#/components/schemas/access_okta-2" }, { "$ref": "#/components/schemas/access_onelogin-2" }, { "$ref": "#/components/schemas/access_pingone-2" }, { "$ref": "#/components/schemas/access_saml-2" }, { "$ref": "#/components/schemas/access_yandex-2" }, { "$ref": "#/components/schemas/access_onetimepin-2" }, { "$ref": "#/components/schemas/access_cloudflare-2" } ] } } }, "type": "object" } ] }, "access_response_collection-18": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_groups-3" } } }, "type": "object" } ] }, "access_response_collection-19": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_service-tokens-2" } } }, "type": "object" } ] }, "access_response_collection-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_groups-2" } } }, "type": "object" } ] }, "access_response_collection-20": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_ca-2" } } }, "type": "object" } ] }, "access_response_collection-21": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_certificates-3" } } }, "type": "object" } ] }, "access_response_collection-22": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_apps" } } }, "type": "object" } ] }, "access_response_collection-23": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_policies" } } }, "type": "object" } ] }, "access_response_collection-24": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "type": "integer", "example": 1 }, "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 100 }, "total_count": { "type": "integer", "example": 1 } } } }, "type": "object" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_users-2" } } }, "type": "object" } ] }, "access_response_collection-3": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_service-tokens" } } }, "type": "object" } ] }, "access_response_collection-4": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_ca" } } }, "type": "object" } ] }, "access_response_collection-5": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_certificates" } } }, "type": "object" } ] }, "access_response_collection-6": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_certificates-2" } } }, "type": "object" } ] }, "access_response_collection-7": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_app_response" } } }, "type": "object" } ] }, "access_response_collection-8": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_app_policy_result" } } }, "type": "object" } ] }, "access_response_collection-9": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_reusable_policy_resp" } } }, "type": "object" } ] }, "access_response_collection_hostnames": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_settings" } } }, "type": "object" } ] }, "access_response_collection_hostnames-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_settings-2" } } }, "type": "object" } ] }, "access_response_single": { "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_jit_request_log_detail" } }, "type": "object" } ] }, "access_responses": { "type": "object", "properties": { "cf_resource_id": { "description": "The unique Cloudflare-generated Id of the SCIM resource.", "type": "string", "example": "bd97ef8d-7986-43e3-9ee0-c25dda33e4b0" }, "error_description": { "description": "The error message which is generated when the status of the SCIM request is 'FAILURE'.", "type": "string", "example": "Invalid JSON body" }, "idp_id": { "description": "The unique Id of the IdP that has SCIM enabled.", "type": "string", "example": "df7e2w5f-02b7-4d9d-af26-8d1988fca630" }, "idp_resource_id": { "description": "The IdP-generated Id of the SCIM resource.", "type": "string", "example": "all_employees" }, "logged_at": { "$ref": "#/components/schemas/access_timestamp" }, "request_body": { "description": "The JSON-encoded string body of the SCIM request.", "type": "string", "example": "{}}" }, "request_method": { "description": "The request method of the SCIM request.", "type": "string", "example": "DELETE" }, "resource_group_name": { "description": "The display name of the SCIM Group resource if it exists.", "type": "string", "example": "ALL_EMPLOYEES" }, "resource_type": { "description": "The resource type of the SCIM request.", "type": "string", "example": "GROUP" }, "resource_user_email": { "description": "The email address of the SCIM User resource if it exists.", "type": "string", "format": "email", "example": "john.smith@example.com" }, "status": { "description": "The status of the SCIM request.", "type": "string", "example": "FAILURE" } } }, "access_reusable_policy_resp": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_policy_resp" }, { "properties": { "account_id": { "$ref": "#/components/schemas/access_identifier" }, "app_count": { "$ref": "#/components/schemas/access_app_count" }, "reusable": { "type": "boolean", "enum": [ true ] } }, "type": "object" } ] }, "access_rule": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/access_access_group_rule" }, { "$ref": "#/components/schemas/access_any_valid_service_token_rule" }, { "$ref": "#/components/schemas/access_auth_context_rule" }, { "$ref": "#/components/schemas/access_authentication_method_rule" }, { "$ref": "#/components/schemas/access_azure_group_rule" }, { "$ref": "#/components/schemas/access_certificate_rule" }, { "$ref": "#/components/schemas/access_common_name_rule" }, { "$ref": "#/components/schemas/access_country_rule" }, { "$ref": "#/components/schemas/access_device_posture_rule" }, { "$ref": "#/components/schemas/access_domain_rule" }, { "$ref": "#/components/schemas/access_email_list_rule" }, { "$ref": "#/components/schemas/access_email_rule" }, { "$ref": "#/components/schemas/access_everyone_rule" }, { "$ref": "#/components/schemas/access_external_evaluation_rule" }, { "$ref": "#/components/schemas/access_github_organization_rule" }, { "$ref": "#/components/schemas/access_gsuite_group_rule" }, { "$ref": "#/components/schemas/access_login_method_rule" }, { "$ref": "#/components/schemas/access_ip_list_rule" }, { "$ref": "#/components/schemas/access_ip_rule" }, { "$ref": "#/components/schemas/access_okta_group_rule" }, { "$ref": "#/components/schemas/access_saml_group_rule" }, { "$ref": "#/components/schemas/access_oidc_claim_rule" }, { "$ref": "#/components/schemas/access_service_token_rule" }, { "$ref": "#/components/schemas/access_linked_app_token_rule" }, { "$ref": "#/components/schemas/access_user_risk_score_rule" }, { "$ref": "#/components/schemas/access_cloudflare_account_member_rule" } ] }, "access_saas_props": { "type": "object", "properties": { "allowed_idps": { "$ref": "#/components/schemas/access_allowed_idps" }, "app_launcher_visible": { "$ref": "#/components/schemas/access_app_launcher_visible" }, "auto_redirect_to_identity": { "$ref": "#/components/schemas/access_auto_redirect_to_identity-2" }, "custom_pages": { "$ref": "#/components/schemas/access_custom_pages-2" }, "logo_url": { "$ref": "#/components/schemas/access_logo_url" }, "name": { "$ref": "#/components/schemas/access_name-8" }, "saas_app": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/access_saml_saas_app" }, { "$ref": "#/components/schemas/access_oidc_saas_app" } ] }, "scim_config": { "$ref": "#/components/schemas/access_scim_config" }, "tags": { "$ref": "#/components/schemas/access_tags" }, "type": { "allOf": [ { "$ref": "#/components/schemas/access_type" }, { "example": "saas", "type": "string" } ] } }, "title": "SaaS Application" }, "access_saas_props-2": { "type": "object", "properties": { "allowed_idps": { "$ref": "#/components/schemas/access_allowed_idps" }, "app_launcher_visible": { "$ref": "#/components/schemas/access_app_launcher_visible" }, "auto_redirect_to_identity": { "$ref": "#/components/schemas/access_auto_redirect_to_identity-2" }, "logo_url": { "$ref": "#/components/schemas/access_logo_url" }, "name": { "$ref": "#/components/schemas/access_name-8" }, "saas_app": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/access_saml_saas_app-2" }, { "$ref": "#/components/schemas/access_oidc_saas_app-2" } ] }, "type": { "description": "The application type.", "type": "string", "example": "saas" } }, "title": "SaaS Application" }, "access_same_site_cookie_attribute": { "description": "Sets the SameSite cookie setting, which provides increased security against CSRF attacks.", "type": "string", "example": "strict" }, "access_saml": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider" }, { "properties": { "config": { "type": "object", "properties": { "attributes": { "description": "A list of SAML attribute names that will be added to your signed JWT token and can be used in SAML policy rules.", "type": "array", "items": { "type": "string" }, "example": [ "group", "department_code", "divison" ] }, "email_attribute_name": { "description": "The attribute name for email in the SAML response.", "type": "string", "example": "Email", "x-auditable": true }, "enable_encryption": { "description": "Enable SAML assertion encryption. When enabled, the Identity Provider will encrypt \nSAML assertions using the certificate from the assigned certificate set.\n\nTo enable encryption:\n1. Create a certificate set via POST to `/identity_providers/{id}/saml_certificate`\n2. Set this field to `true` and include `saml_certificate_set_id` in the PUT request\n3. Configure the public certificate in your external Identity Provider\n\nNote: Requires `saml_certificate_set_id` to be set when `true`.\n", "type": "boolean", "default": false, "x-auditable": true }, "force_authn": { "description": "Asks the IdP to reauthenticate the user for each SAML authentication request.", "type": "boolean", "default": false, "x-auditable": true }, "header_attributes": { "description": "Add a list of attribute names that will be returned in the response header from the Access callback.", "type": "array", "items": { "properties": { "attribute_name": { "description": "attribute name from the IDP", "type": "string" }, "header_name": { "description": "header that will be added on the request to the origin", "type": "string" } }, "type": "object" } }, "idp_public_certs": { "description": "X509 certificate to verify the signature in the SAML authentication response", "type": "array", "items": { "type": "string" } }, "issuer_url": { "description": "IdP Entity ID or Issuer URL", "type": "string", "example": "https://whoami.com", "x-auditable": true }, "max_sso_url_length": { "description": "The maximum URL length the IdP accepts for the SSO redirect URL.\nWhen the constructed SSO URL would exceed this length, the RelayState\nis stored server-side and a short nonce is passed to the IdP instead.\nSet this if your IdP enforces a URL length limit.\n", "type": "integer", "example": 8192, "maximum": 100000, "minimum": 512, "x-auditable": true }, "sign_request": { "description": "Sign the SAML authentication request with Access credentials. To verify the signature, use the public key from the Access certs endpoints.", "type": "boolean", "default": false }, "sso_target_url": { "description": "URL to send the SAML authentication requests to", "type": "string", "example": "https://edgeaccess.org/idp/saml/login", "x-auditable": true } } } }, "type": "object" } ], "title": "Generic SAML" }, "access_saml-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider-2" }, { "properties": { "config": { "type": "object", "properties": { "attributes": { "description": "A list of SAML attribute names that will be added to your signed JWT token and can be used in SAML policy rules.", "type": "array", "items": { "type": "string" }, "example": [ "group", "department_code", "divison" ] }, "email_attribute_name": { "description": "The attribute name for email in the SAML response.", "type": "string", "example": "Email" }, "force_authn": { "description": "Asks the IdP to reauthenticate the user for each SAML authentication request.", "type": "boolean", "default": false }, "header_attributes": { "description": "Add a list of attribute names that will be returned in the response header from the Access callback.", "type": "array", "items": { "properties": { "attribute_name": { "description": "attribute name from the IDP", "type": "string" }, "header_name": { "description": "header that will be added on the request to the origin", "type": "string" } }, "type": "object" } }, "idp_public_certs": { "description": "X509 certificate to verify the signature in the SAML authentication response", "type": "array", "items": { "type": "string" } }, "issuer_url": { "description": "IdP Entity ID or Issuer URL", "type": "string", "example": "https://whoami.com" }, "max_sso_url_length": { "description": "The maximum URL length the IdP accepts for the SSO redirect URL.\nWhen the constructed SSO URL would exceed this length, the RelayState\nis stored server-side and a short nonce is passed to the IdP instead.\nSet this if your IdP enforces a URL length limit.\n", "type": "integer", "example": 8192, "maximum": 100000, "minimum": 512 }, "sign_request": { "description": "Sign the SAML authentication request with Access credentials. To verify the signature, use the public key from the Access certs endpoints.", "type": "boolean" }, "sso_target_url": { "description": "URL to send the SAML authentication requests to", "type": "string", "example": "https://edgeaccess.org/idp/saml/login" } } } }, "type": "object" } ], "title": "Generic SAML" }, "access_saml_certificate": { "description": "A single SAML encryption certificate with metadata", "type": "object", "properties": { "is_current": { "description": "Indicates whether this is the currently active certificate", "type": "boolean", "example": true }, "not_after": { "description": "Certificate expiration date. Certificates are automatically rotated 30 days before expiration.", "type": "string", "format": "date-time", "example": "2027-05-07T19:11:00Z" }, "public_certificate": { "description": "PEM-encoded X.509 certificate containing the public key.\nConfigure this certificate in your external SAML Identity Provider to enable encryption.\n", "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIEpzCCA4+gAwIBAgIUTh2VSDDJ0oB/gabio6j1L9QwWoUwDQYJKoZIhvcNAQEL\n...\n-----END CERTIFICATE-----\n" }, "uid": { "description": "Unique identifier for the certificate", "type": "string", "format": "uuid", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" } }, "required": [ "uid", "public_certificate", "not_after", "is_current" ] }, "access_saml_certificate-2": { "type": "object", "properties": { "is_current": { "description": "Indicates whether the certificate can be used for IdP configuration.", "type": "boolean", "example": true }, "not_after": { "description": "Certificate expiration date", "type": "string", "format": "date-time", "example": "2027-03-21T12:00:00Z" }, "public_certificate": { "description": "The public certificate in PEM format", "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIGAjCCA+qgAwIBAgIJAI7kymlF7CWT...\n...certificate content...\n-----END CERTIFICATE-----\n" }, "uid": { "description": "Unique identifier for the certificate", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" } }, "required": [ "uid", "public_certificate", "not_after", "is_current" ] }, "access_saml_certificate_set": { "description": "A SAML encryption certificate set containing current and optionally previous certificates for encryption key rotation.", "type": "object", "properties": { "created_at": { "description": "Timestamp when the certificate set was created", "type": "string", "format": "date-time", "example": "2026-05-07T19:16:19.821162Z" }, "current_certificate": { "description": "The currently active certificate used for encrypting SAML assertions", "allOf": [ { "$ref": "#/components/schemas/access_saml_certificate" } ] }, "previous_certificate": { "description": "The previous certificate, maintained during rotation to ensure continuity. Null if no rotation has occurred. Mirrors the structure of `saml_certificate`.", "type": "object", "nullable": true }, "uid": { "description": "Unique identifier for the certificate set", "type": "string", "format": "uuid", "example": "c409ef44-e72c-41c8-8c0b-278c8a6f4fd8" }, "updated_at": { "description": "Timestamp when the certificate set was last updated (e.g., during rotation)", "type": "string", "format": "date-time", "example": "2026-05-07T19:16:19.821162Z" } }, "required": [ "uid", "created_at", "updated_at" ] }, "access_saml_certificate_set-2": { "type": "object", "properties": { "created_at": { "description": "When the certificate set was created", "type": "string", "format": "date-time", "example": "2024-03-21T10:30:00Z" }, "current_certificate": { "description": "The current active certificate", "allOf": [ { "$ref": "#/components/schemas/access_saml_certificate-2" } ] }, "previous_certificate": { "description": "The previous certificate (maintained during rotation period). May be null when no rotation has occurred. Mirrors the structure of `saml_certificate`.", "type": "object", "nullable": true }, "uid": { "description": "Unique identifier for the certificate set", "type": "string", "example": "a5bb4b3f-c2d1-4e6a-8f9b-1d3e4f5a6b7c" }, "updated_at": { "description": "When the certificate set was last updated", "type": "string", "format": "date-time", "example": "2024-03-21T10:30:00Z" } }, "required": [ "uid", "created_at", "updated_at" ] }, "access_saml_certificate_set_response": { "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_saml_certificate_set" } }, "type": "object" } ] }, "access_saml_group_rule": { "description": "Matches a SAML group.\nRequires a SAML identity provider.", "type": "object", "properties": { "saml": { "type": "object", "properties": { "attribute_name": { "description": "The name of the SAML attribute.", "type": "string", "example": "group" }, "attribute_value": { "description": "The SAML attribute value to look for.", "type": "string", "example": "devs@cloudflare.com" }, "identity_provider_id": { "description": "The ID of your SAML identity provider.", "type": "string", "example": "ea85612a-29c8-46c2-bacb-669d65136971" } }, "required": [ "attribute_name", "attribute_value", "identity_provider_id" ] } }, "required": [ "saml" ], "title": "SAML group" }, "access_saml_saas_app": { "type": "object", "properties": { "auth_type": { "description": "Optional identifier indicating the authentication protocol used for the saas app. Required for OIDC. Default if unset is \"saml\"", "type": "string", "example": "saml", "enum": [ "saml", "oidc" ] }, "consumer_service_url": { "description": "The service provider's endpoint that is responsible for receiving and parsing a SAML assertion.", "type": "string", "example": "https://example.com" }, "created_at": { "$ref": "#/components/schemas/access_created_at" }, "custom_attributes": { "type": "array", "items": { "properties": { "friendly_name": { "description": "The SAML FriendlyName of the attribute.", "type": "string", "example": "Last Name" }, "name": { "description": "The name of the attribute.", "type": "string", "example": "family_name" }, "name_format": { "description": "A globally unique name for an identity or service provider.", "type": "string", "example": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic", "enum": [ "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified", "urn:oasis:names:tc:SAML:2.0:attrname-format:basic", "urn:oasis:names:tc:SAML:2.0:attrname-format:uri" ] }, "required": { "description": "If the attribute is required when building a SAML assertion.", "type": "boolean", "example": true }, "source": { "type": "object", "properties": { "name": { "description": "The name of the IdP attribute.", "type": "string", "example": "last_name" }, "name_by_idp": { "description": "A mapping from IdP ID to attribute name.", "type": "array", "items": { "properties": { "idp_id": { "description": "The UID of the IdP.", "type": "string", "example": "exampleIdPID1" }, "source_name": { "description": "The name of the IdP provided attribute.", "type": "string", "example": "AttributeName1" } }, "type": "object" } } } } }, "type": "object" } }, "default_relay_state": { "description": "The URL that the user will be redirected to after a successful login for IDP initiated logins.", "type": "string", "example": "https://example.com" }, "idp_entity_id": { "description": "The unique identifier for your SaaS application.", "type": "string", "example": "https://example.cloudflareaccess.com", "x-stainless-terraform-configurability": "computed_optional" }, "name_id_format": { "description": "The format of the name identifier sent to the SaaS application.", "type": "string", "example": "id", "enum": [ "id", "email" ] }, "name_id_transform_jsonata": { "description": "A [JSONata](https://jsonata.org/) expression that transforms an application's user identities into a NameID value for its SAML assertion. This expression should evaluate to a singular string. The output of this expression can override the `name_id_format` setting.\n", "type": "string", "example": "$substringBefore(email, '@') & '+sandbox@' & $substringAfter(email, '@')" }, "public_key": { "description": "The Access public certificate that will be used to verify your identity.", "type": "string", "example": "example unique name", "x-stainless-terraform-configurability": "computed" }, "saml_attribute_transform_jsonata": { "description": "A [JSONata] (https://jsonata.org/) expression that transforms an application's user identities into attribute assertions in the SAML response. The expression can transform id, email, name, and groups values. It can also transform fields listed in the saml_attributes or oidc_fields of the identity provider used to authenticate. The output of this expression must be a JSON object.\n", "type": "string", "example": "$ ~>| groups | {'group_name': name} |" }, "sp_entity_id": { "description": "A globally unique name for an identity or service provider.", "type": "string", "example": "example unique name" }, "sso_endpoint": { "description": "The endpoint where your SaaS application will send login requests.", "type": "string", "example": "https://example.cloudflareaccess.com/cdn-cgi/access/sso/saml/b3f58a2b414e0b51d45c8c2af26fccca0e27c63763c426fa52f98dcf0b3b3bfd", "x-stainless-terraform-configurability": "computed_optional" }, "updated_at": { "$ref": "#/components/schemas/access_updated_at" } }, "title": "SAML SaaS App" }, "access_saml_saas_app-2": { "type": "object", "properties": { "auth_type": { "description": "Optional identifier indicating the authentication protocol used for the saas app. Required for OIDC. Default if unset is \"saml\"", "type": "string", "example": "saml", "enum": [ "saml", "oidc" ] }, "consumer_service_url": { "description": "The service provider's endpoint that is responsible for receiving and parsing a SAML assertion.", "type": "string", "example": "https://example.com" }, "created_at": { "$ref": "#/components/schemas/access_timestamp" }, "custom_attributes": { "type": "array", "items": { "properties": { "friendly_name": { "description": "The SAML FriendlyName of the attribute.", "type": "string", "example": "Last Name" }, "name": { "description": "The name of the attribute.", "type": "string", "example": "family_name" }, "name_format": { "description": "A globally unique name for an identity or service provider.", "type": "string", "example": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic", "enum": [ "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified", "urn:oasis:names:tc:SAML:2.0:attrname-format:basic", "urn:oasis:names:tc:SAML:2.0:attrname-format:uri" ] }, "required": { "description": "If the attribute is required when building a SAML assertion.", "type": "boolean", "example": true }, "source": { "type": "object", "properties": { "name": { "description": "The name of the IdP attribute.", "type": "string", "example": "last_name" }, "name_by_idp": { "description": "A mapping from IdP ID to attribute name.", "type": "object", "example": { "exampleIdPID1": "AttributeName1", "exampleIdPID2": "AttributeName2" }, "additionalProperties": { "type": "string" } } } } }, "type": "object" } }, "idp_entity_id": { "description": "The unique identifier for your SaaS application.", "type": "string", "example": "https://example.cloudflareaccess.com", "x-stainless-terraform-configurability": "computed_optional" }, "name_id_format": { "description": "The format of the name identifier sent to the SaaS application.", "type": "string", "example": "id", "enum": [ "id", "email" ] }, "name_id_transform_jsonata": { "description": "A [JSONata](https://jsonata.org/) expression that transforms an application's user identities into a NameID value for its SAML assertion. This expression should evaluate to a singular string. The output of this expression can override the `name_id_format` setting.\n", "type": "string", "example": "$substringBefore(email, '@') & '+sandbox@' & $substringAfter(email, '@')" }, "public_key": { "description": "The Access public certificate that will be used to verify your identity.", "type": "string", "example": "example unique name", "x-stainless-terraform-configurability": "computed" }, "sp_entity_id": { "description": "A globally unique name for an identity or service provider.", "type": "string", "example": "example unique name" }, "sso_endpoint": { "description": "The endpoint where your SaaS application will send login requests.", "type": "string", "example": "https://example.cloudflareaccess.com/cdn-cgi/access/sso/saml/b3f58a2b414e0b51d45c8c2af26fccca0e27c63763c426fa52f98dcf0b3b3bfd", "x-stainless-terraform-configurability": "computed_optional" }, "updated_at": { "$ref": "#/components/schemas/access_timestamp" } }, "title": "SAML SaaS App" }, "access_scim_config": { "description": "Configuration for provisioning to this application via SCIM. This is currently in closed beta.", "type": "object", "properties": { "authentication": { "oneOf": [ { "$ref": "#/components/schemas/access_scim_config_single_authentication" }, { "$ref": "#/components/schemas/access_scim_config_multi_authentication" } ] }, "deactivate_on_delete": { "description": "If false, propagates DELETE requests to the target application for SCIM resources. If true, sets 'active' to false on the SCIM resource. Note: Some targets do not support DELETE operations.", "type": "boolean" }, "enabled": { "description": "Whether SCIM provisioning is turned on for this application.", "type": "boolean" }, "idp_uid": { "description": "The UID of the IdP to use as the source for SCIM resources to provision to this application.", "type": "string" }, "mappings": { "description": "A list of mappings to apply to SCIM resources before provisioning them in this application. These can transform or filter the resources to be provisioned.", "type": "array", "items": { "$ref": "#/components/schemas/access_scim_config_mapping" } }, "remote_uri": { "description": "The base URI for the application's SCIM-compatible API.", "type": "string" } }, "required": [ "remote_uri", "idp_uid" ] }, "access_scim_config-2": { "description": "Configuration for provisioning to this application via SCIM. This is currently in closed beta.", "type": "object", "properties": { "authentication": { "oneOf": [ { "$ref": "#/components/schemas/access_scim_config_single_authentication-2" }, { "$ref": "#/components/schemas/access_scim_config_multi_authentication-2" } ] }, "deactivate_on_delete": { "description": "If false, we propagate DELETE requests to the target application for SCIM resources. If true, we only set `active` to false on the SCIM resource. This is useful because some targets do not support DELETE operations.", "type": "boolean" }, "enabled": { "description": "Whether SCIM provisioning is turned on for this application.", "type": "boolean" }, "idp_uid": { "description": "The UID of the IdP to use as the source for SCIM resources to provision to this application.", "type": "string" }, "mappings": { "description": "A list of mappings to apply to SCIM resources before provisioning them in this application. These can transform or filter the resources to be provisioned.", "type": "array", "items": { "$ref": "#/components/schemas/access_scim_config_mapping" } }, "remote_uri": { "description": "The base URI for the application's SCIM-compatible API.", "type": "string" } }, "required": [ "remote_uri", "idp_uid" ] }, "access_scim_config_authentication_access_service_token": { "description": "Attributes for configuring Access Service Token authentication scheme for SCIM provisioning to an application.", "type": "object", "properties": { "client_id": { "description": "Client ID of the Access service token used to authenticate with the remote service.", "type": "string" }, "client_secret": { "description": "Client secret of the Access service token used to authenticate with the remote service.", "type": "string", "x-sensitive": true }, "scheme": { "description": "The authentication scheme to use when making SCIM requests to this application.", "type": "string", "enum": [ "access_service_token" ] } }, "required": [ "scheme", "client_id", "client_secret" ], "title": "Access Service Token" }, "access_scim_config_authentication_http_basic": { "description": "Attributes for configuring HTTP Basic authentication scheme for SCIM provisioning to an application.", "type": "object", "properties": { "password": { "description": "Password used to authenticate with the remote SCIM service.", "type": "string", "x-sensitive": true }, "scheme": { "description": "The authentication scheme to use when making SCIM requests to this application.", "type": "string", "enum": [ "httpbasic" ] }, "user": { "description": "User name used to authenticate with the remote SCIM service.", "type": "string" } }, "required": [ "scheme", "user", "password" ], "title": "HTTP Basic" }, "access_scim_config_authentication_oauth2": { "description": "Attributes for configuring OAuth 2 authentication scheme for SCIM provisioning to an application.", "type": "object", "properties": { "authorization_url": { "description": "URL used to generate the auth code used during token generation.", "type": "string" }, "client_id": { "description": "Client ID used to authenticate when generating a token for authenticating with the remote SCIM service.", "type": "string" }, "client_secret": { "description": "Secret used to authenticate when generating a token for authenticating with the remove SCIM service.", "type": "string", "x-sensitive": true }, "scheme": { "description": "The authentication scheme to use when making SCIM requests to this application.", "type": "string", "enum": [ "oauth2" ] }, "scopes": { "description": "The authorization scopes to request when generating the token used to authenticate with the remove SCIM service.", "type": "array", "items": { "type": "string" } }, "token_url": { "description": "URL used to generate the token used to authenticate with the remote SCIM service.", "type": "string" } }, "required": [ "scheme", "client_id", "client_secret", "authorization_url", "token_url" ], "title": "OAuth 2" }, "access_scim_config_authentication_oauth_bearer_token": { "description": "Attributes for configuring OAuth Bearer Token authentication scheme for SCIM provisioning to an application.", "type": "object", "properties": { "scheme": { "description": "The authentication scheme to use when making SCIM requests to this application.", "type": "string", "enum": [ "oauthbearertoken" ] }, "token": { "description": "Token used to authenticate with the remote SCIM service.", "type": "string", "x-sensitive": true } }, "required": [ "scheme", "token" ], "title": "OAuth Bearer Token" }, "access_scim_config_authentication_oauth_bearer_token-2": { "description": "Attributes for configuring OAuth Bearer Token authentication scheme for SCIM provisioning to an application.", "type": "object", "properties": { "scheme": { "description": "The authentication scheme to use when making SCIM requests to this application.", "type": "string", "enum": [ "oauthbearertoken" ] }, "token": { "description": "Token used to authenticate with the remote SCIM service.", "type": "string" } }, "required": [ "scheme", "token" ], "title": "OAuth Bearer Token" }, "access_scim_config_mapping": { "description": "Transformations and filters applied to resources before they are provisioned in the remote SCIM service.", "type": "object", "properties": { "enabled": { "description": "Whether or not this mapping is enabled.", "type": "boolean" }, "filter": { "description": "A [SCIM filter expression](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2) that matches resources that should be provisioned to this application.", "type": "string", "example": "title pr or userType eq \"Intern\"" }, "operations": { "description": "Whether or not this mapping applies to creates, updates, or deletes.", "type": "object", "properties": { "create": { "description": "Whether or not this mapping applies to create (POST) operations.", "type": "boolean" }, "delete": { "description": "Whether or not this mapping applies to DELETE operations.", "type": "boolean" }, "update": { "description": "Whether or not this mapping applies to update (PATCH/PUT) operations.", "type": "boolean" } } }, "schema": { "description": "Which SCIM resource type this mapping applies to.", "type": "string", "example": "urn:ietf:params:scim:schemas:core:2.0:User" }, "strictness": { "description": "The level of adherence to outbound resource schemas when provisioning to this mapping. ‘Strict’ removes unknown values, while ‘passthrough’ passes unknown values to the target.", "type": "string", "enum": [ "strict", "passthrough" ] }, "transform_jsonata": { "description": "A [JSONata](https://jsonata.org/) expression that transforms the resource before provisioning it in the application.", "type": "string", "example": "$merge([$, {'userName': $substringBefore($.userName, '@') & '+test@' & $substringAfter($.userName, '@')}])" } }, "required": [ "schema" ] }, "access_scim_config_multi_authentication": { "description": "Multiple authentication schemes", "type": "array", "items": { "$ref": "#/components/schemas/access_scim_config_single_authentication" } }, "access_scim_config_multi_authentication-2": { "description": "Multiple authentication schemes", "type": "array", "items": { "$ref": "#/components/schemas/access_scim_config_single_authentication-2" } }, "access_scim_config_single_authentication": { "oneOf": [ { "$ref": "#/components/schemas/access_scim_config_authentication_http_basic" }, { "$ref": "#/components/schemas/access_scim_config_authentication_oauth_bearer_token" }, { "$ref": "#/components/schemas/access_scim_config_authentication_oauth2" }, { "$ref": "#/components/schemas/access_scim_config_authentication_access_service_token" } ] }, "access_scim_config_single_authentication-2": { "oneOf": [ { "$ref": "#/components/schemas/access_scim_config_authentication_http_basic" }, { "$ref": "#/components/schemas/access_scim_config_authentication_oauth_bearer_token-2" }, { "$ref": "#/components/schemas/access_scim_config_authentication_oauth2" }, { "$ref": "#/components/schemas/access_scim_config_authentication_access_service_token" } ] }, "access_scim_groups_response": { "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_groups" } } }, "type": "object" } ] }, "access_scim_update_logs_response": { "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_responses" } } }, "type": "object" } ] }, "access_scim_users_response": { "allOf": [ { "$ref": "#/components/schemas/access_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/access_users" } } }, "type": "object" } ] }, "access_seat": { "type": "object", "properties": { "access_seat": { "$ref": "#/components/schemas/access_access_seat" }, "gateway_seat": { "$ref": "#/components/schemas/access_gateway_seat" }, "seat_uid": { "$ref": "#/components/schemas/access_seat_uid" } }, "required": [ "seat_uid", "gateway_seat", "access_seat" ] }, "access_seat_uid": { "description": "The unique API identifier for the Zero Trust seat.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "x-auditable": true }, "access_seat_uid-2": { "description": "The unique API identifier for the Zero Trust seat.", "type": "string" }, "access_seats": { "type": "object", "properties": { "access_seat": { "$ref": "#/components/schemas/access_access_seat" }, "created_at": { "$ref": "#/components/schemas/access_timestamp" }, "gateway_seat": { "$ref": "#/components/schemas/access_gateway_seat" }, "seat_uid": { "$ref": "#/components/schemas/access_seat_uid" }, "updated_at": { "$ref": "#/components/schemas/access_timestamp" } } }, "access_seats_definition": { "type": "array", "items": { "$ref": "#/components/schemas/access_seat" }, "required": [ "seat_uid", "gateway_seat", "access_seat" ] }, "access_self_hosted_domains": { "description": "List of public domains that Access will secure. This field is deprecated in favor of `destinations` and will be supported until **November 21, 2025.** If `destinations` are provided, then `self_hosted_domains` will be ignored.\n", "type": "array", "items": { "description": "A domain that Access will secure.", "type": "string" }, "example": [ "test.example.com/admin", "test.anotherexample.com/staff" ], "default": [], "deprecated": true }, "access_self_hosted_props": { "type": "object", "properties": { "allow_authenticate_via_warp": { "$ref": "#/components/schemas/access_allow_authenticate_via_warp-2" }, "allow_iframe": { "$ref": "#/components/schemas/access_allow_iframe" }, "allowed_idps": { "$ref": "#/components/schemas/access_allowed_idps" }, "app_launcher_visible": { "$ref": "#/components/schemas/access_app_launcher_visible" }, "auto_redirect_to_identity": { "$ref": "#/components/schemas/access_auto_redirect_to_identity-2" }, "cors_headers": { "$ref": "#/components/schemas/access_cors_headers" }, "custom_deny_message": { "$ref": "#/components/schemas/access_custom_deny_message" }, "custom_deny_url": { "$ref": "#/components/schemas/access_custom_deny_url" }, "custom_non_identity_deny_url": { "$ref": "#/components/schemas/access_custom_non_identity_deny_url" }, "custom_pages": { "$ref": "#/components/schemas/access_custom_pages-2" }, "destinations": { "$ref": "#/components/schemas/access_destinations" }, "domain": { "$ref": "#/components/schemas/access_domain" }, "eager_redirect_cookie_setting": { "$ref": "#/components/schemas/access_eager_redirect_cookie_setting" }, "enable_binding_cookie": { "$ref": "#/components/schemas/access_enable_binding_cookie" }, "http_only_cookie_attribute": { "$ref": "#/components/schemas/access_http_only_cookie_attribute" }, "logo_url": { "$ref": "#/components/schemas/access_logo_url" }, "mfa_config": { "$ref": "#/components/schemas/access_mfa_config" }, "name": { "$ref": "#/components/schemas/access_name-8" }, "oauth_configuration": { "$ref": "#/components/schemas/access_oauth_configuration" }, "options_preflight_bypass": { "$ref": "#/components/schemas/access_options_preflight_bypass" }, "path_cookie_attribute": { "$ref": "#/components/schemas/access_path_cookie_attribute" }, "read_service_tokens_from_header": { "$ref": "#/components/schemas/access_read_service_tokens_from_header" }, "same_site_cookie_attribute": { "$ref": "#/components/schemas/access_same_site_cookie_attribute" }, "scim_config": { "$ref": "#/components/schemas/access_scim_config" }, "self_hosted_domains": { "$ref": "#/components/schemas/access_self_hosted_domains" }, "service_auth_401_redirect": { "$ref": "#/components/schemas/access_service_auth_401_redirect" }, "session_duration": { "$ref": "#/components/schemas/access_session_duration-2" }, "skip_interstitial": { "$ref": "#/components/schemas/access_skip_interstitial" }, "tags": { "$ref": "#/components/schemas/access_tags" }, "type": { "allOf": [ { "$ref": "#/components/schemas/access_type" }, { "example": "self_hosted", "type": "string" } ] }, "use_clientless_isolation_app_launcher_url": { "$ref": "#/components/schemas/access_use_clientless_isolation_app_launcher_url" } }, "required": [ "type", "domain" ], "title": "Self Hosted Application" }, "access_self_hosted_props-2": { "type": "object", "properties": { "allow_iframe": { "$ref": "#/components/schemas/access_allow_iframe" }, "allowed_idps": { "$ref": "#/components/schemas/access_allowed_idps" }, "app_launcher_visible": { "$ref": "#/components/schemas/access_app_launcher_visible" }, "auto_redirect_to_identity": { "$ref": "#/components/schemas/access_auto_redirect_to_identity-2" }, "cors_headers": { "$ref": "#/components/schemas/access_cors_headers" }, "custom_deny_message": { "$ref": "#/components/schemas/access_custom_deny_message" }, "custom_deny_url": { "$ref": "#/components/schemas/access_custom_deny_url-2" }, "domain": { "$ref": "#/components/schemas/access_domain-3" }, "eager_redirect_cookie_setting": { "$ref": "#/components/schemas/access_eager_redirect_cookie_setting" }, "enable_binding_cookie": { "$ref": "#/components/schemas/access_enable_binding_cookie" }, "http_only_cookie_attribute": { "$ref": "#/components/schemas/access_http_only_cookie_attribute" }, "logo_url": { "$ref": "#/components/schemas/access_logo_url" }, "name": { "$ref": "#/components/schemas/access_name-8" }, "options_preflight_bypass": { "$ref": "#/components/schemas/access_options_preflight_bypass-2" }, "same_site_cookie_attribute": { "$ref": "#/components/schemas/access_same_site_cookie_attribute" }, "service_auth_401_redirect": { "$ref": "#/components/schemas/access_service_auth_401_redirect" }, "session_duration": { "$ref": "#/components/schemas/access_session_duration-4" }, "skip_interstitial": { "$ref": "#/components/schemas/access_skip_interstitial" }, "type": { "description": "The application type.", "type": "string", "example": "self_hosted" }, "use_clientless_isolation_app_launcher_url": { "$ref": "#/components/schemas/access_use_clientless_isolation_app_launcher_url" } }, "required": [ "type", "domain" ], "title": "Self Hosted Application" }, "access_service-tokens": { "type": "object", "properties": { "client_id": { "$ref": "#/components/schemas/access_client_id" }, "created_at": { "$ref": "#/components/schemas/access_created_at" }, "duration": { "$ref": "#/components/schemas/access_duration" }, "enabled": { "$ref": "#/components/schemas/access_enabled" }, "expires_at": { "$ref": "#/components/schemas/access_timestamp" }, "id": { "allOf": [ { "description": "The ID of the service token.", "type": "string" }, { "$ref": "#/components/schemas/access_uuid" } ] }, "last_seen_at": { "allOf": [ { "type": "string", "x-stainless-skip": true }, { "$ref": "#/components/schemas/access_timestamp" } ] }, "name": { "$ref": "#/components/schemas/access_name-2" }, "updated_at": { "$ref": "#/components/schemas/access_updated_at" } } }, "access_service-tokens-2": { "type": "object", "properties": { "client_id": { "$ref": "#/components/schemas/access_client_id" }, "created_at": { "$ref": "#/components/schemas/access_timestamp" }, "duration": { "$ref": "#/components/schemas/access_duration-2" }, "enabled": { "$ref": "#/components/schemas/access_enabled" }, "expires_at": { "$ref": "#/components/schemas/access_timestamp" }, "id": { "allOf": [ { "description": "The ID of the service token.", "type": "string" }, { "$ref": "#/components/schemas/access_uuid" } ] }, "last_seen_at": { "$ref": "#/components/schemas/access_timestamp" }, "name": { "$ref": "#/components/schemas/access_name-17" }, "updated_at": { "$ref": "#/components/schemas/access_timestamp" } } }, "access_service_auth_401_redirect": { "description": "Returns a 401 status code when the request is blocked by a Service Auth policy.", "type": "boolean", "example": true }, "access_service_token_rule": { "description": "Matches a specific Access Service Token", "type": "object", "properties": { "service_token": { "type": "object", "properties": { "token_id": { "description": "The ID of a Service Token.", "type": "string", "example": "aa0a4aab-672b-4bdb-bc33-a59f1130a11f" } }, "required": [ "token_id" ] } }, "required": [ "service_token" ], "title": "Service Token" }, "access_session_duration": { "description": "The amount of time that tokens issued for applications will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h.", "type": "string", "example": "24h" }, "access_session_duration-2": { "description": "The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h. Note: unsupported for infrastructure type applications.", "type": "string", "example": "24h", "default": "24h" }, "access_session_duration-3": { "description": "The amount of time that tokens issued for the application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h.", "type": "string", "example": "24h", "nullable": true }, "access_session_duration-4": { "description": "The amount of time that tokens issued for this application will be valid. Must be in the format `300ms` or `2h45m`. Valid time units are: ns, us (or µs), ms, s, m, h.", "type": "string", "example": "24h", "default": "24h" }, "access_settings": { "type": "object", "properties": { "china_network": { "description": "Request client certificates for this hostname in China. Can only be set to true if this zone is china network enabled.", "type": "boolean", "example": false, "x-auditable": true }, "client_certificate_forwarding": { "description": "Client Certificate Forwarding is a feature that takes the client cert provided by the eyeball to the edge, and forwards it to the origin as a HTTP header to allow logging on the origin.", "type": "boolean", "example": true, "x-auditable": true }, "hostname": { "description": "The hostname that these settings apply to.", "type": "string", "example": "admin.example.com", "x-auditable": true } }, "additionalProperties": false, "required": [ "hostname", "china_network", "client_certificate_forwarding" ], "title": "Hostname Settings" }, "access_settings-2": { "type": "object", "properties": { "china_network": { "description": "Request client certificates for this hostname in China. Can only be set to true if this zone is china network enabled.", "type": "boolean", "example": false }, "client_certificate_forwarding": { "description": "Client Certificate Forwarding is a feature that takes the client cert provided by the eyeball to the edge, and forwards it to the origin as a HTTP header to allow logging on the origin.", "type": "boolean", "example": true }, "hostname": { "description": "The hostname that these settings apply to.", "type": "string", "example": "admin.example.com" } }, "additionalProperties": false, "required": [ "hostname", "china_network", "client_certificate_forwarding" ], "title": "Hostname Settings" }, "access_since": { "description": "the timestamp of the earliest update log.", "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z" }, "access_single_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "type": "object" }, { "properties": { "result": { "$ref": "#/components/schemas/access_organizations" } }, "type": "object" } ] }, "access_single_response-10": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_reusable_policy_resp" } }, "type": "object" } ] }, "access_single_response-11": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_custom_page" } }, "type": "object" } ] }, "access_single_response-12": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_key_config" } }, "type": "object" } ] }, "access_single_response-13": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_bookmarks" } }, "type": "object" } ] }, "access_single_response-14": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_tag" } }, "type": "object" } ] }, "access_single_response-15": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_organizations-2" } }, "type": "object" } ] }, "access_single_response-16": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_identity-providers-2" } }, "type": "object" } ] }, "access_single_response-17": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_groups-3" } }, "type": "object" } ] }, "access_single_response-18": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_service-tokens-2" } }, "type": "object" } ] }, "access_single_response-19": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_ca-2" } }, "type": "object" } ] }, "access_single_response-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_service-tokens" } }, "type": "object" } ] }, "access_single_response-20": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_certificates-3" } }, "type": "object" } ] }, "access_single_response-21": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_apps" } }, "type": "object" } ] }, "access_single_response-22": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_policies" } }, "type": "object" } ] }, "access_single_response-3": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_identity-providers" } }, "type": "object" } ] }, "access_single_response-4": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_groups-2" } }, "type": "object" } ] }, "access_single_response-5": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_ca" } }, "type": "object" } ] }, "access_single_response-6": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_certificates" } }, "type": "object" } ] }, "access_single_response-7": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_certificates-2" } }, "type": "object" } ] }, "access_single_response-8": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_app_response" } }, "type": "object" } ] }, "access_single_response-9": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_app_policy_result" } }, "type": "object" } ] }, "access_single_response_update": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_app_settings_response" } }, "type": "object" } ] }, "access_single_response_without_html": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_custom_page_without_html" } }, "type": "object" } ] }, "access_single_user_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_users-2" } }, "type": "object" } ] }, "access_skip_app_launcher_login_page": { "description": "Determines when to skip the App Launcher landing page.", "type": "boolean", "example": true, "default": false }, "access_skip_interstitial": { "description": "Enables automatic authentication through cloudflared.", "type": "boolean", "example": true }, "access_ssh_props": { "allOf": [ { "$ref": "#/components/schemas/access_self_hosted_props" }, { "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/access_type" }, { "example": "ssh", "type": "string" } ] } }, "type": "object" } ] }, "access_ssh_props-2": { "allOf": [ { "$ref": "#/components/schemas/access_self_hosted_props-2" }, { "properties": { "type": { "description": "The application type.", "type": "string", "example": "ssh" } }, "type": "object" } ] }, "access_status": { "description": "The status of the policy test request.", "type": "string", "example": "success", "enum": [ "success" ], "x-auditable": true }, "access_status-2": { "description": "The status of the SCIM request.", "type": "array", "items": { "enum": [ "FAILURE", "SUCCESS" ], "type": "string" }, "example": [ "FAILURE", "SUCCESS" ] }, "access_string_key_map_device_session": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/access_device_session" } }, "access_tag": { "description": "A tag", "type": "object", "properties": { "app_count": { "description": "The number of applications that have this tag", "type": "integer", "example": 1, "x-auditable": true, "x-stainless-skip": true }, "created_at": { "$ref": "#/components/schemas/access_created_at" }, "name": { "$ref": "#/components/schemas/access_name-13" }, "updated_at": { "$ref": "#/components/schemas/access_updated_at" } }, "required": [ "name" ] }, "access_tag_without_app_count": { "description": "A tag", "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/access_created_at" }, "name": { "$ref": "#/components/schemas/access_name-13" }, "updated_at": { "$ref": "#/components/schemas/access_updated_at" } }, "required": [ "name" ] }, "access_tags": { "description": "The tags you want assigned to an application. Tags are used to filter applications in the App Launcher dashboard.", "type": "array", "items": { "description": "The tag associated with an application.", "example": "engineers", "type": "string" }, "default": [], "x-stainless-collection-type": "set" }, "access_target_attributes": { "description": "Contains a map of target attribute keys to target attribute values.", "type": "object", "example": { "hostname": [ "test-server", "production-server" ] }, "additionalProperties": { "example": [ "test-server", "production-server" ], "items": { "type": "string" }, "type": "array" }, "deprecated": true }, "access_target_criteria_base": { "description": "Defines targets covered by the application. Use either the legacy top-level target_attributes format or the rule format, but not both. The rule format requires include; require and exclude are optional.", "type": "object", "properties": { "exclude": { "description": "Target is excluded when any selector in this rule matches.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_target_rule" } ] }, "include": { "description": "Target matches when any selector in this rule matches.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_target_rule" } ] }, "port": { "type": "integer", "allOf": [ { "$ref": "#/components/schemas/access_port" } ] }, "require": { "description": "Target matches only when every selector in this rule matches.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_target_rule" } ] }, "target_attributes": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_target_attributes" } ] } }, "oneOf": [ { "not": { "anyOf": [ { "required": [ "include" ], "type": "object" }, { "required": [ "require" ], "type": "object" }, { "required": [ "exclude" ], "type": "object" } ], "type": "object" }, "required": [ "target_attributes" ], "type": "object" }, { "not": { "required": [ "target_attributes" ], "type": "object" }, "required": [ "include" ], "type": "object" } ], "required": [ "port", "protocol" ], "title": "Target Criteria" }, "access_target_criteria_infra_app": { "allOf": [ { "$ref": "#/components/schemas/access_target_criteria_base" }, { "properties": { "protocol": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/access_protocol_infra_app" } ] } }, "type": "object" } ] }, "access_target_criteria_self_hosted_app": { "allOf": [ { "$ref": "#/components/schemas/access_target_criteria_base" }, { "properties": { "protocol": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/access_protocol_self_hosted_app" } ] } }, "type": "object" } ] }, "access_target_rule": { "description": "Selectors within an include, require, or exclude rule. At least one of target_attributes or tags must be non-empty.", "type": "object", "properties": { "tags": { "description": "Map of target tag keys to values. Values within a key are OR'd.", "type": "object", "example": { "environment": [ "production" ] }, "additionalProperties": { "items": { "minLength": 1, "type": "string" }, "maxItems": 50, "minItems": 1, "type": "array" }, "maxProperties": 50, "minProperties": 1 }, "target_attributes": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_target_rule_attributes" } ] } }, "additionalProperties": false, "minProperties": 1, "title": "Target Rule" }, "access_target_rule_attributes": { "description": "Hostname selector map for include, require, or exclude rules. This is distinct from the deprecated top-level target_attributes field and only supports the hostname key.", "type": "object", "properties": { "hostname": { "type": "array", "items": { "minLength": 1, "type": "string" }, "maxItems": 5000, "minItems": 1 } }, "example": { "hostname": [ "web-*" ] }, "additionalProperties": false, "maxProperties": 1, "minProperties": 1 }, "access_template_violation": { "description": "A single validation finding for a template.", "type": "object", "properties": { "message": { "description": "Human-readable description of the finding.", "type": "string", "x-auditable": true }, "ref": { "description": "Optional pointer to the part of the template the finding refers to.", "type": "string", "x-auditable": true }, "tier": { "description": "The validation tier that produced the finding (e.g. html, liquid).", "type": "string", "x-auditable": true } }, "required": [ "tier", "message" ] }, "access_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "x-auditable": true }, "access_title": { "description": "The title shown on the landing page.", "type": "string", "example": "Welcome back!", "default": "Welcome!" }, "access_total_users": { "description": "The total number of users in the user base.", "type": "integer", "example": 20, "x-auditable": true }, "access_type": { "description": "The application type.", "type": "string", "example": "self_hosted", "enum": [ "self_hosted", "saas", "ssh", "vnc", "app_launcher", "warp", "biso", "bookmark", "dash_sso", "infrastructure", "rdp", "mcp", "mcp_portal", "proxy_endpoint" ] }, "access_type-2": { "description": "Custom page type.", "type": "string", "enum": [ "identity_denied", "forbidden", "login", "interstitial" ], "x-auditable": true }, "access_type-3": { "description": "The application type.", "type": "string", "example": "self_hosted", "enum": [ "self_hosted", "saas", "ssh", "vnc", "app_launcher", "warp", "biso", "bookmark", "dash_sso" ] }, "access_ui_read_only_toggle_reason": { "description": "A description of the reason why the UI read only field is being toggled.", "type": "string", "example": "Temporarily turn off the UI read only lock to make a change via the UI", "x-stainless-terraform-configurability": "computed_optional" }, "access_uid": { "description": "The unique API identifier for the user.", "type": "string" }, "access_until": { "description": "the timestamp of the most-recent update log.", "type": "string", "format": "date-time", "example": "2025-01-02T00:00:00Z" }, "access_update_status": { "description": "The status of the policy test.", "type": "string", "example": "complete", "enum": [ "blocked", "processing", "exceeded time", "complete" ], "x-auditable": true }, "access_updated_at": { "allOf": [ { "type": "string", "x-stainless-skip": true }, { "$ref": "#/components/schemas/access_timestamp" } ] }, "access_use_clientless_isolation_app_launcher_url": { "description": "Determines if users can access this application via a clientless browser isolation URL.\nThis allows users to access private domains without connecting to Gateway. The option requires\nClientless Browser Isolation to be set up with policies that allow users of this application.\n", "type": "boolean", "example": false, "default": false }, "access_user_id": { "description": "The UUID of the authenticating user.", "type": "string", "format": "uuid", "example": "f757c5c3-c1b2-50f7-9126-150a099b6f7e" }, "access_user_result": { "description": "Policy evaluation result for an individual user.", "type": "string", "example": "approved", "enum": [ "approved", "blocked", "error" ], "x-auditable": true }, "access_user_risk_score_rule": { "description": "Matches a user's risk score.", "type": "object", "properties": { "user_risk_score": { "type": "object", "properties": { "user_risk_score": { "description": "A list of risk score levels to match. Values can be low, medium, high, or unscored.", "type": "array", "items": { "enum": [ "low", "medium", "high", "unscored" ], "type": "string" }, "example": [ "low", "medium" ], "minItems": 1 } }, "required": [ "user_risk_score" ] } }, "required": [ "user_risk_score" ], "title": "User Risk Score" }, "access_user_seat_expiration_inactive_time": { "description": "The amount of time a user seat is inactive before it expires. When the user seat exceeds the set time of inactivity, the user is removed as an active seat and no longer counts against your Teams seat count. Minimum value for this setting is 1 month (730h). Must be in the format `300ms` or `2h45m`. Valid time units are: `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.", "type": "string", "example": "730h", "x-auditable": true }, "access_user_seat_expiration_inactive_time-2": { "description": "The amount of time a user seat is inactive before it expires. When the user seat exceeds the set time of inactivity, the user is removed as an active seat and no longer counts against your Teams seat count. Must be in the format `300ms` or `2h45m`. Valid time units are: `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.", "type": "string", "example": "720h" }, "access_username": { "description": "The username of the SCIM User resource.", "type": "string", "example": "John Smith" }, "access_usernames": { "description": "Contains the Unix usernames that may be used when connecting over SSH.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "root", "ubuntu" ] }, "access_users": { "type": "object", "properties": { "active": { "description": "Determines the status of the SCIM User resource.", "type": "boolean", "example": true }, "displayName": { "description": "The name of the SCIM User resource.", "type": "string", "example": "John Smith" }, "emails": { "type": "array", "items": { "properties": { "primary": { "description": "Indicates if the email address is the primary email belonging to the SCIM User resource.", "type": "boolean", "example": true }, "type": { "description": "Indicates the type of the email address.", "type": "string", "example": "work" }, "value": { "description": "The email address of the SCIM User resource.", "type": "string", "format": "email", "example": "john.smith@example.com" } }, "type": "object" } }, "externalId": { "description": "The IdP-generated Id of the SCIM resource.", "type": "string", "example": "john_smith" }, "id": { "$ref": "#/components/schemas/access_id" }, "meta": { "$ref": "#/components/schemas/access_meta" }, "schemas": { "description": "The list of URIs which indicate the attributes contained within a SCIM resource.", "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:schemas:core:2.0:User" ] } } }, "access_users-2": { "type": "object", "properties": { "access_seat": { "$ref": "#/components/schemas/access_access_seat-2" }, "active_device_count": { "$ref": "#/components/schemas/access_active_device_count" }, "created_at": { "$ref": "#/components/schemas/access_timestamp" }, "email": { "$ref": "#/components/schemas/access_email-2" }, "gateway_seat": { "$ref": "#/components/schemas/access_gateway_seat-2" }, "id": { "$ref": "#/components/schemas/access_uuid" }, "last_successful_login": { "$ref": "#/components/schemas/access_last_successful_login" }, "name": { "$ref": "#/components/schemas/access_name-10" }, "seat_uid": { "$ref": "#/components/schemas/access_seat_uid-2" }, "uid": { "$ref": "#/components/schemas/access_uid" }, "updated_at": { "$ref": "#/components/schemas/access_timestamp" } } }, "access_users_approved": { "description": "The number of (processed) users approved based on policy evaluation results.", "type": "integer", "example": 5, "x-auditable": true }, "access_users_blocked": { "description": "The number of (processed) users blocked based on policy evaluation results.", "type": "integer", "example": 5, "x-auditable": true }, "access_users_errored": { "description": "The number of (processed) users errored based on policy evaluation results.", "type": "integer", "example": 5 }, "access_uuid": { "description": "UUID.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "x-auditable": true }, "access_uuid-2": { "description": "The UUID of the policy", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36 }, "access_validate_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/access_validation_result" } }, "type": "object" } ] }, "access_validation_result": { "description": "The result of validating a template's content.", "type": "object", "properties": { "errors": { "description": "Blocking findings; a non-empty list means the template cannot be published.", "type": "array", "items": { "$ref": "#/components/schemas/access_template_violation" } }, "page_type": { "$ref": "#/components/schemas/access_type-2" }, "version": { "description": "The contract version the template was validated against.", "type": "integer", "x-auditable": true }, "warnings": { "description": "Advisory findings that do not block publishing.", "type": "array", "items": { "$ref": "#/components/schemas/access_template_violation" } } }, "required": [ "page_type", "version", "errors", "warnings" ] }, "access_vnc_props": { "allOf": [ { "$ref": "#/components/schemas/access_self_hosted_props" }, { "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/access_type" }, { "example": "vnc", "type": "string" } ] } }, "type": "object" } ] }, "access_vnc_props-2": { "allOf": [ { "$ref": "#/components/schemas/access_self_hosted_props-2" }, { "properties": { "type": { "description": "The application type.", "type": "string", "example": "vnc" } }, "type": "object" } ] }, "access_warp_auth_non_browser_401": { "description": "When enabled, unsuccessful WARP authentication requests with a non-HTML Accept header return a 401 response instead of redirecting to the login page.", "type": "boolean", "example": false, "default": false, "x-auditable": true }, "access_warp_auth_session_duration": { "description": "The amount of time that tokens issued for applications will be valid. Must be in the format `30m` or `2h45m`. Valid time units are: m, h.", "type": "string", "example": "24h", "x-auditable": true }, "access_warp_props": { "allOf": [ { "$ref": "#/components/schemas/access_feature_app_props" }, { "properties": { "domain": { "type": "string", "example": "authdomain.cloudflareaccess.com/warp", "readOnly": true }, "name": { "type": "string", "example": "Warp Login App", "default": "Warp Login App", "readOnly": true }, "type": { "allOf": [ { "$ref": "#/components/schemas/access_type" }, { "example": "warp", "type": "string" } ] } }, "type": "object" } ] }, "access_warp_props-2": { "allOf": [ { "$ref": "#/components/schemas/access_feature_app_props-2" }, { "properties": { "domain": { "type": "string", "example": "authdomain.cloudflareaccess.com/warp", "readOnly": true }, "name": { "type": "string", "example": "Warp Login App", "default": "Warp Login App", "readOnly": true }, "type": { "description": "The application type.", "type": "string", "example": "warp" } }, "type": "object" } ] }, "access_yandex": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider" }, { "properties": { "config": { "$ref": "#/components/schemas/access_generic-oauth-config" } }, "type": "object" } ], "title": "Yandex" }, "access_yandex-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/access_identity-provider-2" }, { "properties": { "config": { "$ref": "#/components/schemas/access_generic-oauth-config-2" } }, "type": "object" } ], "title": "Yandex" }, "addressing_account_identifier": { "description": "Identifier of a Cloudflare account.", "type": "string", "example": "258def64c72dae45f3e4c8516e2111f2", "maxLength": 32, "x-auditable": true }, "addressing_account_identifier-2": { "description": "Identifier of a Cloudflare account.", "type": "string", "example": "258def64c72dae45f3e4c8516e2111f2", "maxLength": 32 }, "addressing_address-maps": { "type": "object", "properties": { "can_delete": { "$ref": "#/components/schemas/addressing_can_delete" }, "can_modify_ips": { "$ref": "#/components/schemas/addressing_can_modify_ips" }, "created_at": { "$ref": "#/components/schemas/addressing_timestamp" }, "default_sni": { "$ref": "#/components/schemas/addressing_default_sni" }, "description": { "$ref": "#/components/schemas/addressing_description-2" }, "enabled": { "$ref": "#/components/schemas/addressing_enabled" }, "id": { "$ref": "#/components/schemas/addressing_address_map_identifier" }, "modified_at": { "$ref": "#/components/schemas/addressing_timestamp" } } }, "addressing_address-maps-ip": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/addressing_timestamp" }, "ip": { "$ref": "#/components/schemas/addressing_ip" } } }, "addressing_address-maps-membership": { "type": "object", "properties": { "can_delete": { "$ref": "#/components/schemas/addressing_can_delete-2" }, "created_at": { "$ref": "#/components/schemas/addressing_timestamp" }, "identifier": { "$ref": "#/components/schemas/addressing_identifier" }, "kind": { "$ref": "#/components/schemas/addressing_kind" } } }, "addressing_address-maps-membership-request": { "type": "object", "properties": { "identifier": { "$ref": "#/components/schemas/addressing_identifier" }, "kind": { "$ref": "#/components/schemas/addressing_kind" } } }, "addressing_address_map_identifier": { "description": "Identifier of an Address Map.", "type": "string", "example": "055817b111884e0227e1be16a0be6ee0", "maxLength": 32, "x-auditable": true }, "addressing_advertised": { "description": "Prefix advertisement status to the Internet. This field is only not 'null' if on demand is enabled.", "type": "boolean", "example": true, "deprecated": true, "nullable": true, "x-auditable": true, "x-stainless-deprecation-message": "Prefer the [BGP Prefixes API](https://developers.cloudflare.com/api/resources/addressing/subresources/prefixes/subresources/bgp_prefixes/) instead, which allows for advertising multiple BGP routes within a single IP Prefix." }, "addressing_advertised-2": { "description": "Prefix advertisement status to the Internet. This field is only not 'null' if on demand is enabled.", "type": "boolean", "example": true, "nullable": true, "x-auditable": true }, "addressing_advertised-3": { "description": "Advertisement status of the prefix. If `true`, the BGP route for the prefix is advertised to the Internet. If \n`false`, the BGP route is withdrawn.\n", "type": "boolean", "example": true, "x-auditable": true }, "addressing_advertised_modified_at_nullable": { "description": "Last time the advertisement status was changed. This field is only not 'null' if on demand is enabled.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "deprecated": true, "nullable": true, "x-auditable": true, "x-stainless-deprecation-message": "Prefer the [BGP Prefixes API](https://developers.cloudflare.com/api/resources/addressing/subresources/prefixes/subresources/bgp_prefixes/) instead, which allows for advertising multiple BGP routes within a single IP Prefix." }, "addressing_advertised_response": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "advertised": { "$ref": "#/components/schemas/addressing_advertised-3" }, "advertised_modified_at": { "$ref": "#/components/schemas/addressing_modified_at_nullable" } } } }, "type": "object" } ] }, "addressing_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "addressing_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/addressing_messages" }, "messages": { "$ref": "#/components/schemas/addressing_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "addressing_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/addressing_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/addressing_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "addressing_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-common" } ] }, "addressing_approved": { "description": "Approval state of the prefix (P = pending, V = active).", "type": "string", "example": "P", "x-auditable": true }, "addressing_asn": { "description": "Autonomous System Number (ASN) the prefix will be advertised under.", "type": "integer", "example": 13335, "x-auditable": true }, "addressing_asn-2": { "description": "Autonomous System Number (ASN) the prefix will be advertised under.", "type": "integer", "example": 13335, "nullable": true, "x-auditable": true }, "addressing_asn_prepend_count": { "description": "Number of times to prepend the Cloudflare ASN to the BGP AS-Path attribute", "type": "integer", "example": 2, "default": 0, "maximum": 3, "minimum": 0, "x-auditable": true }, "addressing_auto_advertise_withdraw": { "description": "Determines if Cloudflare advertises a BYOIP BGP prefix even when there is no matching BGP prefix in the Magic routing table. When true, Cloudflare will automatically withdraw the BGP prefix when there are no matching BGP routes, and will resume advertising when there is at least one matching BGP route.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "addressing_auto_generated": { "description": "Whether the LOA has been auto-generated for the prefix owner by Cloudflare.", "type": "boolean", "example": true, "x-auditable": true }, "addressing_bgp_on_demand": { "type": "object", "properties": { "advertised": { "$ref": "#/components/schemas/addressing_advertised-2" }, "advertised_modified_at": { "$ref": "#/components/schemas/addressing_modified_at_nullable" }, "on_demand_enabled": { "$ref": "#/components/schemas/addressing_on_demand_enabled-2" }, "on_demand_locked": { "$ref": "#/components/schemas/addressing_on_demand_locked-2" } } }, "addressing_bgp_prefix_create": { "type": "object", "properties": { "cidr": { "$ref": "#/components/schemas/addressing_cidr" } }, "required": [ "cidr" ] }, "addressing_bgp_prefix_identifier": { "description": "Identifier of BGP Prefix.", "type": "string", "example": "7009ba364c7a5760798ceb430e603b74", "maxLength": 32, "x-auditable": true }, "addressing_bgp_prefix_update_advertisement": { "type": "object", "properties": { "asn_prepend_count": { "$ref": "#/components/schemas/addressing_asn_prepend_count" }, "auto_advertise_withdraw": { "$ref": "#/components/schemas/addressing_auto_advertise_withdraw" }, "on_demand": { "type": "object", "properties": { "advertised": { "type": "boolean" } } } } }, "addressing_bgp_signal_opts": { "type": "object", "properties": { "enabled": { "$ref": "#/components/schemas/addressing_bgp_signaling_enabled" }, "modified_at": { "$ref": "#/components/schemas/addressing_bgp_signaling_modified_at" } } }, "addressing_bgp_signaling_enabled": { "description": "Whether control of advertisement of the prefix to the Internet is enabled to be performed via BGP signal", "type": "boolean", "example": false, "x-auditable": true }, "addressing_bgp_signaling_modified_at": { "description": "Last time BGP signaling control was toggled. This field is null if BGP signaling has never been enabled.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "nullable": true, "x-auditable": true }, "addressing_can_delete": { "description": "If set to false, then the Address Map cannot be deleted via API. This is true for Cloudflare-managed maps.", "type": "boolean", "example": true, "readOnly": true, "x-auditable": true }, "addressing_can_delete-2": { "description": "Controls whether the membership can be deleted via the API or not.", "type": "boolean", "example": true, "readOnly": true, "x-auditable": true }, "addressing_can_modify_ips": { "description": "If set to false, then the IPs on the Address Map cannot be modified via the API. This is true for Cloudflare-managed maps.", "type": "boolean", "example": true, "readOnly": true, "x-auditable": true }, "addressing_cidr": { "description": "IP Prefix in Classless Inter-Domain Routing format.", "type": "string", "example": "192.0.2.0/24", "x-auditable": true }, "addressing_cidr-2": { "description": "IP Prefix in Classless Inter-Domain Routing format.", "type": "string", "example": "192.0.2.0/24" }, "addressing_create_binding_request": { "type": "object", "properties": { "cidr": { "$ref": "#/components/schemas/addressing_cidr" }, "service_id": { "$ref": "#/components/schemas/addressing_service_identifier" } }, "required": [ "cidr", "service_id" ] }, "addressing_created_at": { "description": "Timestamp of the moment the object was created.", "type": "string", "format": "date-time" }, "addressing_default_sni": { "description": "If you have legacy TLS clients which do not send the TLS server name indicator, then you can specify one default SNI on the map. If Cloudflare receives a TLS handshake from a client without an SNI, it will respond with the default SNI on those IPs. The default SNI can be any valid zone or subdomain owned by the account.", "type": "string", "example": "*.example.com", "nullable": true, "x-auditable": true }, "addressing_delegate_loa_creation": { "description": "Whether Cloudflare is allowed to generate the LOA document on behalf of the prefix owner.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "addressing_delegated_account_identifier": { "description": "Account identifier for the account to which prefix is being delegated.", "type": "string", "example": "b1946ac92492d2347c6235b4d2611184", "maxLength": 32, "x-auditable": true }, "addressing_delegation_identifier": { "description": "Identifier of a Delegation.", "type": "string", "example": "d933b1530bc56c9953cf8ce166da8004", "maxLength": 32, "readOnly": true, "x-auditable": true }, "addressing_description": { "description": "Description of the prefix.", "type": "string", "example": "Internal test prefix", "maxLength": 1000, "x-auditable": true }, "addressing_description-2": { "description": "An optional description field which may be used to describe the types of IPs or zones on the map.", "type": "string", "example": "My Ecommerce zones", "nullable": true, "x-auditable": true }, "addressing_enabled": { "description": "Whether the Address Map is enabled or not. Cloudflare's DNS will not respond with IP addresses on an Address Map until the map is enabled.", "type": "boolean", "example": true, "default": false, "nullable": true, "x-auditable": true }, "addressing_filename": { "description": "Name of LOA document. Max file size 10MB, and supported filetype is pdf.", "type": "string", "example": "site_loa_doc.pdf", "x-auditable": true }, "addressing_full_response": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-single" }, { "properties": { "result": { "allOf": [ { "$ref": "#/components/schemas/addressing_address-maps" }, { "properties": { "ips": { "$ref": "#/components/schemas/addressing_ips" }, "memberships": { "$ref": "#/components/schemas/addressing_memberships" } }, "type": "object" } ] } }, "type": "object" } ] }, "addressing_id_response": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/addressing_delegation_identifier" } } } }, "type": "object" } ] }, "addressing_identifier": { "description": "The identifier for the membership (eg. a zone or account tag).", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "addressing_ip": { "description": "An IPv4 or IPv6 address.", "type": "string", "example": "192.0.2.1", "x-auditable": true }, "addressing_ip_address": { "description": "An IPv4 or IPv6 address.", "type": "string", "example": "192.0.2.1", "x-auditable": true }, "addressing_ipam-bgp-prefixes": { "type": "object", "properties": { "asn": { "$ref": "#/components/schemas/addressing_asn-2" }, "asn_prepend_count": { "$ref": "#/components/schemas/addressing_asn_prepend_count" }, "auto_advertise_withdraw": { "$ref": "#/components/schemas/addressing_auto_advertise_withdraw" }, "bgp_signal_opts": { "$ref": "#/components/schemas/addressing_bgp_signal_opts" }, "cidr": { "$ref": "#/components/schemas/addressing_cidr" }, "created_at": { "$ref": "#/components/schemas/addressing_timestamp" }, "id": { "$ref": "#/components/schemas/addressing_bgp_prefix_identifier" }, "modified_at": { "$ref": "#/components/schemas/addressing_timestamp" }, "on_demand": { "$ref": "#/components/schemas/addressing_bgp_on_demand" } } }, "addressing_ipam-delegations": { "type": "object", "properties": { "cidr": { "$ref": "#/components/schemas/addressing_cidr" }, "created_at": { "$ref": "#/components/schemas/addressing_timestamp" }, "delegated_account_id": { "$ref": "#/components/schemas/addressing_delegated_account_identifier" }, "id": { "$ref": "#/components/schemas/addressing_delegation_identifier" }, "modified_at": { "$ref": "#/components/schemas/addressing_timestamp" }, "parent_prefix_id": { "$ref": "#/components/schemas/addressing_prefix_identifier" } } }, "addressing_ipam-prefixes": { "type": "object", "properties": { "account_id": { "$ref": "#/components/schemas/addressing_account_identifier" }, "advertised": { "$ref": "#/components/schemas/addressing_advertised" }, "advertised_modified_at": { "$ref": "#/components/schemas/addressing_advertised_modified_at_nullable" }, "approved": { "$ref": "#/components/schemas/addressing_approved" }, "asn": { "$ref": "#/components/schemas/addressing_asn" }, "cidr": { "$ref": "#/components/schemas/addressing_cidr" }, "created_at": { "$ref": "#/components/schemas/addressing_timestamp" }, "delegate_loa_creation": { "$ref": "#/components/schemas/addressing_delegate_loa_creation" }, "description": { "$ref": "#/components/schemas/addressing_description" }, "id": { "$ref": "#/components/schemas/addressing_prefix_identifier" }, "irr_validation_state": { "$ref": "#/components/schemas/addressing_validation_state" }, "loa_document_id": { "$ref": "#/components/schemas/addressing_loa_document_identifier" }, "modified_at": { "$ref": "#/components/schemas/addressing_timestamp" }, "on_demand_enabled": { "$ref": "#/components/schemas/addressing_on_demand_enabled" }, "on_demand_locked": { "$ref": "#/components/schemas/addressing_on_demand_locked" }, "ownership_validation_state": { "$ref": "#/components/schemas/addressing_validation_state" }, "ownership_validation_token": { "$ref": "#/components/schemas/addressing_ownership_validation_token" }, "rpki_validation_state": { "$ref": "#/components/schemas/addressing_validation_state" } } }, "addressing_ips": { "description": "The set of IPs on the Address Map.", "type": "array", "items": { "$ref": "#/components/schemas/addressing_address-maps-ip" } }, "addressing_kind": { "description": "The type of the membership.", "type": "string", "example": "zone", "enum": [ "zone", "account" ], "x-auditable": true }, "addressing_lease": { "type": "object", "properties": { "active_from": { "description": "Timestamp of the moment the lease was created.\n", "type": "string", "format": "date-time", "example": "2020-01-01T00:00:00Z" }, "cidrs": { "description": "CIDRs attached to the lease", "type": "array", "items": { "$ref": "#/components/schemas/addressing_cidr-2" }, "example": [ "192.0.2.100/32", "192.0.2.101/32" ] }, "created_at": { "$ref": "#/components/schemas/addressing_created_at" }, "id": { "$ref": "#/components/schemas/addressing_lease_id" }, "modified_at": { "$ref": "#/components/schemas/addressing_modified_at" }, "owner_id": { "$ref": "#/components/schemas/addressing_lease_owner_id" }, "purpose": { "description": "Describes the purpose of the addresses.", "type": "string", "example": "Spectrum Static IPs" } } }, "addressing_lease_id": { "description": "Identifier for the lease", "type": "string", "example": "8fee4b6fd361283a72381ccfda355471" }, "addressing_lease_owner_id": { "description": "Cloudflare account ID of the account owning the lease.", "type": "string", "example": "3a7d3de1d0682240cf046c7f50866cc5" }, "addressing_loa_document_identifier": { "description": "Identifier for the uploaded LOA document.", "type": "string", "example": "d933b1530bc56c9953cf8ce166da8004", "maxLength": 32, "nullable": true, "x-auditable": true }, "addressing_loa_upload_response": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "account_id": { "$ref": "#/components/schemas/addressing_account_identifier" }, "auto_generated": { "$ref": "#/components/schemas/addressing_auto_generated" }, "created": { "$ref": "#/components/schemas/addressing_timestamp" }, "filename": { "$ref": "#/components/schemas/addressing_filename" }, "id": { "$ref": "#/components/schemas/addressing_loa_document_identifier" }, "size_bytes": { "$ref": "#/components/schemas/addressing_size_bytes" }, "verified": { "$ref": "#/components/schemas/addressing_verified" }, "verified_at": { "$ref": "#/components/schemas/addressing_verified_at" } } } }, "type": "object" } ] }, "addressing_membership_requests": { "description": "Zones and Accounts which will be assigned IPs on this Address Map. A zone membership will take priority over an account membership.", "type": "array", "items": { "$ref": "#/components/schemas/addressing_address-maps-membership-request" }, "example": [ { "identifier": "023e105f4ecef8ad9ca31a8372d0c353", "kind": "zone" } ] }, "addressing_memberships": { "description": "Zones and Accounts which will be assigned IPs on this Address Map. A zone membership will take priority over an account membership.", "type": "array", "items": { "$ref": "#/components/schemas/addressing_address-maps-membership" } }, "addressing_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "addressing_modified_at": { "description": "Timestamp of the moment the object was modified.", "type": "string", "format": "date-time" }, "addressing_modified_at_nullable": { "description": "Last time the advertisement status was changed. This field is only not 'null' if on demand is enabled.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "nullable": true, "x-auditable": true }, "addressing_on_demand_enabled": { "description": "Whether advertisement of the prefix to the Internet may be dynamically enabled or disabled.", "type": "boolean", "example": true, "deprecated": true, "x-auditable": true, "x-stainless-deprecation-message": "Prefer the [BGP Prefixes API](https://developers.cloudflare.com/api/resources/addressing/subresources/prefixes/subresources/bgp_prefixes/) instead, which allows for advertising multiple BGP routes within a single IP Prefix." }, "addressing_on_demand_enabled-2": { "description": "Whether advertisement of the prefix to the Internet may be dynamically enabled or disabled.", "type": "boolean", "example": true, "x-auditable": true }, "addressing_on_demand_locked": { "description": "Whether advertisement status of the prefix is locked, meaning it cannot be changed.", "type": "boolean", "example": false, "deprecated": true, "x-auditable": true, "x-stainless-deprecation-message": "Prefer the [BGP Prefixes API](https://developers.cloudflare.com/api/resources/addressing/subresources/prefixes/subresources/bgp_prefixes/) instead, which allows for advertising multiple BGP routes within a single IP Prefix." }, "addressing_on_demand_locked-2": { "description": "Whether the advertisement status of the prefix is locked, meaning it cannot be changed.", "type": "boolean", "example": false, "x-auditable": true }, "addressing_ownership_validation_token": { "description": "Token provided to demonstrate ownership of the prefix.", "type": "string", "example": "1234a5b6-1234-1abc-12a3-1234a5b6789c", "x-auditable": true }, "addressing_prefix_identifier": { "description": "Identifier of an IP Prefix.", "type": "string", "example": "2af39739cc4e3b5910c918468bb89828", "maxLength": 32, "x-auditable": true }, "addressing_provisioning": { "description": "Status of a Service Binding's deployment to the Cloudflare network", "type": "object", "properties": { "state": { "description": "When a binding has been deployed to a majority of Cloudflare datacenters, the binding will become active and can be used with its associated service.\n", "type": "string", "example": "provisioning", "enum": [ "provisioning", "active", "magic_transit_route_missing" ], "x-auditable": true } } }, "addressing_response_collection": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-single" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/addressing_ipam-prefixes" } } }, "type": "object" } ] }, "addressing_response_collection-2": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/addressing_ipam-delegations" } } }, "type": "object" } ] }, "addressing_response_collection-3": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/addressing_address-maps" } } }, "type": "object" } ] }, "addressing_response_collection-4": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/addressing_lease" } } }, "type": "object" } ] }, "addressing_response_collection_bgp": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-single" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/addressing_ipam-bgp-prefixes" } } }, "type": "object" } ] }, "addressing_service_binding": { "type": "object", "properties": { "cidr": { "$ref": "#/components/schemas/addressing_cidr" }, "id": { "$ref": "#/components/schemas/addressing_service_binding_identifier" }, "provisioning": { "$ref": "#/components/schemas/addressing_provisioning" }, "service_id": { "$ref": "#/components/schemas/addressing_service_identifier" }, "service_name": { "$ref": "#/components/schemas/addressing_service_name" } } }, "addressing_service_binding_identifier": { "description": "Identifier of a Service Binding.", "type": "string", "example": "0429b49b6a5155297b78e75a44b09e14", "maxLength": 32, "x-auditable": true }, "addressing_service_identifier": { "description": "Identifier of a Service on the Cloudflare network. Available services and their IDs may be found in the\n**List Services** endpoint.\n", "type": "string", "example": "2db684ee7ca04e159946fd05b99e1bcd", "maxLength": 32, "x-auditable": true }, "addressing_service_name": { "description": "Name of a service running on the Cloudflare network", "type": "string", "example": "Magic Transit", "x-auditable": true }, "addressing_single_response": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/addressing_ipam-prefixes" } }, "type": "object" } ] }, "addressing_single_response-2": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/addressing_ipam-delegations" } }, "type": "object" } ] }, "addressing_single_response-3": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/addressing_address-maps" } }, "type": "object" } ] }, "addressing_single_response_bgp": { "allOf": [ { "$ref": "#/components/schemas/addressing_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/addressing_ipam-bgp-prefixes" } }, "type": "object" } ] }, "addressing_size_bytes": { "description": "File size of the uploaded LOA document.", "type": "integer", "example": 444, "x-auditable": true }, "addressing_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "x-auditable": true }, "addressing_validation_state": { "description": "State of one kind of validation for an IP prefix.", "type": "string", "example": "pending", "x-auditable": true }, "addressing_verified": { "description": "Whether the LOA has been verified by Cloudflare staff.", "type": "boolean", "example": true, "x-auditable": true }, "addressing_verified_at": { "description": "Timestamp of the moment the LOA was marked as validated.", "type": "string", "format": "date-time", "nullable": true, "x-auditable": true }, "addressing_zone_identifier": { "description": "Identifier of a zone.", "type": "string", "example": "8ac8489932db6327334c9b6d58544cfe", "maxLength": 32, "x-auditable": true }, "ai-audit_api-response-common": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ai-audit_api_message" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ai-audit_api_message" } }, "success": { "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages" ] }, "ai-audit_api-response-common-failure": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ai-audit_api_message" }, "example": [ { "code": 7003, "message": "No route for the URI" } ], "minItems": 1 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ai-audit_api_message" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages" ] }, "ai-audit_api_message": { "type": "object", "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "ai-audit_bulk_robots_rules": { "description": "Map of hostname to parsed robots.txt rules.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ai-audit_robots_rules" }, "maxProperties": 25 }, "ai-audit_content_signal": { "description": "Content signal directives from robots.txt.", "type": "object", "properties": { "ai-input": { "description": "Whether AI input usage is permitted.", "type": "string", "enum": [ "yes", "no" ] }, "ai-train": { "description": "Whether AI training is permitted.", "type": "string", "enum": [ "yes", "no" ] }, "search": { "description": "Whether search indexing is permitted.", "type": "string", "enum": [ "yes", "no" ] } } }, "ai-audit_robots_rules": { "description": "Parsed robots.txt rules for a single domain.", "type": "object", "properties": { "sitemaps": { "description": "List of sitemap URLs found in robots.txt.", "type": "array", "items": { "type": "string" } }, "status": { "description": "HTTP status code from fetching the robots.txt file.", "type": "integer" }, "userAgents": { "description": "Map of user-agent string to its parsed rules.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ai-audit_user_agent_rules" } } }, "required": [ "userAgents" ] }, "ai-audit_user_agent_rules": { "description": "Parsed rules for a specific user-agent.", "type": "object", "properties": { "allow": { "description": "List of allowed path patterns.", "type": "array", "items": { "type": "string" } }, "contentSignals": { "$ref": "#/components/schemas/ai-audit_content_signal" }, "crawlDelay": { "description": "Crawl delay in seconds.", "type": "number" }, "disallow": { "description": "List of disallowed path patterns.", "type": "array", "items": { "type": "string" } } }, "required": [ "allow", "disallow" ] }, "aig-billing_CreateTopupResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/aig-billing_CreateTopupResult" }, "result_info": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "has_more", "page", "per_page", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "errors", "messages" ] }, "aig-billing_CreateTopupResult": { "type": "object", "properties": { "brand": { "description": "Card brand (visa, mastercard, etc.).", "type": "string" }, "client_secret": { "description": "Stripe PaymentIntent client secret.", "type": "string", "nullable": true }, "last4": { "description": "Last 4 digits of card.", "type": "string" }, "onboarding": { "description": "Whether the user was already onboarded.", "type": "boolean" }, "payment_intent_id": { "description": "Stripe invoice ID.", "type": "string" } }, "required": [ "onboarding", "payment_intent_id", "client_secret" ] }, "aig-billing_DeleteSpendingLimitResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/aig-billing_DeleteSpendingLimitResult" }, "result_info": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "has_more", "page", "per_page", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "errors", "messages" ] }, "aig-billing_DeleteSpendingLimitResult": { "type": "object" }, "aig-billing_DeleteTopupConfigResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/aig-billing_DeleteTopupConfigResult" }, "result_info": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "has_more", "page", "per_page", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "errors", "messages" ] }, "aig-billing_DeleteTopupConfigResult": { "type": "object" }, "aig-billing_ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors" ] }, "aig-billing_GetCreditBalanceResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/aig-billing_GetCreditBalanceResult" }, "result_info": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "has_more", "page", "per_page", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "errors", "messages" ] }, "aig-billing_GetCreditBalanceResult": { "type": "object", "properties": { "balance": { "type": "number" }, "first_topup_success": { "type": "boolean" }, "has_default_payment_method": { "type": "boolean" }, "payment_method": { "type": "object", "nullable": true, "properties": { "brand": { "type": "string" }, "last4": { "type": "string" } } }, "topup_config": { "type": "object", "properties": { "amount": { "type": "number", "nullable": true }, "disabledReason": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true }, "lastFailedAt": { "type": "number", "nullable": true }, "threshold": { "type": "number", "nullable": true } }, "required": [ "threshold", "amount" ] } }, "required": [ "balance", "has_default_payment_method", "payment_method", "topup_config" ] }, "aig-billing_GetInvoiceHistoryResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/aig-billing_GetInvoiceHistoryResult" }, "result_info": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "has_more", "page", "per_page", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "errors", "messages" ] }, "aig-billing_GetInvoiceHistoryResult": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "properties": { "amount_due": { "type": "number" }, "amount_paid": { "type": "number" }, "amount_remaining": { "type": "number" }, "attempt_count": { "type": "number" }, "attempted": { "type": "boolean" }, "auto_advance": { "type": "boolean", "nullable": true }, "created": { "type": "number" }, "created_by": { "type": "string" }, "currency": { "type": "string" }, "description": { "type": "string", "nullable": true }, "id": { "type": "string", "nullable": true }, "invoice_origin": { "type": "string" }, "invoice_pdf": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true } }, "required": [ "amount_paid", "amount_due", "amount_remaining", "currency" ], "type": "object" } }, "pagination": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "has_more", "page", "per_page", "total_count" ] } }, "required": [ "invoices", "pagination" ] }, "aig-billing_GetInvoicePreviewResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/aig-billing_GetInvoicePreviewResult" }, "result_info": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "has_more", "page", "per_page", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "errors", "messages" ] }, "aig-billing_GetInvoicePreviewResult": { "type": "object", "properties": { "amount_due": { "type": "number" }, "amount_paid": { "type": "number" }, "amount_remaining": { "type": "number" }, "currency": { "type": "string" }, "id": { "type": "string" }, "invoice_lines": { "type": "array", "items": { "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "description": { "type": "string", "nullable": true }, "period": { "type": "object", "properties": { "end": { "type": "number" }, "start": { "type": "number" } }, "required": [ "start", "end" ] }, "pretax_credit_amounts": { "type": "array", "items": { "properties": { "amount": { "type": "number" }, "credit_balance_transaction": { "type": "string", "nullable": true }, "discount": { "type": "string", "nullable": true }, "type": { "type": "string" } }, "required": [ "amount", "type" ], "type": "object" } }, "pricing": { "type": "object", "properties": { "unit_amount_decimal": { "type": "string", "nullable": true } }, "required": [ "unit_amount_decimal" ] }, "quantity": { "type": "number" } }, "required": [ "description", "amount", "period", "currency", "pricing", "quantity" ], "type": "object" } }, "period_end": { "type": "number" }, "period_start": { "type": "number" }, "status": { "type": "string", "enum": [ "draft", "open", "paid", "uncollectible", "void" ] } }, "required": [ "id", "amount_due", "amount_paid", "amount_remaining", "currency", "period_start", "period_end", "status", "invoice_lines" ] }, "aig-billing_GetSpendingLimitResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/aig-billing_GetSpendingLimitResult" }, "result_info": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "has_more", "page", "per_page", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "errors", "messages" ] }, "aig-billing_GetSpendingLimitResult": { "type": "object", "properties": { "config": { "type": "object", "properties": { "amount": { "type": "number", "nullable": true }, "duration": { "type": "string", "nullable": true }, "strategy": { "type": "string", "nullable": true } }, "required": [ "amount", "duration", "strategy" ] }, "enabled": { "type": "boolean" } }, "required": [ "enabled", "config" ] }, "aig-billing_GetTopupConfigResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/aig-billing_GetTopupConfigResult" }, "result_info": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "has_more", "page", "per_page", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "errors", "messages" ] }, "aig-billing_GetTopupConfigResult": { "type": "object", "properties": { "amount": { "type": "number", "nullable": true }, "disabledReason": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true }, "lastFailedAt": { "type": "number", "nullable": true }, "threshold": { "type": "number", "nullable": true } }, "required": [ "threshold", "amount" ] }, "aig-billing_GetTopupEligibilityResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/aig-billing_GetTopupEligibilityResult" }, "result_info": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "has_more", "page", "per_page", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "errors", "messages" ] }, "aig-billing_GetTopupEligibilityResult": { "type": "object", "properties": { "account_payment_method_state": { "description": "Account-level PM posture derived from the passed-in list.", "type": "string", "example": "SUPPORTED_PRESENT", "enum": [ "NONE", "UNSUPPORTED_ONLY", "SUPPORTED_PRESENT", "UNKNOWN" ] }, "aig_customer_state": { "description": "AIG Stripe customer resolution outcome.", "type": "string", "example": "RESOLVED", "enum": [ "RESOLVED", "RESOLUTION_FAILED" ] }, "aig_default_payment_method_state": { "description": "Whether the AIG Stripe customer has a default PM attached.", "type": "string", "example": "MISSING", "enum": [ "PRESENT", "MISSING" ] }, "display_payment_method": { "description": "Card to reference in the UI, e.g. \"use card ending 1234\".", "type": "object", "nullable": true, "properties": { "brand": { "type": "string", "example": "visa" }, "last4": { "type": "string", "example": "1234" } }, "required": [ "last4" ] }, "eligible": { "description": "True only when reason === ELIGIBLE.", "type": "boolean", "example": false }, "reason": { "description": "Canonical (in)eligibility cause. Drives Stratus copy + support triage.", "type": "string", "example": "ACCOUNT_PAYMENT_METHOD_NOT_LINKED_TO_AIG", "enum": [ "ELIGIBLE", "NO_ACCOUNT_PAYMENT_METHOD", "UNSUPPORTED_ACCOUNT_PAYMENT_METHOD", "ACCOUNT_PAYMENT_METHOD_NOT_DEFAULT", "ACCOUNT_PAYMENT_METHOD_NOT_LINKED_TO_AIG", "CONTRACT_BILLING_NOT_SELF_SERVE", "AIG_CUSTOMER_RESOLUTION_FAILED", "PENDING_3DS_AUTHENTICATION", "PAYMENT_AUTHENTICATION_FAILED" ] }, "recommended_action": { "description": "Machine-readable next step.", "type": "string", "example": "USE_EXISTING_CARD", "enum": [ "NONE", "ADD_SUPPORTED_PAYMENT_METHOD", "USE_EXISTING_CARD", "SET_CARD_AS_DEFAULT", "CONTACT_SUPPORT", "RESUME_AUTHENTICATION", "RETRY" ] }, "recoverable": { "description": "Whether the customer can resolve this themselves (vs contact support).", "type": "boolean", "example": true } }, "required": [ "eligible", "reason", "recoverable", "recommended_action", "account_payment_method_state", "aig_customer_state", "aig_default_payment_method_state", "display_payment_method" ] }, "aig-billing_GetTopupLimitsResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/aig-billing_GetTopupLimitsResult" }, "result_info": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "has_more", "page", "per_page", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "errors", "messages" ] }, "aig-billing_GetTopupLimitsResult": { "type": "object", "properties": { "currency": { "description": "ISO 4217 currency code.", "type": "string", "example": "USD" }, "max_cents": { "type": "integer" }, "min_cents": { "description": "Minimum allowed top-up amount in cents.", "type": "integer", "example": 1000 } }, "required": [ "min_cents", "max_cents", "currency" ] }, "aig-billing_GetUsageHistoryResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/aig-billing_GetUsageHistoryResult" }, "result_info": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "has_more", "page", "per_page", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "errors", "messages" ] }, "aig-billing_GetUsageHistoryResult": { "type": "object", "properties": { "history": { "type": "array", "items": { "properties": { "aggregated_value": { "type": "number" }, "end_time": { "type": "number" }, "id": { "type": "string" }, "start_time": { "type": "number" } }, "required": [ "id", "aggregated_value", "end_time", "start_time" ], "type": "object" } } }, "required": [ "history" ] }, "aig-billing_SetSpendingLimitResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/aig-billing_SetSpendingLimitResult" }, "result_info": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "has_more", "page", "per_page", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "errors", "messages" ] }, "aig-billing_SetSpendingLimitResult": { "type": "object" }, "aig-billing_SetTopupConfigResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/aig-billing_SetTopupConfigResult" }, "result_info": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "has_more", "page", "per_page", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "errors", "messages" ] }, "aig-billing_SetTopupConfigResult": { "type": "object", "properties": { "amount": { "type": "number" }, "threshold": { "type": "number" } }, "required": [ "threshold", "amount" ] }, "aig-billing_TopupStatusResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/aig-billing_TopupStatusResult" }, "result_info": { "type": "object", "properties": { "has_more": { "type": "boolean" }, "page": { "type": "number" }, "per_page": { "type": "number" }, "total_count": { "type": "number" } }, "required": [ "has_more", "page", "per_page", "total_count" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result", "errors", "messages" ] }, "aig-billing_TopupStatusResult": { "type": "object", "properties": { "payment_intent_id": { "type": "string" }, "status": { "type": "string", "enum": [ "completed", "pending" ] } }, "required": [ "status", "payment_intent_id" ] }, "alexandria_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/alexandria_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Returns the total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Returns the current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Returns the number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Returns the total results available without any search parameters.", "type": "number", "example": 2000 } } } }, "type": "object" } ] }, "alexandria_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/alexandria_messages" }, "messages": { "$ref": "#/components/schemas/alexandria_messages" }, "success": { "description": "Indicates whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "alexandria_api_response_common_failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/alexandria_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/alexandria_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Indicates whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "alexandria_application": { "type": "object", "properties": { "application_confidence_score": { "$ref": "#/components/schemas/alexandria_application_confidence_score" }, "application_score_composition": { "$ref": "#/components/schemas/alexandria_application_score_composition" }, "application_source": { "$ref": "#/components/schemas/alexandria_application_source" }, "application_type": { "$ref": "#/components/schemas/alexandria_application_type" }, "application_type_description": { "$ref": "#/components/schemas/alexandria_application_type_description" }, "category_id": { "$ref": "#/components/schemas/alexandria_category_id" }, "created_at": { "$ref": "#/components/schemas/alexandria_application_created_at" }, "gen_ai_score": { "$ref": "#/components/schemas/alexandria_application_gen_ai_score" }, "hostnames": { "$ref": "#/components/schemas/alexandria_application_hostnames" }, "human_id": { "$ref": "#/components/schemas/alexandria_application_human_id" }, "id": { "$ref": "#/components/schemas/alexandria_application_id" }, "ip_subnets": { "$ref": "#/components/schemas/alexandria_application_ip_subnets" }, "name": { "$ref": "#/components/schemas/alexandria_application_name" }, "port_protocols": { "$ref": "#/components/schemas/alexandria_application_port_protocols" }, "support_domains": { "$ref": "#/components/schemas/alexandria_application_support_domains" }, "supported": { "$ref": "#/components/schemas/alexandria_application_supported" }, "updated_at": { "$ref": "#/components/schemas/alexandria_application_updated_at" }, "version": { "$ref": "#/components/schemas/alexandria_application_version" } }, "required": [ "application_source", "application_type", "category_id", "application_type_description", "gen_ai_score", "application_confidence_score", "created_at", "supported", "hostnames", "human_id", "id", "ip_subnets", "name", "port_protocols", "support_domains", "updated_at", "version" ] }, "alexandria_application_confidence_score": { "description": "Confidence score for the application. Returns -1 when no score is available.", "type": "number", "format": "float", "example": 0.92 }, "alexandria_application_created_at": { "description": "Returns the application creation time.", "type": "string", "example": "2025-01-01T00:00:00Z" }, "alexandria_application_gen_ai_score": { "description": "GenAI score for the application. Returns -1 when no score is available.", "type": "number", "format": "float", "example": 1.5 }, "alexandria_application_hostnames": { "description": "Hostnames matched by the application.", "type": "array", "items": { "type": "string" }, "example": [ "example.com", "foo.com" ], "x-stainless-collection-type": "set" }, "alexandria_application_human_id": { "description": "Returns the human readable ID.", "type": "string", "example": "HR" }, "alexandria_application_id": { "description": "Returns the application ID.", "type": "integer", "format": "int64", "example": 498, "maximum": 4294967295, "minimum": 0 }, "alexandria_application_ip_subnets": { "description": "IP subnets matched by the application.", "type": "array", "items": { "type": "string" }, "example": [ "192.168.1.0/24", "10.0.0.0/8" ], "x-stainless-collection-type": "set" }, "alexandria_application_list_item": { "description": "Describes one application in a list response. This endpoint returns every property below unless the `fields` query parameter narrows the response, so treat all of them except `id` as optional.", "type": "object", "properties": { "application_confidence_score": { "$ref": "#/components/schemas/alexandria_application_confidence_score" }, "application_score_composition": { "$ref": "#/components/schemas/alexandria_application_score_composition" }, "application_source": { "$ref": "#/components/schemas/alexandria_application_source" }, "application_type": { "$ref": "#/components/schemas/alexandria_application_type" }, "application_type_description": { "$ref": "#/components/schemas/alexandria_application_type_description" }, "category_id": { "$ref": "#/components/schemas/alexandria_category_id" }, "created_at": { "$ref": "#/components/schemas/alexandria_application_created_at" }, "gen_ai_score": { "$ref": "#/components/schemas/alexandria_application_gen_ai_score" }, "hostnames": { "$ref": "#/components/schemas/alexandria_application_hostnames" }, "human_id": { "$ref": "#/components/schemas/alexandria_application_human_id" }, "id": { "$ref": "#/components/schemas/alexandria_application_id" }, "ip_subnets": { "$ref": "#/components/schemas/alexandria_application_ip_subnets" }, "name": { "$ref": "#/components/schemas/alexandria_application_name" }, "port_protocols": { "$ref": "#/components/schemas/alexandria_application_port_protocols" }, "review_status": { "description": "The account-specific Gateway review status. Applications with no assigned review status are returned as `unreviewed`.", "type": "string", "enum": [ "approved", "unapproved", "in_review", "unreviewed" ] }, "support_domains": { "$ref": "#/components/schemas/alexandria_application_support_domains" }, "supported": { "$ref": "#/components/schemas/alexandria_application_supported" }, "updated_at": { "$ref": "#/components/schemas/alexandria_application_updated_at" }, "version": { "$ref": "#/components/schemas/alexandria_application_version" } }, "required": [ "id" ] }, "alexandria_application_name": { "description": "Returns the application name.", "type": "string", "example": "HR" }, "alexandria_application_port_protocols": { "description": "Port and protocol pairs matched by the application.", "type": "array", "items": { "type": "string" }, "example": [ "tcp/80", "tcp/443" ], "x-stainless-collection-type": "set" }, "alexandria_application_reference": { "type": "object", "properties": { "id": { "description": "The public identifier of the referencing resource.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" }, "name": { "description": "The name of the referencing resource.", "type": "string", "example": "Allow Spotify" }, "type": { "description": "The resource type, such as Rule or Profile. Additional types may be returned.", "type": "string", "example": "Rule" } }, "required": [ "id", "name", "type" ] }, "alexandria_application_score_composition": { "description": "Returns the score composition breakdown for the application.", "type": "object", "example": { "categories": [ { "confidence": 0.95, "name": "Security" } ], "plan": "free" }, "nullable": true }, "alexandria_application_source": { "description": "Returns the application source.", "type": "string", "example": "cloudflare" }, "alexandria_application_support_domains": { "description": "Support domains matched by the application.", "type": "array", "items": { "type": "string" }, "example": [ "example.com", "foo.com" ], "x-stainless-collection-type": "set" }, "alexandria_application_supported": { "description": "Cloudflare products that support this application.", "type": "array", "items": { "enum": [ "GATEWAY", "ACCESS", "CASB" ], "type": "string" }, "example": [ "GATEWAY", "ACCESS" ], "x-stainless-collection-type": "set" }, "alexandria_application_type": { "description": "Returns the application type.", "type": "string", "example": "Human Resources" }, "alexandria_application_type_description": { "description": "Returns the application type description.", "type": "string", "example": "Applications used to manage employees and workforce tools." }, "alexandria_application_updated_at": { "description": "Returns the application update time.", "type": "string", "example": "2025-01-01T00:00:00Z" }, "alexandria_application_version": { "description": "Returns the application version.", "type": "string", "example": "2025-01-01T00:00:00Z" }, "alexandria_applications": { "description": "Returns the list of applications.", "type": "array", "items": { "$ref": "#/components/schemas/alexandria_application_list_item" } }, "alexandria_categories": { "description": "Returns the list of categories.", "type": "array", "items": { "$ref": "#/components/schemas/alexandria_category" } }, "alexandria_category": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/alexandria_category_created_at" }, "description": { "$ref": "#/components/schemas/alexandria_category_description" }, "id": { "$ref": "#/components/schemas/alexandria_category_id" }, "name": { "$ref": "#/components/schemas/alexandria_category_name" } }, "required": [ "created_at", "description", "id", "name" ] }, "alexandria_category_created_at": { "description": "Returns the category creation time.", "type": "string", "example": "2025-01-01T00:00:00Z" }, "alexandria_category_description": { "description": "Returns the category description.", "type": "string", "example": "Category description" }, "alexandria_category_id": { "description": "Returns the category ID.", "type": "integer", "format": "int64", "example": 12, "maximum": 4294967295, "minimum": 1 }, "alexandria_category_name": { "description": "Returns the category name.", "type": "string", "example": "Category name" }, "alexandria_create_application_request": { "type": "object", "properties": { "category_id": { "$ref": "#/components/schemas/alexandria_category_id" }, "hostnames": { "$ref": "#/components/schemas/alexandria_application_hostnames" }, "human_id": { "$ref": "#/components/schemas/alexandria_application_human_id" }, "ip_subnets": { "$ref": "#/components/schemas/alexandria_application_ip_subnets" }, "name": { "$ref": "#/components/schemas/alexandria_application_name" }, "port_protocols": { "$ref": "#/components/schemas/alexandria_application_port_protocols" }, "support_domains": { "$ref": "#/components/schemas/alexandria_application_support_domains" } }, "required": [ "name", "human_id", "category_id" ] }, "alexandria_delete_application_conflict_response": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string", "example": "Application is referenced by other resources" }, "meta": { "type": "object", "properties": { "references": { "description": "The complete list of resources in the account that reference the application.", "type": "array", "items": { "$ref": "#/components/schemas/alexandria_application_reference" }, "minItems": 1 } }, "required": [ "references" ] } }, "required": [ "code", "message", "meta" ], "type": "object" }, "maxItems": 1, "minItems": 1 }, "messages": { "$ref": "#/components/schemas/alexandria_messages" }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "alexandria_delete_application_response": { "allOf": [ { "$ref": "#/components/schemas/alexandria_api-response-common" }, { "properties": { "result": { "type": "object", "enum": [ null ], "nullable": true } }, "required": [ "result" ], "type": "object" } ] }, "alexandria_get_application_response": { "allOf": [ { "$ref": "#/components/schemas/alexandria_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/alexandria_application" } }, "type": "object" } ] }, "alexandria_get_applications_response": { "allOf": [ { "$ref": "#/components/schemas/alexandria_api-response-collection" }, { "properties": { "result": { "$ref": "#/components/schemas/alexandria_applications" } }, "type": "object" } ] }, "alexandria_get_categories_response": { "allOf": [ { "$ref": "#/components/schemas/alexandria_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/alexandria_categories" } }, "type": "object" } ] }, "alexandria_get_category_response": { "allOf": [ { "$ref": "#/components/schemas/alexandria_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/alexandria_category" } }, "type": "object" } ] }, "alexandria_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "alexandria_update_application_request": { "description": "Updates the network matchers for the application. Omitted matcher lists are left unchanged; send an empty array to clear a list.", "type": "object", "properties": { "hostnames": { "$ref": "#/components/schemas/alexandria_application_hostnames" }, "ip_subnets": { "$ref": "#/components/schemas/alexandria_application_ip_subnets" }, "port_protocols": { "$ref": "#/components/schemas/alexandria_application_port_protocols" }, "support_domains": { "$ref": "#/components/schemas/alexandria_application_support_domains" } } }, "analytics-engine_JsonFormatResponse": { "description": "Response structure when FORMAT JSON is specified in the query. Contains the query result rows, column metadata, and a row count.\n", "type": "object", "properties": { "data": { "description": "Array of result rows. Each row is an object with keys corresponding to the selected columns.\n", "type": "array", "items": { "additionalProperties": true, "type": "object" } }, "meta": { "description": "Column metadata describing the name and type of each column in the result set.\n", "type": "array", "items": { "properties": { "name": { "description": "Column name.", "type": "string" }, "type": { "description": "Column data type.", "type": "string" } }, "required": [ "name", "type" ], "type": "object" } }, "rows": { "description": "Total number of rows in the result set.", "type": "integer" } }, "required": [ "data", "meta", "rows" ] }, "api-shield_Rule": { "description": "A Token Validation rule that can enforce security policies using JWT Tokens.", "type": "object", "properties": { "action": { "$ref": "#/components/schemas/api-shield_action" }, "created_at": { "$ref": "#/components/schemas/api-shield_timestamp-2" }, "description": { "$ref": "#/components/schemas/api-shield_description-2" }, "enabled": { "$ref": "#/components/schemas/api-shield_enabled" }, "expression": { "$ref": "#/components/schemas/api-shield_expression" }, "id": { "$ref": "#/components/schemas/api-shield_uuid-2" }, "last_updated": { "$ref": "#/components/schemas/api-shield_timestamp-2" }, "selector": { "$ref": "#/components/schemas/api-shield_selector" }, "title": { "$ref": "#/components/schemas/api-shield_title-2" } }, "required": [ "title", "description", "action", "enabled", "expression", "selector" ] }, "api-shield_TokenConfiguration": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/api-shield_timestamp-2" }, "credentials": { "$ref": "#/components/schemas/api-shield_credentials" }, "description": { "$ref": "#/components/schemas/api-shield_description" }, "id": { "$ref": "#/components/schemas/api-shield_uuid-2" }, "last_updated": { "$ref": "#/components/schemas/api-shield_timestamp-2" }, "title": { "$ref": "#/components/schemas/api-shield_title" }, "token_sources": { "$ref": "#/components/schemas/api-shield_token_sources" }, "token_type": { "$ref": "#/components/schemas/api-shield_token_type" } }, "required": [ "id", "title", "description", "token_sources", "token_type", "credentials", "created_at", "last_updated" ] }, "api-shield_action": { "description": "Action to take on requests that match operations included in `selector` and fail `expression`.", "type": "string", "example": "log", "enum": [ "log", "block" ], "x-auditable": true }, "api-shield_after": { "description": "Move rule to before rule with ID.", "type": "object", "properties": { "after": { "description": "Move rule to after rule with this ID.", "type": "string", "format": "uuid", "example": "0d9bf70c-92e1-4bb3-9411-34a3bcc59003", "maxLength": 36, "x-auditable": true } } }, "api-shield_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "api-shield_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/api-shield_messages" }, "messages": { "$ref": "#/components/schemas/api-shield_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "api-shield_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/api-shield_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/api-shield_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "api-shield_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" } ] }, "api-shield_api-response-single-obj": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "type": "object" } }, "type": "object" } ] }, "api-shield_api_discovery_origin": { "description": "* `ML` - Discovered operation was sourced using ML API Discovery * `SessionIdentifier` - Discovered operation was sourced using Session Identifier API Discovery * `LabelDiscovery` - Discovered operation was identified to have a specific label\n", "type": "string", "enum": [ "ML", "SessionIdentifier", "LabelDiscovery" ], "x-auditable": true }, "api-shield_api_discovery_patch_multiple_request": { "type": "object", "example": { "3818d821-5901-4147-a474-f5f5aec1d54e": { "state": "ignored" }, "b17c8043-99a0-4202-b7d9-8f7cdbee02cd": { "state": "review" } }, "additionalProperties": { "$ref": "#/components/schemas/api-shield_api_discovery_patch_multiple_request_entry" } }, "api-shield_api_discovery_patch_multiple_request_entry": { "description": "Mappings of discovered operations (keys) to objects describing their state", "type": "object", "properties": { "state": { "$ref": "#/components/schemas/api-shield_api_discovery_state_patch" } } }, "api-shield_api_discovery_state": { "description": "State of operation in API Discovery\n * `review` - Operation is not saved into API Shield Endpoint Management\n * `saved` - Operation is saved into API Shield Endpoint Management\n * `ignored` - Operation is marked as ignored\n", "type": "string", "enum": [ "review", "saved", "ignored" ], "x-auditable": true }, "api-shield_api_discovery_state_patch": { "description": "Mark state of operation in API Discovery\n * `review` - Mark operation as for review\n * `ignored` - Mark operation as ignored\n", "type": "string", "enum": [ "review", "ignored" ], "x-auditable": true }, "api-shield_auth_id_characteristic": { "description": "Auth ID Characteristic", "properties": { "name": { "description": "The name of the characteristic field, i.e., the header or cookie name.", "type": "string", "example": "authorization", "maxLength": 128, "x-auditable": true }, "type": { "description": "The type of characteristic.", "type": "string", "example": "header", "enum": [ "header", "cookie" ], "x-auditable": true } }, "required": [ "type", "name" ] }, "api-shield_auth_id_characteristic_jwt_claim": { "description": "Auth ID Characteristic extracted from JWT Token Claims", "type": "object", "properties": { "name": { "description": "Claim location expressed as `$(token_config_id):$(json_path)`, where `token_config_id` \nis the ID of the token configuration used in validating the JWT, and `json_path` is a RFC 9535 \nJSONPath (https://goessner.net/articles/JsonPath/, https://www.rfc-editor.org/rfc/rfc9535.html).\nThe JSONPath expression may be in dot or bracket notation, may only specify literal keys\nor array indexes, and must return a singleton value, which will be interpreted as a string.\n", "type": "string", "example": "e0de1a3a-8c2c-4f90-98d8-cbdf0a3f2cb5:$.foo.bar[0].baz", "maxLength": 128, "pattern": "^(?[a-z0-9\\-]{32,36}):\\$(?.*?)$", "x-auditable": true }, "type": { "description": "The type of characteristic.", "type": "string", "example": "jwt", "enum": [ "jwt" ], "x-auditable": true } }, "required": [ "type", "name" ] }, "api-shield_auth_id_characteristics": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/api-shield_auth_id_characteristic" }, { "$ref": "#/components/schemas/api-shield_auth_id_characteristic_jwt_claim" } ] }, "maxItems": 10, "uniqueItems": true }, "api-shield_auth_id_tokens": { "description": "The total number of auth-ids seen across this calculation.", "type": "integer", "readOnly": true, "x-auditable": true }, "api-shield_basic_operation": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/api-shield_endpoint" }, "host": { "$ref": "#/components/schemas/api-shield_host" }, "method": { "$ref": "#/components/schemas/api-shield_method" } }, "required": [ "method", "host", "endpoint" ] }, "api-shield_before": { "description": "Move rule to after rule with ID.", "type": "object", "properties": { "before": { "description": "Move rule to before rule with this ID.", "type": "string", "format": "uuid", "example": "0d9bf70c-92e1-4bb3-9411-34a3bcc59003", "maxLength": 36, "x-auditable": true } } }, "api-shield_bulk_delete_labels_on_operation_request": { "type": "object", "properties": { "managed": { "type": "object", "properties": { "labels": { "description": "List of managed label names.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label_name" } } } }, "selector": { "$ref": "#/components/schemas/api-shield_operation_id_selector" }, "user": { "type": "object", "properties": { "labels": { "description": "List of user label names.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label_name" } } } } }, "required": [ "selector" ] }, "api-shield_bulk_post_labels_on_operation_request": { "type": "object", "properties": { "managed": { "type": "object", "properties": { "labels": { "description": "List of managed label names.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label_name" }, "minItems": 1 } } }, "selector": { "$ref": "#/components/schemas/api-shield_operation_id_selector" }, "user": { "type": "object", "properties": { "labels": { "description": "List of user label names.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label_name" }, "minItems": 1 } } } }, "required": [ "selector" ] }, "api-shield_bulk_put_labels_on_operation_request": { "type": "object", "properties": { "managed": { "description": "Managed labels to replace for all affected operations", "type": "object", "properties": { "labels": { "description": "List of managed label names. Providing an empty array will result in all managed labels being removed from all affected operations", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label_name" } } }, "required": [ "labels" ] }, "selector": { "$ref": "#/components/schemas/api-shield_operation_id_selector" }, "user": { "description": "User labels to replace for all affected operations", "type": "object", "properties": { "labels": { "description": "List of user label names. Providing an empty array will result in all user labels being removed from all affected operations", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label_name" } } }, "required": [ "labels" ] } }, "required": [ "selector", "user", "managed" ] }, "api-shield_confidence_intervals_bounds": { "description": "Upper and lower bound for percentile estimate", "type": "object", "properties": { "lower": { "description": "Lower bound for percentile estimate", "type": "number", "example": 20.5, "x-auditable": true }, "upper": { "description": "Upper bound for percentile estimate", "type": "number", "example": 30.4, "x-auditable": true } }, "readOnly": true }, "api-shield_configuration": { "type": "object", "properties": { "auth_id_characteristics": { "$ref": "#/components/schemas/api-shield_auth_id_characteristics" } }, "required": [ "auth_id_characteristics" ] }, "api-shield_configuration-single-response": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_configuration" } }, "required": [ "result" ], "type": "object" } ] }, "api-shield_cookie": { "description": "HTTP request cookie", "type": "string", "example": "http.request.cookies[\"Authorization\"][0]", "pattern": "^http.request.cookies\\[.*?\\]\\[\\d+\\]$", "x-auditable": true }, "api-shield_create-single-rule-request": { "allOf": [ { "description": "A Token Validation rule that can enforce security policies using JWT Tokens.", "required": [ "title", "description", "action", "enabled", "expression", "selector" ], "type": "object" }, { "$ref": "#/components/schemas/api-shield_rule-properties" } ] }, "api-shield_credentials": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-response" }, "maxItems": 64, "minItems": 1 } }, "required": [ "keys" ] }, "api-shield_credentials-JWT-Key-EC-ES256": { "description": "JSON representation of an ES256 key", "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-common" }, { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-EC-common" }, { "properties": { "alg": { "description": "Algorithm", "type": "string", "enum": [ "ES256" ], "x-auditable": true }, "crv": { "description": "Curve", "type": "string", "enum": [ "P-256" ], "x-auditable": true } }, "required": [ "alg", "crv" ], "type": "object" } ] }, "api-shield_credentials-JWT-Key-EC-ES384": { "description": "JSON representation of an ES384 key", "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-common" }, { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-EC-common" }, { "properties": { "alg": { "description": "Algorithm", "type": "string", "enum": [ "ES384" ], "x-auditable": true }, "crv": { "description": "Curve", "type": "string", "enum": [ "P-384" ], "x-auditable": true } }, "required": [ "alg", "crv" ], "type": "object" } ] }, "api-shield_credentials-JWT-Key-EC-common": { "type": "object", "properties": { "kty": { "description": "Key Type", "type": "string", "enum": [ "EC" ], "x-auditable": true }, "x": { "description": "X EC coordinate", "type": "string", "x-auditable": false }, "y": { "description": "Y EC coordinate", "type": "string", "x-auditable": false } }, "required": [ "kty", "x", "y" ] }, "api-shield_credentials-JWT-Key-RSA": { "description": "JSON representation of an RSA key.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-common" }, { "properties": { "alg": { "description": "Algorithm", "type": "string", "enum": [ "RS256", "RS384", "RS512", "PS256", "PS384", "PS512" ], "x-auditable": true }, "e": { "description": "RSA exponent", "type": "string", "x-auditable": false }, "kty": { "description": "Key Type", "type": "string", "enum": [ "RSA" ], "x-auditable": true }, "n": { "description": "RSA modulus", "type": "string", "x-auditable": false } }, "required": [ "kty", "alg", "n", "e" ], "type": "object" } ] }, "api-shield_credentials-JWT-Key-common": { "type": "object", "properties": { "kid": { "description": "Key ID", "type": "string", "x-auditable": true } }, "required": [ "kid" ] }, "api-shield_credentials-JWT-Key-oct-patch-request": { "description": "JSON representation of a symmetric key for PATCH requests.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-common" }, { "properties": { "alg": { "description": "Algorithm", "type": "string", "enum": [ "HS256", "HS384", "HS512" ], "x-auditable": true }, "k": { "description": "Symmetric key material. Optional for PATCH: omit to preserve existing secret for matching `{alg,kid}`; send a string to rotate. `k: null` is invalid.", "type": "string", "x-auditable": false }, "kty": { "description": "Key Type", "type": "string", "enum": [ "oct" ], "x-auditable": true } }, "required": [ "kty", "alg" ], "type": "object" } ] }, "api-shield_credentials-JWT-Key-oct-request": { "description": "JSON representation of a symmetric key for create/PUT requests.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-common" }, { "properties": { "alg": { "description": "Algorithm", "type": "string", "enum": [ "HS256", "HS384", "HS512" ], "x-auditable": true }, "k": { "description": "Symmetric key material. Required for create and PUT update requests.", "type": "string", "x-auditable": false }, "kty": { "description": "Key Type", "type": "string", "enum": [ "oct" ], "x-auditable": true } }, "required": [ "kty", "alg", "k" ], "type": "object" } ] }, "api-shield_credentials-JWT-Key-oct-response": { "description": "JSON representation of a symmetric verification key in API responses (secret material is redacted).", "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-common" }, { "properties": { "alg": { "description": "Algorithm", "type": "string", "enum": [ "HS256", "HS384", "HS512" ], "x-auditable": true }, "kty": { "description": "Key Type", "type": "string", "enum": [ "oct" ], "x-auditable": true } }, "required": [ "kty", "alg" ], "type": "object" } ] }, "api-shield_credentials-JWT-Key-patch-request": { "description": "JSON representation of a JWKS key for PATCH credentials requests.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-RSA" }, { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-EC-ES256" }, { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-EC-ES384" }, { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-oct-patch-request" } ] }, "api-shield_credentials-JWT-Key-request": { "description": "JSON representation of a JWKS key for create and PUT requests.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-RSA" }, { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-EC-ES256" }, { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-EC-ES384" }, { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-oct-request" } ] }, "api-shield_credentials-JWT-Key-response": { "description": "JSON representation of a JWKS key.", "type": "object", "example": { "alg": "ES256", "crv": "P-256", "kid": "38013f13-c266-4eec-a72a-92ec92779f21", "kty": "EC", "x": "KN53JRwN3wCjm2o39bvZUX2VdrsHzS8pxOAGjm8m7EQ", "y": "lnkkzIxaveggz-HFhcMWW15nxvOj0Z_uQsXbpK0GFcY" }, "oneOf": [ { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-RSA" }, { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-EC-ES256" }, { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-EC-ES384" }, { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-oct-response" } ] }, "api-shield_credentials-patch-request": { "description": "Request payload for PATCH credentials. Provided keys define the complete stored key set, and stored keys omitted from payload are removed. For each provided key identity (`{alg,kid}`), payload fields overwrite the stored key before validation and omitted fields inherit from the stored key. Key identities must be unique.", "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-patch-request" }, "maxItems": 64, "minItems": 1 } }, "required": [ "keys" ] }, "api-shield_credentials-request": { "description": "Request payload for create and PUT credentials operations. Provided keys define the complete stored key set. Key identities (`{alg,kid}`) must be unique.", "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_credentials-JWT-Key-request" }, "maxItems": 64, "minItems": 1 } }, "required": [ "keys" ] }, "api-shield_data_points": { "description": "The number of data points used for the threshold suggestion calculation.", "type": "integer", "readOnly": true, "x-auditable": true }, "api-shield_delete_labels_on_operation_request": { "type": "object", "properties": { "managed": { "description": "List of managed label names.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label_name" } }, "user": { "description": "List of user label names.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label_name" } } } }, "api-shield_description": { "type": "string", "example": "Long description for Token Validation Configuration", "maxLength": 500, "x-auditable": true }, "api-shield_description-2": { "description": "A human-readable description that gives more details than `title`.", "type": "string", "example": "Long description for Token Validation Rule", "maxLength": 500, "x-auditable": true }, "api-shield_discovery_operation": { "allOf": [ { "properties": { "features": { "$ref": "#/components/schemas/api-shield_traffic_stats" }, "id": { "$ref": "#/components/schemas/api-shield_uuid-2" }, "last_updated": { "$ref": "#/components/schemas/api-shield_timestamp-2" }, "origin": { "description": "API discovery engine(s) that discovered this operation", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_api_discovery_origin" } }, "state": { "$ref": "#/components/schemas/api-shield_api_discovery_state" } }, "required": [ "id", "last_updated", "state", "origin" ], "type": "object" }, { "$ref": "#/components/schemas/api-shield_basic_operation" } ] }, "api-shield_edit-single-rule-request": { "allOf": [ { "$ref": "#/components/schemas/api-shield_rule-properties" }, { "properties": { "position": { "$ref": "#/components/schemas/api-shield_position" } }, "type": "object" } ] }, "api-shield_enabled": { "description": "Toggle rule on or off.", "type": "boolean", "example": true, "x-auditable": true }, "api-shield_endpoint": { "description": "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/.", "type": "string", "format": "uri-template", "example": "/api/v1/users/{var1}", "maxLength": 4096, "pattern": "^/.*$", "x-auditable": true }, "api-shield_expression": { "description": "Rule expression. Requests that fail to match this expression will be subject to `action`.\n\nFor details on expressions, see the [Cloudflare Docs](https://developers.cloudflare.com/api-shield/security/jwt-validation/).\n", "type": "string", "example": "is_jwt_valid(\"52973293-cb04-4a97-8f55-e7d2ad1107dd\") or is_jwt_valid(\"46eab8d1-6376-45e3-968f-2c649d77d423\")", "x-auditable": true }, "api-shield_full_label": { "allOf": [ { "$ref": "#/components/schemas/api-shield_label" }, { "properties": { "mapped_resources": { "$ref": "#/components/schemas/api-shield_label_mapped_resources" } }, "type": "object" } ] }, "api-shield_full_managed_label": { "allOf": [ { "$ref": "#/components/schemas/api-shield_full_label" }, { "properties": { "source": { "type": "string", "example": "managed" } }, "type": "object" } ] }, "api-shield_global_setting_change_base": { "type": "object", "properties": { "validation_default_mitigation_action": { "description": "The default mitigation action used\nMitigation actions are as follows:\n\n - `\"log\"` - log request when request does not conform to schema\n - `\"block\"` - deny access to the site when request does not conform to schema\n - `\"none\"` - skip running schema validation\n", "type": "string", "example": "block", "enum": [ "none", "log", "block" ], "x-auditable": true }, "validation_override_mitigation_action": { "description": "When set, this overrides both zone level and operation level mitigation actions.\n\n - `\"none\"` - skip running schema validation entirely for the request\n - `null` - clears any existing override\n", "type": "string", "enum": [ "none", null ], "nullable": true, "x-auditable": true } } }, "api-shield_global_settings": { "type": "object", "properties": { "validation_default_mitigation_action": { "description": "The default mitigation action used\n\nMitigation actions are as follows:\n\n - `log` - log request when request does not conform to schema\n - `block` - deny access to the site when request does not conform to schema\n - `none` - skip running schema validation\n", "type": "string", "example": "block", "enum": [ "none", "log", "block" ], "x-auditable": true }, "validation_override_mitigation_action": { "description": "When not null, this overrides global both zone level and operation level mitigation actions. This can serve as a quick way to disable schema validation for the whole zone.\n\n - `\"none\"` will skip running schema validation entirely for the request\n", "type": "string", "enum": [ "none", null ], "nullable": true, "x-auditable": true } }, "required": [ "validation_default_mitigation_action" ] }, "api-shield_header": { "description": "HTTP request header (must be lowercase)", "type": "string", "example": "http.request.headers[\"x-auth\"][0]", "pattern": "^http.request.headers\\[.*?\\]\\[\\d+\\]$", "x-auditable": true }, "api-shield_host": { "description": "RFC3986-compliant host.", "type": "string", "format": "hostname", "example": "www.example.com", "maxLength": 255, "x-auditable": true }, "api-shield_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "api-shield_identifier-2": { "allOf": [ { "$ref": "#/components/schemas/api-shield_identifier" }, { "readOnly": true, "type": "string", "x-auditable": true } ] }, "api-shield_index": { "type": "object", "properties": { "index": { "description": "Move rule to this position", "type": "integer", "example": 2, "minimum": 1, "x-auditable": true } }, "required": [ "index" ] }, "api-shield_label": { "type": "object", "allOf": [ { "properties": { "created_at": { "$ref": "#/components/schemas/api-shield_timestamp-2" }, "description": { "$ref": "#/components/schemas/api-shield_label_description" }, "last_updated": { "$ref": "#/components/schemas/api-shield_timestamp-2" }, "metadata": { "$ref": "#/components/schemas/api-shield_label_metadata" }, "name": { "$ref": "#/components/schemas/api-shield_label_name" }, "source": { "$ref": "#/components/schemas/api-shield_label_source" } }, "required": [ "name", "description", "metadata", "source", "last_updated", "created_at" ], "type": "object" } ] }, "api-shield_label_description": { "description": "The description of the label", "type": "string", "example": "All endpoints that deal with logins", "x-auditable": true }, "api-shield_label_mapped_resources": { "description": "Provides counts of what resources are linked to this label", "type": "object", "example": { "operations": 29 } }, "api-shield_label_metadata": { "description": "Metadata for the label", "type": "object", "example": { "foo": "bar" } }, "api-shield_label_name": { "description": "The name of the label", "type": "string", "example": "login", "x-auditable": true }, "api-shield_label_request": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/api-shield_label_description" }, "metadata": { "$ref": "#/components/schemas/api-shield_label_metadata" }, "name": { "$ref": "#/components/schemas/api-shield_label_name" } }, "required": [ "name" ] }, "api-shield_label_source": { "description": "* `user` - label is owned by the user\n* `managed` - label is owned by cloudflare\n", "type": "string", "enum": [ "user", "managed" ], "x-auditable": true }, "api-shield_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "api-shield_method": { "description": "The HTTP method used to access the endpoint.", "type": "string", "example": "GET", "enum": [ "GET", "POST", "HEAD", "OPTIONS", "PUT", "DELETE", "CONNECT", "PATCH", "TRACE" ], "x-auditable": true }, "api-shield_multiple-operation-response": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_operation" } } }, "required": [ "result" ], "type": "object" } ] }, "api-shield_multiple-operation-response-paginated": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/api-shield_operation" } ] } } }, "required": [ "result" ], "type": "object" } ] }, "api-shield_object-with-operation-id": { "type": "object", "properties": { "operation_id": { "allOf": [ { "description": "The ID of the operation", "type": "string", "x-auditable": true }, { "$ref": "#/components/schemas/api-shield_uuid-2" } ] } }, "required": [ "operation_id" ] }, "api-shield_old_kind": { "description": "Kind of schema", "type": "string", "example": "openapi_v3", "enum": [ "openapi_v3" ], "x-auditable": true }, "api-shield_old_operation_mitigation_action": { "description": "When set, this applies a mitigation action to this operation\n\n - `log` log request when request does not conform to schema for this operation\n - `block` deny access to the site when request does not conform to schema for this operation\n - `none` will skip mitigation for this operation\n - `null` indicates that no operation level mitigation is in place, see Zone Level Schema Validation Settings for mitigation action that will be applied\n", "type": "string", "example": "block", "enum": [ "log", "block", "none", null ], "nullable": true, "x-auditable": true }, "api-shield_old_operation_schema_validation_settings": { "type": "object", "properties": { "mitigation_action": { "$ref": "#/components/schemas/api-shield_old_operation_mitigation_action" }, "operation_id": { "$ref": "#/components/schemas/api-shield_uuid-2" } } }, "api-shield_old_operation_schema_validation_settings_modify_request": { "type": "object", "properties": { "mitigation_action": { "$ref": "#/components/schemas/api-shield_old_operation_mitigation_action" } } }, "api-shield_old_operation_schema_validation_settings_multiple_request": { "type": "object", "example": { "3818d821-5901-4147-a474-f5f5aec1d54e": { "mitigation_action": "log" }, "b17c8043-99a0-4202-b7d9-8f7cdbee02cd": { "mitigation_action": "block" } }, "additionalProperties": { "$ref": "#/components/schemas/api-shield_old_operation_schema_validation_settings_multiple_request_entry" } }, "api-shield_old_operation_schema_validation_settings_multiple_request_entry": { "description": "Operation ID to mitigation action mappings", "type": "object", "properties": { "mitigation_action": { "$ref": "#/components/schemas/api-shield_old_operation_mitigation_action" } } }, "api-shield_old_public_schema": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/api-shield_timestamp-2" }, "kind": { "$ref": "#/components/schemas/api-shield_old_kind" }, "name": { "description": "Name of the schema", "type": "string", "example": "petstore schema", "x-auditable": true }, "schema_id": { "$ref": "#/components/schemas/api-shield_uuid-2" }, "source": { "description": "Source of the schema", "type": "string", "example": "", "x-auditable": true }, "validation_enabled": { "$ref": "#/components/schemas/api-shield_old_validation_enabled" } }, "required": [ "schema_id", "name", "kind", "created_at" ] }, "api-shield_old_response_user_schemas_hosts": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/api-shield_timestamp-2" }, "hosts": { "description": "Hosts serving the schema, e.g zone.host.com", "type": "array", "items": { "type": "string" } }, "name": { "description": "Name of the schema", "type": "string", "example": "petstore schema", "x-auditable": true }, "schema_id": { "$ref": "#/components/schemas/api-shield_uuid-2" } }, "required": [ "schema_id", "name", "hosts", "created_at" ] }, "api-shield_old_schema_upload_details_errors_critical": { "type": "object", "properties": { "critical": { "description": "Diagnostic critical error events that occurred during processing.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_old_schema_upload_log_event" } }, "errors": { "description": "Diagnostic error events that occurred during processing.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_old_schema_upload_log_event" } } } }, "api-shield_old_schema_upload_details_warnings_only": { "type": "object", "properties": { "warnings": { "description": "Diagnostic warning events that occurred during processing. These events are non-critical errors found within the schema.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_old_schema_upload_log_event" } } } }, "api-shield_old_schema_upload_failure": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common-failure" }, { "properties": { "upload_details": { "$ref": "#/components/schemas/api-shield_old_schema_upload_details_errors_critical" } }, "type": "object" } ] }, "api-shield_old_schema_upload_log_event": { "type": "object", "properties": { "code": { "description": "Code that identifies the event that occurred.", "type": "integer", "example": 28, "x-auditable": true }, "locations": { "description": "JSONPath location(s) in the schema where these events were encountered. See [https://goessner.net/articles/JsonPath/](https://goessner.net/articles/JsonPath/) for JSONPath specification.", "type": "array", "items": { "description": "JSONPath location in the schema where these events were encountered. See [https://goessner.net/articles/JsonPath/](https://goessner.net/articles/JsonPath/) for JSONPath specification.", "example": ".paths[\"/user/{username}\"].put", "type": "string", "x-auditable": true } }, "message": { "description": "Diagnostic message that describes the event.", "type": "string", "example": "unsupported media type: application/octet-stream", "x-auditable": true } }, "required": [ "code" ] }, "api-shield_old_schema_upload_response": { "type": "object", "properties": { "schema": { "$ref": "#/components/schemas/api-shield_old_public_schema" }, "upload_details": { "$ref": "#/components/schemas/api-shield_old_schema_upload_details_warnings_only" } }, "required": [ "schema" ] }, "api-shield_old_validation_default_mitigation_action": { "description": "The default mitigation action used when there is no mitigation action defined on the operation\n\nMitigation actions are as follows:\n\n * `log` - log request when request does not conform to schema\n * `block` - deny access to the site when request does not conform to schema\n\nA special value of of `none` will skip running schema validation entirely for the request when there is no mitigation action defined on the operation\n", "type": "string", "example": "block", "enum": [ "none", "log", "block" ], "x-auditable": true }, "api-shield_old_validation_default_mitigation_action_patch": { "description": "The default mitigation action used when there is no mitigation action defined on the operation\nMitigation actions are as follows:\n\n * `log` - log request when request does not conform to schema\n * `block` - deny access to the site when request does not conform to schema\n\nA special value of of `none` will skip running schema validation entirely for the request when there is no mitigation action defined on the operation\n\n`null` will have no effect.\n", "type": "string", "example": "block", "enum": [ "none", "log", "block", null ], "nullable": true, "x-auditable": true }, "api-shield_old_validation_enabled": { "description": "Flag whether schema is enabled for validation.", "type": "boolean", "x-auditable": true }, "api-shield_old_validation_override_mitigation_action": { "description": "When set, this overrides both zone level and operation level mitigation actions.\n\n - `none` will skip running schema validation entirely for the request\n - `null` indicates that no override is in place\n", "type": "string", "example": "disable_override", "enum": [ "none", null ], "nullable": true, "x-auditable": true }, "api-shield_old_validation_override_mitigation_action_patch": { "description": "When set, this overrides both zone level and operation level mitigation actions.\n\n - `none` will skip running schema validation entirely for the request\n\nTo clear any override, use the special value `disable_override`\n\n`null` will have no effect.\n", "type": "string", "example": "none", "enum": [ "none", "disable_override", null ], "nullable": true, "x-auditable": true }, "api-shield_old_validation_override_mitigation_action_write": { "description": "When set, this overrides both zone level and operation level mitigation actions.\n\n - `none` will skip running schema validation entirely for the request\n - `null` indicates that no override is in place\n\nTo clear any override, use the special value `disable_override` or `null`\n", "type": "string", "example": "none", "enum": [ "none", "disable_override", null ], "nullable": true, "x-auditable": true }, "api-shield_old_zone_schema_validation_settings": { "type": "object", "properties": { "validation_default_mitigation_action": { "$ref": "#/components/schemas/api-shield_old_validation_default_mitigation_action" }, "validation_override_mitigation_action": { "$ref": "#/components/schemas/api-shield_old_validation_override_mitigation_action" } } }, "api-shield_old_zone_schema_validation_settings_patch": { "type": "object", "properties": { "validation_default_mitigation_action": { "$ref": "#/components/schemas/api-shield_old_validation_default_mitigation_action_patch" }, "validation_override_mitigation_action": { "$ref": "#/components/schemas/api-shield_old_validation_override_mitigation_action_patch" } } }, "api-shield_old_zone_schema_validation_settings_put": { "type": "object", "properties": { "validation_default_mitigation_action": { "$ref": "#/components/schemas/api-shield_old_validation_default_mitigation_action" }, "validation_override_mitigation_action": { "$ref": "#/components/schemas/api-shield_old_validation_override_mitigation_action_write" } }, "required": [ "validation_default_mitigation_action" ] }, "api-shield_openapi": { "description": "A OpenAPI 3.0.0 compliant schema.", "type": "object", "example": { "info": { "title": "OpenAPI JSON schema for www.example.com", "version": "1.0" }, "openapi": "3.0.0", "paths": { "... Further paths ...": {}, "/api/v1/users/{var1}": { "get": { "parameters": [ { "name": "var1", "in": "path", "required": true, "schema": { "type": "string" } } ] } } }, "servers": [ { "url": "www.example.com" } ] } }, "api-shield_openapi-with-thresholds": { "description": "A OpenAPI 3.0.0 compliant schema.", "type": "object", "example": { "info": { "title": "OpenAPI JSON schema for www.example.com", "version": "1.0" }, "openapi": "3.0.0", "paths": { "... Further paths ...": {}, "/api/v1/users/{var1}": { "get": { "parameters": [ { "name": "var1", "in": "path", "required": true, "schema": { "type": "string" } } ] } } }, "servers": [ { "url": "www.example.com" } ] } }, "api-shield_operation": { "allOf": [ { "$ref": "#/components/schemas/api-shield_standard_operation" }, { "default": {}, "nullable": true, "properties": { "features": { "$ref": "#/components/schemas/api-shield_operation_features" } }, "type": "object" } ] }, "api-shield_operation_feature_api_routing": { "type": "object", "properties": { "api_routing": { "description": "API Routing settings on endpoint.", "type": "object", "properties": { "last_updated": { "$ref": "#/components/schemas/api-shield_timestamp" }, "route": { "description": "Target route.", "type": "string", "example": "https://api.example.com/api/service", "x-auditable": true } } } }, "example": { "api_routing": { "last_updated": "2014-01-01T05:20:00.12345Z", "route": "https://api.example.com/api/service" } }, "readOnly": true }, "api-shield_operation_feature_confidence_intervals": { "type": "object", "properties": { "confidence_intervals": { "type": "object", "properties": { "last_updated": { "$ref": "#/components/schemas/api-shield_timestamp" }, "suggested_threshold": { "type": "object", "properties": { "confidence_intervals": { "type": "object", "properties": { "p90": { "$ref": "#/components/schemas/api-shield_confidence_intervals_bounds" }, "p95": { "$ref": "#/components/schemas/api-shield_confidence_intervals_bounds" }, "p99": { "$ref": "#/components/schemas/api-shield_confidence_intervals_bounds" } } }, "mean": { "description": "Suggested threshold.", "type": "number", "example": 25.5, "x-auditable": true } } } } } }, "example": { "confidence_intervals": { "last_updated": "2014-01-01T05:20:00.12345Z", "suggested_threshold": { "confidence_intervals": { "p90": { "lower": 23.1, "upper": 23.9 }, "p95": { "lower": 22, "upper": 24.1 }, "p99": { "lower": 20.2, "upper": 30 } }, "mean": 23.5 } } }, "readOnly": true }, "api-shield_operation_feature_parameter_schemas": { "type": "object", "properties": { "parameter_schemas": { "type": "object", "properties": { "last_updated": { "$ref": "#/components/schemas/api-shield_timestamp" }, "parameter_schemas": { "$ref": "#/components/schemas/api-shield_parameter_schemas_definition" } } } }, "readOnly": true, "required": [ "parameter_schemas", "last_updated" ] }, "api-shield_operation_feature_schema_info": { "type": "object", "properties": { "schema_info": { "type": "object", "properties": { "active_schema": { "description": "Schema active on endpoint.", "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/api-shield_timestamp" }, "id": { "$ref": "#/components/schemas/api-shield_uuid-2" }, "name": { "description": "Schema file name.", "type": "string", "example": "api-endpoints-8694824bf5c04d019edcbf399c03c103-api-discovery.example.com-thresholds.json", "x-auditable": true } } }, "mitigation_action": { "description": "Action taken on requests failing validation.", "type": "string", "example": "block", "enum": [ "none", "log", "block" ], "nullable": true, "x-auditable": true } } } }, "readOnly": true }, "api-shield_operation_feature_thresholds": { "type": "object", "properties": { "thresholds": { "type": "object", "properties": { "auth_id_tokens": { "$ref": "#/components/schemas/api-shield_auth_id_tokens" }, "data_points": { "$ref": "#/components/schemas/api-shield_data_points" }, "last_updated": { "$ref": "#/components/schemas/api-shield_timestamp" }, "p50": { "$ref": "#/components/schemas/api-shield_p50" }, "p90": { "$ref": "#/components/schemas/api-shield_p90" }, "p99": { "$ref": "#/components/schemas/api-shield_p99" }, "period_seconds": { "$ref": "#/components/schemas/api-shield_period_seconds" }, "requests": { "$ref": "#/components/schemas/api-shield_requests" }, "suggested_threshold": { "$ref": "#/components/schemas/api-shield_suggested_threshold" } } } }, "readOnly": true, "required": [ "period_seconds", "suggested_threshold", "p50", "p90", "p99", "requests", "auth_id_tokens", "data_points", "last_updated" ] }, "api-shield_operation_features": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/api-shield_operation_feature_thresholds" }, { "$ref": "#/components/schemas/api-shield_operation_feature_parameter_schemas" }, { "$ref": "#/components/schemas/api-shield_operation_feature_api_routing" }, { "$ref": "#/components/schemas/api-shield_operation_feature_confidence_intervals" }, { "$ref": "#/components/schemas/api-shield_operation_feature_schema_info" } ], "readOnly": true }, "api-shield_operation_id_selector": { "description": "Operation IDs selector", "type": "object", "properties": { "include": { "type": "object", "properties": { "operation_ids": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_uuid-2" }, "minItems": 1 } }, "required": [ "operation_ids" ] } }, "required": [ "include" ] }, "api-shield_operation_schema_fragment": { "description": "An OpenAPI operation object fragment containing schema information for an operation. May include parameter definitions, request body specifications, and a component schema extension.", "type": "object", "properties": { "parameters": { "description": "OpenAPI parameter objects describing path, query, header, or cookie parameters.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "requestBody": { "description": "OpenAPI request body object describing the expected request payload.", "additionalProperties": true, "type": "object" } }, "nullable": true }, "api-shield_operation_schemas": { "description": "OpenAPI JSON schemas for an operation, including both user-uploaded and Cloudflare-learned schemas.", "type": "object", "properties": { "learned": { "$ref": "#/components/schemas/api-shield_operation_schema_fragment" }, "uploaded": { "$ref": "#/components/schemas/api-shield_operation_schema_fragment" } }, "readOnly": true }, "api-shield_operation_with_labels_only": { "allOf": [ { "$ref": "#/components/schemas/api-shield_standard_operation" }, { "properties": { "labels": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label" } } }, "type": "object" } ] }, "api-shield_p50": { "description": "The p50 quantile of requests (in period_seconds).", "type": "integer", "readOnly": true, "x-auditable": true }, "api-shield_p90": { "description": "The p90 quantile of requests (in period_seconds).", "type": "integer", "readOnly": true, "x-auditable": true }, "api-shield_p99": { "description": "The p99 quantile of requests (in period_seconds).", "type": "integer", "readOnly": true, "x-auditable": true }, "api-shield_parameter_schemas_definition": { "description": "An operation schema object containing a response.", "type": "object", "properties": { "parameters": { "description": "An array containing the learned parameter schemas.", "example": [ { "description": "Sufficient requests have been observed for this parameter to provide high confidence in this parameter schema.", "in": "path", "name": "var1", "required": true, "schema": { "type": "integer", "maximum": 10, "minimum": 1 } } ], "items": { "type": "object" }, "readOnly": true, "type": "array" }, "responses": { "description": "An empty response object. This field is required to yield a valid operation schema.", "nullable": true, "readOnly": true, "type": "object" } }, "example": { "parameters": [ { "description": "Sufficient requests have been observed for this parameter to provide high confidence in this parameter schema.", "in": "path", "name": "var1", "required": true, "schema": { "type": "integer", "maximum": 10, "minimum": 1 } } ], "responses": null }, "readOnly": true }, "api-shield_patch_discoveries_response": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_api_discovery_patch_multiple_request" } }, "required": [ "result" ], "type": "object" } ] }, "api-shield_patch_discovery_response": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "state": { "$ref": "#/components/schemas/api-shield_api_discovery_state" } } } }, "required": [ "result" ], "type": "object" } ] }, "api-shield_patch_label_request": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/api-shield_label_description" }, "metadata": { "$ref": "#/components/schemas/api-shield_label_metadata" } } }, "api-shield_per_operation_setting": { "type": "object", "properties": { "mitigation_action": { "description": "When set, this applies a mitigation action to this operation which supersedes a global schema validation setting just for this operation\n\n - `\"log\"` - log request when request does not conform to schema for this operation\n - `\"block\"` - deny access to the site when request does not conform to schema for this operation\n - `\"none\"` - will skip mitigation for this operation\n", "type": "string", "example": "block", "enum": [ "log", "block", "none" ], "x-auditable": true }, "operation_id": { "$ref": "#/components/schemas/api-shield_uuid-2" } }, "required": [ "operation_id", "mitigation_action" ] }, "api-shield_per_operation_setting_change_base": { "type": "object", "properties": { "mitigation_action": { "description": "When set, this applies a mitigation action to this operation\n\n - `\"log\"` - log request when request does not conform to schema for this operation\n - `\"block\"` - deny access to the site when request does not conform to schema for this operation\n - `\"none\"` - will skip mitigation for this operation\n - `null` - clears any mitigation action\n", "type": "string", "example": "block", "enum": [ "log", "block", "none", null ], "nullable": true, "x-auditable": true } } }, "api-shield_period_seconds": { "description": "The period over which this threshold is suggested.", "type": "integer", "readOnly": true, "x-auditable": true }, "api-shield_position": { "description": "Update rule order among zone rules.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/api-shield_index" }, { "$ref": "#/components/schemas/api-shield_before" }, { "$ref": "#/components/schemas/api-shield_after" } ], "writeOnly": true }, "api-shield_post_labels_on_operation_request": { "type": "object", "properties": { "managed": { "description": "List of managed label names.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label_name" }, "minItems": 1 }, "user": { "description": "List of user label names.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label_name" }, "minItems": 1 } } }, "api-shield_public_schema": { "description": "A schema used in schema validation", "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/api-shield_timestamp-2" }, "kind": { "description": "The kind of the schema", "type": "string", "example": "openapi_v3", "enum": [ "openapi_v3" ], "readOnly": true, "x-auditable": true }, "name": { "description": "A human-readable name for the schema", "type": "string", "example": "petstore schema", "readOnly": true, "x-auditable": true }, "schema_id": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/api-shield_uuid-2" }, { "description": "A unique identifier of this schema", "format": "uuid", "readOnly": true, "type": "string" } ], "x-auditable": true }, "source": { "description": "The raw schema, e.g., the OpenAPI schema, either as JSON or YAML", "type": "string", "example": "", "readOnly": true, "x-auditable": true }, "validation_enabled": { "description": "An indicator if this schema is enabled", "type": "boolean", "x-auditable": true } }, "required": [ "schema_id", "name", "kind", "source", "created_at" ] }, "api-shield_public_schema_success_result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_public_schema" } }, "required": [ "result" ], "type": "object" } ] }, "api-shield_put_label_request": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/api-shield_label_description" }, "metadata": { "$ref": "#/components/schemas/api-shield_label_metadata" } } }, "api-shield_put_labels_on_operation_request": { "type": "object", "properties": { "managed": { "description": "List of managed label names. Omitting this property or passing an empty array will result in all managed labels being removed from the operation", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label_name" } }, "user": { "description": "List of user label names. Omitting this property or passing an empty array will result in all user labels being removed from the operation", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_label_name" } } } }, "api-shield_replace_operations_attached_to_label_request": { "type": "object", "properties": { "selector": { "$ref": "#/components/schemas/api-shield_operation_id_selector" } }, "required": [ "selector" ] }, "api-shield_request_expression_templates_fallthrough": { "type": "object", "properties": { "hosts": { "description": "List of hosts to be targeted in the expression", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "{zone}.domain1.tld", "domain2.tld" ] } }, "additionalProperties": false, "required": [ "hosts" ] }, "api-shield_requests": { "description": "The estimated number of requests covered by these calculations.", "type": "integer", "readOnly": true, "x-auditable": true }, "api-shield_response_expression_templates_fallthrough": { "type": "object", "properties": { "expression": { "description": "WAF Expression for fallthrough", "type": "string", "example": "(cf.api_gateway.fallthrough_detected)", "x-auditable": true }, "title": { "description": "Title for the expression", "type": "string", "example": "Fallthrough Expression for [zone.domain.tld]", "x-auditable": true } }, "required": [ "title", "expression" ] }, "api-shield_rule-properties": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/api-shield_action" }, "description": { "$ref": "#/components/schemas/api-shield_description-2" }, "enabled": { "$ref": "#/components/schemas/api-shield_enabled" }, "expression": { "$ref": "#/components/schemas/api-shield_expression" }, "selector": { "$ref": "#/components/schemas/api-shield_selector" }, "title": { "$ref": "#/components/schemas/api-shield_title-2" } } }, "api-shield_schema-response-with-thresholds": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "schemas": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_openapi-with-thresholds" } }, "timestamp": { "type": "string", "x-auditable": true } } } }, "required": [ "result" ], "type": "object" } ] }, "api-shield_schema_hosts": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/api-shield_timestamp-2" }, "hosts": { "description": "Hosts serving the schema, e.g zone.host.com", "type": "array", "items": { "type": "string" }, "readOnly": true, "x-auditable": true }, "name": { "description": "Name of the schema", "type": "string", "example": "petstore schema", "readOnly": true, "x-auditable": true }, "schema_id": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/api-shield_uuid-2" }, { "description": "A unique identifier of this schema", "format": "uuid", "readOnly": true, "type": "string" } ], "x-auditable": true } }, "required": [ "schema_id", "name", "hosts", "created_at" ] }, "api-shield_schema_issue_notification": { "type": "object", "properties": { "code": { "description": "A unique error code that describes the kind of issue with the schema", "type": "integer", "minimum": 1000 }, "message": { "description": "A short text explaining the issue with the schema", "type": "string" }, "source": { "type": "object", "nullable": true, "properties": { "locations": { "description": "A list of JSON path expression(s) that describe the location(s) of the issue within the provided resource. See [https://goessner.net/articles/JsonPath/](https://goessner.net/articles/JsonPath/) for JSONPath specification.", "type": "array", "items": { "example": ".paths[\"/user/{username}\"].put", "type": "string" } } } } }, "required": [ "code", "message" ] }, "api-shield_schema_response_discovery": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "schemas": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_openapi" } }, "timestamp": { "$ref": "#/components/schemas/api-shield_timestamp-2" } }, "required": [ "timestamp", "schemas" ] } }, "required": [ "result" ], "type": "object" } ] }, "api-shield_selector": { "description": "Select operations covered by this rule.\n\nFor details on selectors, see the [Cloudflare Docs](https://developers.cloudflare.com/api-shield/security/jwt-validation/).\n", "type": "object", "properties": { "exclude": { "description": "Ignore operations that were otherwise included by `include`.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_selector-exclude" }, "nullable": true }, "include": { "description": "Select all matching operations.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_selector-include" }, "nullable": true } } }, "api-shield_selector-exclude": { "type": "object", "properties": { "operation_ids": { "description": "Excluded operation IDs.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_uuid-2" }, "example": [ "f9c5615e-fe15-48ce-bec6-cfc1946f1bec", "56828eae-035a-4396-ba07-51c66d680a04" ] } } }, "api-shield_selector-include": { "type": "object", "properties": { "host": { "description": "Included hostnames.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_host" }, "example": [ "v1.example.com", "v2.example.com" ] } } }, "api-shield_selector-operation-state": { "description": "Details how `selector` interacted with an operation:\n - `included` operations are included by `selector` and will be covered by the Token Validation Rule\n - `excluded` operations are excluded by `selector` and will not be covered by the Token Validation Rule\n - `ignored` operations are not included by `selector` and will not be covered by the Token Validation Rule\n", "type": "string", "example": "included", "enum": [ "included", "excluded", "ignored" ], "x-auditable": true }, "api-shield_single-operation-response": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "allOf": [ { "$ref": "#/components/schemas/api-shield_operation" }, { "properties": { "schemas": { "$ref": "#/components/schemas/api-shield_operation_schemas" } }, "type": "object" } ] } }, "required": [ "result" ], "type": "object" } ] }, "api-shield_standard_operation": { "allOf": [ { "$ref": "#/components/schemas/api-shield_basic_operation" }, { "properties": { "last_updated": { "$ref": "#/components/schemas/api-shield_timestamp-2" }, "operation_id": { "$ref": "#/components/schemas/api-shield_uuid-2" } }, "required": [ "operation_id", "last_updated" ], "type": "object" } ] }, "api-shield_suggested_threshold": { "description": "The suggested threshold in requests done by the same auth_id or period_seconds.", "type": "integer", "readOnly": true, "x-auditable": true }, "api-shield_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "x-auditable": true }, "api-shield_timestamp-2": { "allOf": [ { "$ref": "#/components/schemas/api-shield_timestamp" }, { "readOnly": true, "type": "string", "x-auditable": true } ] }, "api-shield_title": { "type": "string", "example": "Example Token Validation Configuration", "maxLength": 50, "x-auditable": true }, "api-shield_title-2": { "description": "A human-readable name for the rule.", "type": "string", "example": "Example Token Validation Rule", "maxLength": 50, "x-auditable": true }, "api-shield_token_sources": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/api-shield_header" }, { "$ref": "#/components/schemas/api-shield_cookie" } ] }, "example": [ "http.request.headers[\"x-auth\"][0]", "http.request.cookies[\"Authorization\"][0]" ], "maxItems": 4, "minItems": 1 }, "api-shield_token_type": { "type": "string", "example": "JWT", "enum": [ "JWT" ], "x-auditable": true }, "api-shield_traffic_stats": { "type": "object", "properties": { "traffic_stats": { "type": "object", "properties": { "last_updated": { "$ref": "#/components/schemas/api-shield_timestamp-2" }, "period_seconds": { "description": "The period in seconds these statistics were computed over", "type": "integer", "example": 3600, "readOnly": true, "x-auditable": true }, "requests": { "description": "The average number of requests seen during this period", "type": "number", "format": "float", "example": 1987.06, "readOnly": true, "x-auditable": true } }, "required": [ "period_seconds", "requests", "last_updated" ] } }, "readOnly": true }, "api-shield_uuid": { "description": "UUID.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "x-auditable": true }, "api-shield_uuid-2": { "allOf": [ { "minLength": 36, "type": "string", "x-auditable": true }, { "$ref": "#/components/schemas/api-shield_uuid" } ] }, "argo-analytics_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/argo-analytics_messages" }, "messages": { "$ref": "#/components/schemas/argo-analytics_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": {}, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "argo-analytics_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/argo-analytics_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/argo-analytics_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "argo-analytics_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/argo-analytics_api-response-common" }, { "properties": { "result": { "anyOf": [ { "nullable": true, "type": "object" }, { "nullable": true, "type": "string" } ] } } } ] }, "argo-analytics_identifier": { "description": "Identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "argo-analytics_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "argo-analytics_response_single": { "allOf": [ { "$ref": "#/components/schemas/argo-analytics_api-response-single" }, { "properties": { "result": { "type": "object" } }, "type": "object" } ] }, "argo-config_api_response_common_failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/argo-config_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/argo-config_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Describes a failed API response.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "argo-config_api_response_single": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/argo-config_messages" }, "messages": { "$ref": "#/components/schemas/argo-config_messages" }, "result": { "$ref": "#/components/schemas/argo-config_result_object" }, "success": { "description": "Describes a successful API response.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "argo-config_editable": { "description": "Specifies if the setting is editable.", "type": "boolean", "x-auditable": true }, "argo-config_identifier": { "description": "Specifies the zone associated with the API call.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "argo-config_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "argo-config_modified_on": { "description": "Specifies the time when the setting was last modified.", "type": "string", "format": "date-time", "x-auditable": true }, "argo-config_patch": { "description": "Configures the enablement of Argo Smart Routing.", "type": "object", "properties": { "value": { "$ref": "#/components/schemas/argo-config_setting_value" } }, "required": [ "value" ] }, "argo-config_result_object": { "type": "object", "properties": { "editable": { "$ref": "#/components/schemas/argo-config_editable" }, "id": { "$ref": "#/components/schemas/argo-config_setting_id" }, "modified_on": { "$ref": "#/components/schemas/argo-config_modified_on" }, "value": { "$ref": "#/components/schemas/argo-config_setting_value" } }, "required": [ "id", "value", "editable" ] }, "argo-config_setting_id": { "description": "Specifies the identifier of the Argo Smart Routing setting.", "type": "string", "x-auditable": true }, "argo-config_setting_value": { "description": "Specifies the enablement value of Argo Smart Routing.", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true }, "art_APIError": { "type": "object", "properties": { "code": { "type": "integer", "example": 11005 }, "message": { "type": "string", "example": "art.api.parameter.invalid" } } }, "art_APIMessage": { "type": "object", "properties": { "code": { "type": "integer", "example": 1000 }, "message": { "type": "string", "example": "API in beta: expect breaking changes." } } }, "art_CommonQuery": { "description": "Defines fields that all query types share.", "type": "object", "properties": { "filters": { "description": "Filters to apply before aggregating results.", "type": "array", "items": { "$ref": "#/components/schemas/art_Filter" }, "example": [] }, "from": { "description": "The start of the query time range (inclusive). RFC3339 format with timezone is required (e.g. `2024-11-05T00:00:00Z`).", "type": "string", "format": "date-time", "example": "2024-11-05T00:00:00Z" }, "groupBy": { "description": "Specifies the column names to group results by. Requires valid columns for the target dataset.", "type": "array", "items": { "type": "string" }, "example": [ "country", "allowed" ] }, "stats": { "description": "Specifies the stat names to include in results. Requires valid stats for the target dataset (e.g. `attemptsTotal`, `bytesTotal`).", "type": "array", "items": { "type": "string" }, "example": [ "attemptsTotal" ] }, "to": { "description": "Specifies the end of the query time range (exclusive). Requires RFC3339 format with timezone.", "type": "string", "format": "date-time", "example": "2024-11-06T00:00:00Z" } }, "required": [ "from", "to", "groupBy", "stats", "filters" ] }, "art_DataSecurityContentFindingsTopNQuery": { "description": "Returns the top N integrations for content findings.", "type": "object", "properties": { "filters": { "description": "Filters to apply. `findingType = content` is applied automatically for CASB data.", "type": "array", "items": { "$ref": "#/components/schemas/art_Filter" }, "example": [] }, "from": { "description": "Start of the query time range (inclusive). RFC3339.", "type": "string", "format": "date-time", "example": "2024-11-01T00:00:00Z" }, "n": { "description": "Maximum number of integrations to return.", "type": "integer", "format": "int64", "example": 10, "minimum": 1 }, "to": { "description": "End of the query time range (exclusive). RFC3339.", "type": "string", "format": "date-time", "example": "2024-11-08T00:00:00Z" } }, "required": [ "from", "to", "n", "filters" ] }, "art_DataSecurityFindingsSummaryQuery": { "description": "Query for aggregate findings summary.", "type": "object", "properties": { "filters": { "description": "Filters to apply.", "type": "array", "items": { "$ref": "#/components/schemas/art_Filter" }, "example": [] }, "from": { "description": "Start of the query time range (inclusive). RFC3339.", "type": "string", "format": "date-time", "example": "2024-11-01T00:00:00Z" }, "to": { "description": "End of the query time range (exclusive). RFC3339.", "type": "string", "format": "date-time", "example": "2024-11-08T00:00:00Z" } }, "required": [ "from", "to", "filters" ] }, "art_DataSecurityFindingsTimeseriesQuery": { "description": "Query for findings timeseries.", "type": "object", "properties": { "filters": { "description": "Filters to apply.", "type": "array", "items": { "$ref": "#/components/schemas/art_Filter" }, "example": [] }, "from": { "description": "Start of the query time range (inclusive). RFC3339.", "type": "string", "format": "date-time", "example": "2024-11-01T00:00:00Z" }, "to": { "description": "End of the query time range (exclusive). RFC3339.", "type": "string", "format": "date-time", "example": "2024-11-08T00:00:00Z" } }, "required": [ "from", "to", "filters" ] }, "art_DataSecurityFindingsTimeseriesResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/art_APIError" }, "example": [] }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/art_APIMessage" } }, "result": { "$ref": "#/components/schemas/art_DataSecurityFindingsTimeseriesResult" }, "success": { "type": "boolean", "example": true } }, "required": [ "success", "result", "errors", "messages" ] }, "art_DataSecurityFindingsTimeseriesResult": { "description": "Merged CASB and CDE findings timeseries result.", "type": "object", "properties": { "resolution": { "description": "Always null for this endpoint.", "type": "string", "nullable": true }, "slots": { "description": "Contains time-bucketed result rows. Each slot includes a `timestamp` plus `content` and `posture` maps with `cloud` and `saas` keys.\n", "type": "array", "items": { "$ref": "#/components/schemas/art_ResultValues" }, "example": [ { "content": { "cloud": 150, "saas": 23 }, "posture": { "cloud": 0, "saas": 5 }, "timestamp": "2024-11-05T00:00:00Z" } ] } }, "required": [ "slots" ] }, "art_ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/art_APIError" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/art_APIMessage" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "example": false } }, "required": [ "success", "errors", "messages" ] }, "art_Filter": { "description": "A filter to apply to the query.", "type": "object", "properties": { "name": { "description": "Specifies the column name to filter on. Requires a valid column for the target dataset (e.g. `country`, `allowed`, `appId`).", "type": "string", "example": "country" }, "op": { "description": "Filter operator. Common values: `eq`, `neq`, `in`, `not_in`, `gt`, `lt`, `gte`, `lte`.\n", "type": "string", "example": "in" }, "values": { "description": "Values to match against. Type depends on the column.", "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "integer" }, { "type": "number" } ] }, "example": [ "US", "CA", "GB" ] } }, "required": [ "name", "op", "values" ] }, "art_QuerySummary": { "allOf": [ { "$ref": "#/components/schemas/art_CommonQuery" } ] }, "art_QueryTimeseries": { "allOf": [ { "$ref": "#/components/schemas/art_CommonQuery" }, { "properties": { "resolution": { "description": "Time bucket size for grouping results. Controls the granularity of the returned time slots.\n", "type": "string", "example": "hour" } }, "required": [ "resolution" ], "type": "object" } ] }, "art_QueryTopN": { "allOf": [ { "$ref": "#/components/schemas/art_CommonQuery" }, { "properties": { "n": { "description": "Maximum number of results to return.", "type": "integer", "format": "int64", "example": 10, "minimum": 1 }, "orderBy": { "description": "Specifies the stat name for sorting results in descending order. Requires a valid stat for the target dataset.", "type": "string", "example": "attemptsTotal" } }, "required": [ "n", "orderBy" ], "type": "object" } ] }, "art_ResultValues": { "description": "Maps field names to values. Keys represent stat names and group-by column names. Values depend on the dataset (strings, numbers, booleans).\n", "type": "object", "example": { "attemptsTotal": 1234, "country": "US" }, "additionalProperties": true }, "art_SummaryResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/art_APIError" }, "example": [] }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/art_APIMessage" } }, "result": { "$ref": "#/components/schemas/art_SummaryResult" }, "success": { "type": "boolean", "example": true } }, "required": [ "success", "result", "errors", "messages" ] }, "art_SummaryResult": { "type": "object", "properties": { "currentTotal": { "description": "Aggregated stats for the requested time range.", "type": "array", "items": { "$ref": "#/components/schemas/art_ResultValues" }, "example": [ { "attemptsTotal": 48291 } ] }, "previousTotal": { "description": "Aggregated stats for the equivalent preceding time range, for trend comparison.\n", "type": "array", "items": { "$ref": "#/components/schemas/art_ResultValues" }, "example": [ { "attemptsTotal": 41033 } ] } }, "required": [ "currentTotal", "previousTotal" ] }, "art_TimeseriesResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/art_APIError" }, "example": [] }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/art_APIMessage" } }, "result": { "$ref": "#/components/schemas/art_TimeseriesResult" }, "success": { "type": "boolean", "example": true } }, "required": [ "success", "result", "errors", "messages" ] }, "art_TimeseriesResult": { "type": "object", "properties": { "resolution": { "description": "The resolution used for time bucketing.", "type": "string", "example": "hour" }, "slots": { "description": "Time-bucketed result rows. Each slot contains a `time_bucket` field plus the requested stats and group-by dimensions.\n", "type": "array", "items": { "$ref": "#/components/schemas/art_ResultValues" }, "example": [ { "attemptsTotal": 1234, "country": "US", "time_bucket": "2024-11-05T00:00:00Z" } ] } }, "required": [ "slots", "resolution" ] }, "art_TopNResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/art_APIError" }, "example": [] }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/art_APIMessage" } }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/art_ResultValues" } }, "success": { "type": "boolean", "example": true } }, "required": [ "success", "result", "errors", "messages" ] }, "bill-subs-api_account_billing_history": { "type": "object", "properties": { "action": { "description": "The billing item action.", "type": "string", "example": "subscription" }, "amount": { "description": "The amount associated with this billing item.", "type": "number", "example": 20.99 }, "amount_to_pay": { "description": "The amount remaining to pay.", "type": "number", "example": 0 }, "currency": { "description": "The currency of the billing item.", "type": "string", "example": "USD" }, "description": { "description": "The billing item description.", "type": "string", "example": "The billing item description" }, "external_invoice_id": { "description": "The external invoice identifier.", "type": "string" }, "hosted_invoice_url": { "description": "URL to the hosted invoice.", "type": "string" }, "id": { "description": "Billing history item identifier.", "type": "string", "example": "b69a9f3492637782896352daae219e7d" }, "invoice_id": { "description": "The associated invoice identifier.", "type": "string" }, "occurred_at": { "description": "When the billing event occurred.", "type": "string", "format": "date-time", "example": "2014-03-01T12:21:59.3456Z" }, "receipt_id": { "description": "The associated receipt identifier.", "type": "string" }, "source": { "description": "The source of the billing item.", "type": "string" }, "source_invoice_id": { "description": "The source invoice identifier.", "type": "string" }, "status": { "description": "The status of the billing item.", "type": "string" }, "type": { "description": "The billing item type.", "type": "string", "example": "charge" } } }, "bill-subs-api_account_billing_history_collection": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/bill-subs-api_account_billing_history" } } }, "type": "object" } ] }, "bill-subs-api_account_credits_response": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "confirmed_balance_cents": { "description": "The confirmed credit balance in cents.", "type": "integer", "format": "int64", "example": 5000 }, "currency": { "description": "Currency of the credit balance.", "type": "string", "example": "USD" }, "days_remaining": { "description": "Days remaining until the credits expire.", "type": "integer", "format": "int64", "example": 180 }, "eligible": { "description": "Whether the account is eligible to receive credits.", "type": "boolean", "example": true }, "has_record": { "description": "Whether a credit record exists for the account.", "type": "boolean", "example": true }, "original_amount_cents": { "description": "The original credit amount in cents.", "type": "integer", "format": "int64", "example": 10000 }, "percent_consumed": { "description": "Percentage of the original credit amount consumed.", "type": "number", "format": "double", "example": 50 }, "projected_depletion_date": { "description": "Projected date when the credits will be depleted.", "type": "string", "format": "date-time", "example": "2024-07-01T00:00:00Z" }, "valid_from": { "description": "When the credits become valid.", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "valid_to": { "description": "When the credits expire.", "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z" } } } }, "type": "object" } ] }, "bill-subs-api_account_subscription_response_collection": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/bill-subs-api_subscription" } } }, "type": "object" } ] }, "bill-subs-api_account_subscription_response_single": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/bill-subs-api_subscription" } }, "type": "object" } ] }, "bill-subs-api_action": { "description": "The billing item action.", "type": "string", "example": "subscription", "maxLength": 30, "readOnly": true, "x-auditable": true }, "bill-subs-api_address_validation_request": { "type": "object", "properties": { "address": { "description": "Address line 1.", "type": "string" }, "address2": { "description": "Address line 2.", "type": "string" }, "city": { "description": "City.", "type": "string" }, "country": { "description": "Country code.", "type": "string" }, "state": { "description": "State or province.", "type": "string" }, "zipcode": { "description": "Postal or zip code.", "type": "string" } } }, "bill-subs-api_address_validation_response_single": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "validated_addresses": { "description": "List of validated address suggestions.", "type": "array", "items": { "$ref": "#/components/schemas/bill-subs-api_validated_address" } } } } }, "type": "object" } ] }, "bill-subs-api_amount": { "description": "The amount associated with this billing item.", "type": "number", "example": 20.99, "readOnly": true, "x-auditable": true }, "bill-subs-api_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "type": "object" }, "nullable": true }, "result_info": { "$ref": "#/components/schemas/bill-subs-api_result_info" } }, "type": "object" } ] }, "bill-subs-api_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/bill-subs-api_messages" }, "messages": { "$ref": "#/components/schemas/bill-subs-api_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": { "type": "object" }, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "bill-subs-api_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "bill-subs-api_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-common" }, { "properties": { "result": { "anyOf": [ { "nullable": true, "type": "object" }, { "nullable": true, "type": "string" } ] } }, "type": "object" } ] }, "bill-subs-api_available-rate-plan": { "type": "object", "properties": { "can_subscribe": { "$ref": "#/components/schemas/bill-subs-api_can_subscribe" }, "currency": { "$ref": "#/components/schemas/bill-subs-api_currency" }, "externally_managed": { "$ref": "#/components/schemas/bill-subs-api_externally_managed" }, "frequency": { "$ref": "#/components/schemas/bill-subs-api_schemas-frequency" }, "id": { "$ref": "#/components/schemas/bill-subs-api_identifier" }, "is_subscribed": { "$ref": "#/components/schemas/bill-subs-api_is_subscribed" }, "legacy_id": { "$ref": "#/components/schemas/bill-subs-api_legacy_id" }, "name": { "$ref": "#/components/schemas/bill-subs-api_schemas-name" }, "price": { "$ref": "#/components/schemas/bill-subs-api_schemas-price" } } }, "bill-subs-api_bad_debt_info": { "type": "object", "properties": { "already_paid": { "description": "Amount already paid towards the debt.", "type": "number", "example": 0 }, "bad_debt_status": { "description": "The current bad debt status of the account.", "type": "string", "example": "active" }, "invoices": { "description": "List of outstanding invoices contributing to bad debt.", "type": "array", "items": { "$ref": "#/components/schemas/bill-subs-api_account_billing_history" } }, "total_debt_amount": { "description": "Total outstanding debt amount.", "type": "number", "example": 20.99 } } }, "bill-subs-api_bad_debt_response_single": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/bill-subs-api_bad_debt_info" } }, "type": "object" } ] }, "bill-subs-api_billing-history": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/bill-subs-api_action" }, "amount": { "$ref": "#/components/schemas/bill-subs-api_amount" }, "currency": { "$ref": "#/components/schemas/bill-subs-api_currency" }, "description": { "$ref": "#/components/schemas/bill-subs-api_description" }, "id": { "$ref": "#/components/schemas/bill-subs-api_components-schemas-identifier" }, "occurred_at": { "$ref": "#/components/schemas/bill-subs-api_occurred_at" }, "type": { "$ref": "#/components/schemas/bill-subs-api_type" }, "zone": { "$ref": "#/components/schemas/bill-subs-api_schemas-zone" } }, "required": [ "id", "type", "action", "description", "occurred_at", "amount", "currency", "zone" ] }, "bill-subs-api_billing_history_collection": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/bill-subs-api_billing-history" } } }, "type": "object" } ] }, "bill-subs-api_billing_profile_request": { "description": "Request body for creating or updating a billing profile.", "type": "object", "properties": { "address": { "description": "Street address line 1.", "type": "string", "example": "123 Main Street" }, "address2": { "description": "Street address line 2 (apt, suite, etc.).", "type": "string", "example": "Apt 1" }, "billing_email": { "description": "Primary billing email address.", "type": "string", "example": "billing@example.com" }, "buying_rate_plan": { "description": "Rate plan being purchased right after profile setup.", "type": "string" }, "captcha_challenge_jwt": { "description": "Captcha challenge JWT issued during onboarding.", "type": "string" }, "cf_turnstile_response": { "description": "Cloudflare Turnstile response.", "type": "string" }, "city": { "description": "City on the billing profile.", "type": "string", "example": "Anytown" }, "company": { "description": "Company name on the billing profile.", "type": "string", "example": "Example Inc" }, "country": { "description": "ISO 3166-1 alpha-2 country code.", "type": "string", "example": "US" }, "first_name": { "description": "First name on the billing profile.", "type": "string", "example": "John" }, "h_captcha_response": { "description": "hCaptcha response.", "type": "string" }, "last_name": { "description": "Last name on the billing profile.", "type": "string", "example": "Doe" }, "preferred_locale": { "description": "Preferred locale for invoice rendering (BCP 47).", "type": "string", "example": "en-US" }, "secondary_billing_email": { "description": "Secondary billing email address for CC on invoices.", "type": "string", "example": "secondary@example.com" }, "state": { "description": "State or region on the billing profile.", "type": "string", "example": "CA" }, "tax_id_type": { "description": "Type of tax ID provided.", "type": "string" }, "telephone": { "description": "Contact phone number.", "type": "string", "example": "+1-555-555-5555" }, "vat": { "description": "VAT identifier.", "type": "string" }, "zipcode": { "description": "ZIP or postal code.", "type": "string", "example": "94103" } } }, "bill-subs-api_billing_response_single": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "account_type": { "type": "string", "example": "type" }, "address": { "type": "string", "example": "123 Main Street" }, "address2": { "type": "string", "example": "Apt 1" }, "balance": { "type": "string", "example": 0 }, "card_expiry_month": { "type": "integer", "example": 12 }, "card_expiry_year": { "type": "integer", "example": 2099 }, "card_number": { "type": "string", "example": 4242424242424242 }, "city": { "type": "string", "example": "Anytown" }, "company": { "type": "string", "example": "Company" }, "country": { "type": "string", "example": "Anycountry" }, "created_on": { "type": "string", "format": "date-time", "example": "2014-03-01T12:21:59.3456Z" }, "device_data": { "type": "string", "example": "sample_data", "writeOnly": true }, "edited_on": { "type": "string", "format": "date-time", "example": "2014-03-01T12:21:59.3456Z" }, "enterprise_billing_email": { "type": "string", "example": "johndoe@gmail.com", "x-auditable": true }, "enterprise_primary_email": { "type": "string", "example": "johndoe@gmail.com", "x-auditable": true }, "first_name": { "type": "string", "example": "John" }, "id": { "$ref": "#/components/schemas/bill-subs-api_components-schemas-identifier" }, "is_partner": { "type": "boolean", "example": false }, "last_name": { "type": "string", "example": "Doe" }, "next_bill_date": { "type": "string", "format": "date-time", "example": "2014-03-01T12:21:59.3456Z" }, "payment_address": { "type": "string", "example": "123 Main Street" }, "payment_address2": { "type": "string", "example": "Apt 1" }, "payment_city": { "type": "string", "example": "Anytown" }, "payment_country": { "type": "string", "example": "Anycountry" }, "payment_email": { "type": "string", "example": "johndoe@gmail.com" }, "payment_first_name": { "type": "string", "example": "John" }, "payment_gateway": { "type": "string", "example": "gateway", "writeOnly": true }, "payment_last_name": { "type": "string", "example": "Doe" }, "payment_nonce": { "type": "string", "example": "abc123", "writeOnly": true }, "payment_state": { "type": "string", "example": "state" }, "payment_zipcode": { "type": "string", "example": 12345 }, "primary_email": { "type": "string", "example": "johndoe@gmail.com", "x-auditable": true }, "state": { "type": "string", "example": "AnyState" }, "tax_id_type": { "type": "string", "example": "type" }, "telephone": { "type": "string", "example": 1234567899 }, "validation_code": { "type": "string", "example": 1111 }, "vat": { "type": "string", "example": "GB123456789" }, "zipcode": { "type": "string", "example": 12345 } } } }, "type": "object" } ] }, "bill-subs-api_bulk_account_subscription_response": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-collection" }, { "properties": { "result": { "type": "object", "properties": { "client_secrets": { "$ref": "#/components/schemas/bill-subs-api_client_secrets" }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/bill-subs-api_subscription" } } } } }, "type": "object" } ] }, "bill-subs-api_can_subscribe": { "description": "Indicates whether you can subscribe to this plan.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "bill-subs-api_cancel_reason": { "type": "object", "properties": { "id": { "description": "The cancel reason identifier.", "type": "string" }, "other": { "description": "Additional cancellation details.", "type": "string" }, "reason_code": { "description": "The cancellation reason codes.", "type": "array", "items": { "type": "string" } }, "submitted": { "description": "When the cancel reason was submitted.", "type": "string", "format": "date-time" }, "subscription_id": { "description": "The subscription identifier.", "type": "string" } } }, "bill-subs-api_cancel_reason_request": { "type": "object", "properties": { "other": { "description": "Additional cancellation details.", "type": "string" }, "reason_code": { "description": "The cancellation reason codes.", "type": "array", "items": { "type": "string" } } } }, "bill-subs-api_cancel_reason_response_single": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/bill-subs-api_cancel_reason" } }, "type": "object" } ] }, "bill-subs-api_client_secret": { "description": "Client secret for the subscription created with this plan.", "type": "string", "x-auditable": false }, "bill-subs-api_client_secret_response_single": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "client_secret": { "description": "The Stripe client secret for frontend payment confirmation.", "type": "string" } } } }, "type": "object" } ] }, "bill-subs-api_client_secrets": { "type": "array", "items": { "$ref": "#/components/schemas/bill-subs-api_client_secret" }, "nullable": true }, "bill-subs-api_component-value": { "type": "object", "properties": { "default": { "$ref": "#/components/schemas/bill-subs-api_default" }, "name": { "$ref": "#/components/schemas/bill-subs-api_components-schemas-name" }, "unit_price": { "$ref": "#/components/schemas/bill-subs-api_unit_price" } } }, "bill-subs-api_component_value": { "description": "A component value for a subscription.", "type": "object", "properties": { "default": { "description": "The default amount assigned.", "type": "number", "example": 5, "x-auditable": true }, "display_name": { "description": "A human-readable version of the component name.", "type": "string", "example": "Page Rules" }, "kind": { "description": "The type of component value. \"enum\" for discrete values (including boolean on/off toggles where 0=off and 1=on), \"sum\" for countable quantities, \"usage\" for metered billing components.", "type": "string", "example": "sum", "enum": [ "enum", "sum", "usage" ] }, "name": { "description": "The name of the component value.", "type": "string", "example": "page_rules", "x-auditable": true }, "price": { "description": "The unit price for the component value.", "type": "number", "example": 5, "x-auditable": true }, "value": { "description": "The amount of the component value assigned.", "type": "number", "example": 20, "x-auditable": true } } }, "bill-subs-api_component_values": { "description": "Configurable component values for the subscription.", "type": "array", "items": { "$ref": "#/components/schemas/bill-subs-api_component_value" } }, "bill-subs-api_components-schemas-identifier": { "description": "Billing item identifier tag.", "type": "string", "example": "b69a9f3492637782896352daae219e7d", "maxLength": 32, "readOnly": true, "x-auditable": true }, "bill-subs-api_components-schemas-name": { "description": "The unique component.", "example": "page_rules", "enum": [ "zones", "page_rules", "dedicated_certificates", "dedicated_certificates_custom" ], "x-auditable": true }, "bill-subs-api_currency": { "description": "The monetary unit in which pricing information is displayed.", "type": "string", "example": "USD", "readOnly": true, "x-auditable": true }, "bill-subs-api_current_period_end": { "description": "The end of the current period and also when the next billing is due.", "type": "string", "format": "date-time", "example": "2014-03-31T12:20:00Z", "readOnly": true, "x-auditable": true }, "bill-subs-api_current_period_start": { "description": "When the current billing period started. May match initial_period_start if this is the first period.", "type": "string", "format": "date-time", "example": "2014-05-11T12:20:00Z", "readOnly": true, "x-auditable": true }, "bill-subs-api_default": { "description": "The default amount allocated.", "type": "number", "example": 5, "x-auditable": true }, "bill-subs-api_description": { "description": "The billing item description.", "type": "string", "example": "The billing item description", "maxLength": 255, "readOnly": true, "x-auditable": true }, "bill-subs-api_duration": { "description": "The duration of the plan subscription.", "type": "number", "example": 1, "x-auditable": true }, "bill-subs-api_externally_managed": { "description": "Indicates whether this plan is managed externally.", "type": "boolean", "example": false, "default": false, "x-auditable": true }, "bill-subs-api_frequency": { "description": "How often the subscription is renewed automatically.", "type": "string", "example": "monthly", "enum": [ "weekly", "monthly", "quarterly", "yearly" ], "x-auditable": true }, "bill-subs-api_frequency_response": { "description": "How often the subscription is renewed automatically (computed field).", "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_frequency" }, { "enum": [ "weekly", "monthly", "quarterly", "yearly", "not-applicable" ], "type": "string" } ], "readOnly": true, "x-stainless-terraform-configurability": "computed" }, "bill-subs-api_identifier": { "description": "Identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "bill-subs-api_install_id": { "description": "app install id.", "type": "string", "deprecated": true, "x-auditable": true }, "bill-subs-api_is_subscribed": { "description": "Indicates whether you are currently subscribed to this plan.", "type": "boolean", "example": false, "default": false, "x-auditable": true }, "bill-subs-api_legacy_id": { "description": "The legacy identifier for this rate plan, if any.", "type": "string", "example": "free", "readOnly": true, "x-auditable": true }, "bill-subs-api_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "bill-subs-api_name": { "description": "The domain name", "type": "string", "example": "example.com", "maxLength": 253, "pattern": "^([a-zA-Z0-9][\\-a-zA-Z0-9]*\\.)+[\\-a-zA-Z0-9]{2,20}$", "readOnly": true, "x-auditable": true }, "bill-subs-api_occurred_at": { "description": "When the billing item was created.", "type": "string", "format": "date-time", "example": "2014-03-01T12:21:59.3456Z", "readOnly": true, "x-auditable": true }, "bill-subs-api_payment_intent_response_single": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "client_secret": { "description": "The Stripe client secret for frontend payment method collection.", "type": "string" }, "intent_type": { "description": "The type of Stripe intent created.", "type": "string" } } } }, "type": "object" } ] }, "bill-subs-api_payment_method": { "type": "object", "properties": { "address": { "description": "Billing address line 1.", "type": "string" }, "address2": { "description": "Billing address line 2.", "type": "string" }, "bank_account_type": { "description": "Bank account type.", "type": "string" }, "bank_code": { "description": "Bank code.", "type": "string" }, "bank_country": { "description": "Bank country.", "type": "string" }, "bank_name": { "description": "Bank name for bank-based payment methods.", "type": "string" }, "bank_routing_number": { "description": "Bank routing number.", "type": "string" }, "cashapp_cash_tag": { "description": "Cash App cash tag.", "type": "string" }, "city": { "description": "Billing city.", "type": "string" }, "country": { "description": "Billing country.", "type": "string" }, "default": { "description": "Whether this is the default payment method.", "type": "boolean" }, "device_data": { "description": "Device data for fraud prevention.", "type": "string", "writeOnly": true }, "expiration_date": { "description": "Card expiration date.", "type": "string", "readOnly": true }, "first_name": { "description": "Billing first name.", "type": "string" }, "id": { "description": "Payment method identifier.", "type": "string", "readOnly": true }, "last_four": { "description": "Last four digits of the card number.", "type": "string", "example": "4242", "readOnly": true }, "last_name": { "description": "Billing last name.", "type": "string" }, "nick_name": { "description": "A nickname for the payment method.", "type": "string" }, "payment_account_email": { "description": "Email associated with the payment account.", "type": "string" }, "payment_email": { "description": "Payment email address.", "type": "string" }, "payment_gateway": { "description": "The payment gateway used.", "type": "string", "writeOnly": true }, "payment_nonce": { "description": "Payment nonce for tokenized payments.", "type": "string", "writeOnly": true }, "state": { "description": "Billing state.", "type": "string" }, "type": { "description": "The payment method type.", "type": "string", "example": "CREDIT_CARD", "enum": [ "CREDIT_CARD", "PAYPAL", "CASHAPP", "SEPA_DEBIT", "LINK", "ACH_DIRECT_DEBIT" ] }, "zipcode": { "description": "Billing zip code.", "type": "string" } } }, "bill-subs-api_payment_method_response_collection": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/bill-subs-api_payment_method" } } }, "type": "object" } ] }, "bill-subs-api_payment_method_response_single": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/bill-subs-api_payment_method" } }, "type": "object" } ] }, "bill-subs-api_plan_response_collection": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/bill-subs-api_schemas-rate-plan" } } }, "type": "object" } ] }, "bill-subs-api_price": { "description": "The price of the subscription that will be billed, in US dollars.", "type": "number", "example": 20, "readOnly": true, "x-auditable": true }, "bill-subs-api_rate-plan": { "type": "object", "properties": { "components": { "$ref": "#/components/schemas/bill-subs-api_schemas-component_values" }, "currency": { "$ref": "#/components/schemas/bill-subs-api_currency" }, "duration": { "$ref": "#/components/schemas/bill-subs-api_duration" }, "frequency": { "$ref": "#/components/schemas/bill-subs-api_schemas-frequency" }, "id": { "$ref": "#/components/schemas/bill-subs-api_rate-plan_components-schemas-identifier" }, "name": { "$ref": "#/components/schemas/bill-subs-api_schemas-name" } } }, "bill-subs-api_rate-plan_components-schemas-identifier": { "description": "Plan identifier tag.", "type": "string", "example": "free", "readOnly": true, "x-auditable": true }, "bill-subs-api_rate_plan": { "description": "The rate plan applied to the subscription.", "type": "object", "properties": { "currency": { "description": "The currency applied to the rate plan subscription.", "type": "string", "example": "USD", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "externally_managed": { "description": "Whether this rate plan is managed externally from Cloudflare.", "type": "boolean", "example": false, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "id": { "description": "The ID of the rate plan.", "type": "string", "example": "free", "x-auditable": true }, "is_contract": { "description": "Whether a rate plan is enterprise-based (or newly adopted term contract).", "type": "boolean", "example": false, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "public_name": { "description": "The full name of the rate plan.", "type": "string", "example": "Business Plan", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "scope": { "description": "The scope that this rate plan applies to.", "type": "string", "example": "zone", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "sets": { "description": "The list of sets this rate plan applies to. Returns array of strings.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [], "x-stainless-terraform-configurability": "optional" } } }, "bill-subs-api_rate_plan_simple_response": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "components": { "description": "Pricing components that make up this rate plan.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "currency": { "description": "Currency of the rate plan pricing.", "type": "string", "example": "USD" }, "id": { "description": "The uppercase rate plan public key.", "type": "string", "example": "TEAMS_FREE" }, "public_name": { "description": "Human-readable description of the rate plan.", "type": "string", "example": "Cloudflare Teams Free" } } } }, "type": "object" } ] }, "bill-subs-api_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters", "type": "number", "example": 2000 } } }, "bill-subs-api_schemas-component_values": { "description": "Array of available components values for the plan.", "type": "array", "items": { "$ref": "#/components/schemas/bill-subs-api_component-value" } }, "bill-subs-api_schemas-frequency": { "description": "The frequency at which you will be billed for this plan.", "type": "string", "example": "monthly", "enum": [ "weekly", "monthly", "quarterly", "yearly" ], "readOnly": true, "x-auditable": true }, "bill-subs-api_schemas-identifier": { "description": "Subscription identifier tag.", "type": "string", "example": "506e3185e9c882d175a2d0cb0093d9f2", "maxLength": 32, "readOnly": true, "x-auditable": true }, "bill-subs-api_schemas-name": { "description": "The plan name.", "type": "string", "example": "Free Plan", "maxLength": 80, "readOnly": true, "x-auditable": true }, "bill-subs-api_schemas-price": { "description": "The amount you will be billed for this plan.", "type": "number", "example": 0, "x-auditable": true }, "bill-subs-api_schemas-rate-plan": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_rate-plan" } ] }, "bill-subs-api_schemas-zone": { "type": "object", "properties": { "name": { "type": "string", "readOnly": true, "x-auditable": true } } }, "bill-subs-api_state": { "description": "The state that the subscription is in.", "type": "string", "example": "Paid", "enum": [ "Trial", "Provisioned", "Paid", "AwaitingPayment", "Cancelled", "Failed", "Expired" ], "readOnly": true, "x-auditable": true }, "bill-subs-api_subscription": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_subscription-v2" } ] }, "bill-subs-api_subscription-v2": { "type": "object", "properties": { "app": { "description": "Cloudflare Apps Marketplace is sunset. This field is retained for legacy grandfathered app subscriptions only.", "type": "object", "deprecated": true, "properties": { "install_id": { "$ref": "#/components/schemas/bill-subs-api_install_id" } } }, "component_values": { "$ref": "#/components/schemas/bill-subs-api_component_values" }, "currency": { "$ref": "#/components/schemas/bill-subs-api_currency" }, "current_period_end": { "$ref": "#/components/schemas/bill-subs-api_current_period_end" }, "current_period_start": { "$ref": "#/components/schemas/bill-subs-api_current_period_start" }, "frequency": { "$ref": "#/components/schemas/bill-subs-api_frequency" }, "id": { "$ref": "#/components/schemas/bill-subs-api_schemas-identifier" }, "price": { "$ref": "#/components/schemas/bill-subs-api_price" }, "rate_plan": { "$ref": "#/components/schemas/bill-subs-api_rate_plan" }, "state": { "$ref": "#/components/schemas/bill-subs-api_state" }, "zone": { "$ref": "#/components/schemas/bill-subs-api_zone" } } }, "bill-subs-api_subscription_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_subscription-v2" }, { "properties": { "frequency": { "$ref": "#/components/schemas/bill-subs-api_frequency_response" } }, "type": "object" } ] }, "bill-subs-api_type": { "description": "The billing item type.", "type": "string", "example": "charge", "maxLength": 30, "readOnly": true, "x-auditable": true }, "bill-subs-api_unit_price": { "description": "The unit price of the component.", "type": "number", "example": 1, "readOnly": true, "x-auditable": true }, "bill-subs-api_unpaid_invoices_response_single": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "invoices": { "description": "List of unpaid invoices.", "type": "array", "items": { "$ref": "#/components/schemas/bill-subs-api_account_billing_history" } } } } }, "type": "object" } ] }, "bill-subs-api_user_subscription_response_collection": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/bill-subs-api_subscription" } } }, "type": "object" } ] }, "bill-subs-api_user_subscription_response_single": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "type": "object" } }, "type": "object" } ] }, "bill-subs-api_validated_address": { "type": "object", "properties": { "address": { "description": "Validated address line 1.", "type": "string" }, "address2": { "description": "Validated address line 2.", "type": "string" }, "city": { "description": "Validated city.", "type": "string" }, "country": { "description": "Validated country code.", "type": "string" }, "state": { "description": "Validated state or province.", "type": "string" }, "validation_code": { "description": "The validation result code.", "type": "string" }, "zipcode": { "description": "Validated postal or zip code.", "type": "string" } } }, "bill-subs-api_zone": { "description": "A simple zone object. May have null properties if not a zone subscription.", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/bill-subs-api_identifier" }, "name": { "$ref": "#/components/schemas/bill-subs-api_name" } } }, "bill-subs-api_zone_subscription_response_single": { "allOf": [ { "$ref": "#/components/schemas/bill-subs-api_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/bill-subs-api_subscription_response" } }, "type": "object" } ] }, "billable-usage-api_api-response-common-failure": { "description": "Represents a failed API response.", "type": "object", "properties": { "errors": { "description": "Contains error details describing why the request failed.", "type": "array", "items": { "$ref": "#/components/schemas/billable-usage-api_message" }, "example": [ { "code": 1183, "message": "Invalid request parameters: Please ensure all required parameters are included and correctly formatted." } ], "minItems": 1 }, "messages": { "description": "Contains informational notices about the response.", "type": "array", "items": { "$ref": "#/components/schemas/billable-usage-api_message" }, "nullable": true }, "result": { "description": "Contains the response payload (always null on failure).", "type": "object", "nullable": true }, "success": { "description": "Indicates whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "billable-usage-api_cost_and_usage_data": { "description": "A single cost and usage record for a metered product within a specific charge period, aligned with the FinOps FOCUS v1.3 specification.", "type": "object", "properties": { "BilledCost": { "description": "A charge serving as the basis for invoicing, inclusive of all reduced rates and discounts while excluding the amortization of upfront charges (one-time or recurring).", "type": "number", "example": 0, "nullable": true }, "BillingAccountId": { "description": "Public identifier of the Cloudflare account (account tag).", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" }, "BillingAccountName": { "description": "Display name of the Cloudflare account.", "type": "string", "example": "My Account" }, "BillingCurrency": { "description": "Currency that a charge was billed in (ISO 4217).", "type": "string", "example": "USD", "nullable": true }, "BillingPeriodEnd": { "description": "Exclusive end of the billing cycle that contains this usage record.", "type": "string", "format": "date-time", "example": "2025-06-01T00:00:00Z", "nullable": true }, "BillingPeriodStart": { "description": "Inclusive start of the billing cycle that contains this usage record.", "type": "string", "format": "date-time", "example": "2025-05-01T00:00:00Z", "nullable": true }, "ChargeCategory": { "description": "Highest-level classification of a charge based on the nature of how it gets billed. Currently only \"Usage\" is supported.", "type": "string", "example": "Usage", "enum": [ "Usage" ] }, "ChargeClass": { "description": "Indicates whether the row represents a correction to one or more charges invoiced in a previous billing period.", "type": "string", "enum": [ "Correction" ], "nullable": true }, "ChargeDescription": { "description": "Self-contained summary of the charge's purpose and price.", "type": "string", "example": "Workers Standard Requests — daily usage" }, "ChargeFrequency": { "description": "Indicates how often a charge occurs. Currently only \"Usage-Based\" is supported.", "type": "string", "example": "Usage-Based", "enum": [ "Usage-Based" ] }, "ChargePeriodEnd": { "description": "Exclusive end of the time interval during which the usage was consumed.", "type": "string", "format": "date-time", "example": "2025-05-02T00:00:00Z" }, "ChargePeriodStart": { "description": "Inclusive start of the time interval during which the usage was consumed.", "type": "string", "format": "date-time", "example": "2025-05-01T00:00:00Z" }, "ConsumedQuantity": { "description": "Measured usage amount within the charge period. Reflects raw metered consumption before pricing transformations.", "type": "number", "example": 150000 }, "ConsumedUnit": { "description": "Unit of measure for the consumed quantity (e.g., \"GB\", \"Requests\", \"vCPU-Hours\").", "type": "string", "example": "Requests" }, "ContractedCost": { "description": "Cost calculated by multiplying ContractedUnitPrice and the corresponding PricingQuantity.", "type": "number", "example": 0.75, "nullable": true }, "ContractedUnitPrice": { "description": "The agreed-upon unit price for a single PricingUnit of the associated billable metric, inclusive of negotiated discounts, if present, while excluding any other discounts.", "type": "number", "example": 0.000005, "nullable": true }, "EffectiveCost": { "description": "The amortized cost of the charge after applying all reduced rates, discounts, and the applicable portion of relevant, prepaid purchases (one-time or recurring) that covered the charge.", "type": "number", "example": 0, "nullable": true }, "HostProviderName": { "description": "Name of the entity providing the underlying infrastructure or platform.", "type": "string", "example": "Cloudflare" }, "InvoiceIssuerName": { "description": "Name of the entity responsible for invoicing for the services consumed.", "type": "string", "example": "Cloudflare" }, "ListCost": { "description": "Cost calculated by multiplying ListUnitPrice and the corresponding PricingQuantity.", "type": "number", "example": 0.75, "nullable": true }, "ListUnitPrice": { "description": "Suggested provider-published unit price for a single PricingUnit of the associated billable metric, exclusive of any discounts.", "type": "number", "example": 0.000005, "nullable": true }, "PricingQuantity": { "description": "Volume of a given service used or purchased, based on the PricingUnit.", "type": "number", "example": 150000, "nullable": true }, "PricingUnit": { "description": "Provider-specified measurement unit for determining unit prices, indicating how the provider rates measured usage after applying pricing rules like block pricing.", "type": "string", "example": "Requests", "nullable": true }, "RegionId": { "description": "Provider-assigned identifier for an isolated geographic area where a service is provided.", "type": "string", "example": "EEUR", "nullable": true }, "RegionName": { "description": "Name of an isolated geographic area where a service is provided.", "type": "string", "example": "Eastern Europe", "nullable": true }, "ServiceProviderName": { "description": "Name of the entity that made the services available for purchase.", "type": "string", "example": "Cloudflare" }, "SubAccountId": { "description": "Unique identifier assigned to a grouping of services. For Cloudflare, this is the subscription or contract ID.", "type": "string", "example": "c9bd752d-9ca8-411d-b804-be44a758057f" }, "SubAccountName": { "description": "Name assigned to a grouping of services. For Cloudflare, this is the subscription or contract display name.", "type": "string", "example": "My Subscription" }, "Tags": { "description": "Tag values for the requested `GroupBy` keys. Omitted when `GroupBy` is not provided. Missing keys are omitted, and key-only tags are returned as boolean `true`. All other tag values are strings.", "type": "object", "example": { "team": "fintech" }, "additionalProperties": { "oneOf": [ { "type": "string" }, { "enum": [ true ], "type": "boolean" } ] } }, "x_BillableMetricId": { "description": "The unique identifier for the billable metric in the Cloudflare catalog. Cloudflare extension; replaces FOCUS SkuId.", "type": "string", "example": "workers_standard_requests" }, "x_BillableMetricName": { "description": "The display name of the billable metric. Cloudflare extension; replaces FOCUS SkuMeter.", "type": "string", "example": "Workers Standard Requests" }, "x_ProductCategoryName": { "description": "The product category the charge belongs to (e.g., \"Developer\", \"Cloudflare One\"). Cloudflare extension; replaces FOCUS ServiceCategory.", "type": "string", "example": "Developer" }, "x_ProductFamilyId": { "description": "The unique identifier for the product family in the Cloudflare catalog. Cloudflare extension; replaces FOCUS ServiceId.", "type": "string", "example": "workers" }, "x_ProductFamilyName": { "description": "The product family the charge belongs to (e.g., \"R2\", \"Workers\"). Cloudflare extension; replaces FOCUS ServiceName.", "type": "string", "example": "Workers" }, "x_ZoneId": { "description": "The identifier for the Cloudflare zone (zone tag). Cloudflare extension.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "nullable": true }, "x_ZoneName": { "description": "The display name of the Cloudflare zone. Cloudflare extension.", "type": "string", "example": "example.com", "nullable": true } }, "required": [ "ServiceProviderName", "InvoiceIssuerName", "HostProviderName", "BillingAccountId", "BillingAccountName", "ChargePeriodStart", "ChargePeriodEnd", "x_BillableMetricId", "x_BillableMetricName", "ChargeCategory", "ChargeFrequency", "ChargeDescription", "ConsumedQuantity", "ConsumedUnit" ] }, "billable-usage-api_identifier": { "description": "Represents a Cloudflare resource identifier tag.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "pattern": "^[0-9a-f]{32}$" }, "billable-usage-api_message": { "description": "Represents an API notice or error detail.", "type": "object", "properties": { "code": { "description": "Identifies the error or notice type.", "type": "integer" }, "message": { "description": "Describes the error or notice.", "type": "string" } }, "required": [ "message" ] }, "billable-usage-api_usage_info_response": { "description": "Represents a successful response containing subscription info.", "type": "object", "properties": { "errors": { "description": "Contains error details if the request failed.", "type": "array", "items": { "$ref": "#/components/schemas/billable-usage-api_message" }, "nullable": true }, "messages": { "description": "Contains any informational messages from the API.", "type": "array", "items": { "$ref": "#/components/schemas/billable-usage-api_message" }, "nullable": true }, "result": { "description": "Contains the usage info.", "type": "object", "properties": { "covered": { "description": "Indicates whether the account is covered.", "type": "boolean", "example": true }, "subscriptions": { "description": "List of subscriptions for the account.", "type": "array", "items": { "properties": { "billing_cycle_anchor_timestamp": { "description": "The subscription billing cycle anchor timestamp.", "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" }, "end_timestamp": { "description": "The subscription end timestamp. Omitted for active subscriptions; present only when the subscription has been cancelled.", "type": "string", "format": "date-time", "example": "2023-12-31T23:59:59Z" }, "id": { "description": "The identifier for the Cloudflare subscription.", "type": "string", "example": "3F3CD4CQ6N7FXO7IK6NVFJBOYA" }, "start_timestamp": { "description": "The subscription start timestamp.", "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" } }, "required": [ "id", "start_timestamp", "billing_cycle_anchor_timestamp" ], "type": "object" } } }, "required": [ "covered", "subscriptions" ] }, "success": { "description": "Indicates whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "billable-usage-api_usage_record": { "description": "Represents a single billable usage record.\n\nThis schema carries 19 of the 21 columns FOCUS 1.3 marks as mandatory. Mandatory columns are always present, using an explicit null when the value is unknown, so consumers can distinguish \"unknown\" from \"not provided\".\n\nKnown gap 1: `ServiceCategory` (FOCUS 1.3 section 3.1.55) is not yet implemented and does not appear in this schema. Cloudflare's product catalog does not yet have a stakeholder-approved mapping from product family to a FOCUS ServiceCategory value, so the column is omitted entirely rather than shipping unapproved values. It will be added once that mapping exists.\n\nKnown gap 2: `BillingPeriodEnd` (FOCUS 1.3 section 3.1.4) is not yet implemented and does not appear in this schema, because no authoritative source for it exists today. Deriving it by calendar arithmetic drifts for billing cycle anchors on day 29-31, and the billing provider's current period end describes only the current period, so it is wrong for backdated records. `BillingPeriodStart` is correctly sourced and is still reported, so records carry a billing period start with no corresponding end until an authoritative end date is available.\n\nPer FOCUS 1.3 section 4.1.4.1, the columns that are not part of FOCUS (`ServiceFamilyName`, `CumulatedPricingQuantity`, `CumulatedContractedCost`, `ZoneId`, `ZoneName` and `SubscriptionId`) would normally carry an `x_` prefix. They are kept unprefixed here to avoid a breaking change for existing consumers.", "type": "object", "properties": { "BilledCost": { "description": "The amount invoiced for this charge. PayGo is billed directly by Cloudflare, so this equals ContractedCost.", "type": "number", "example": 0.75 }, "BillingAccountId": { "description": "The identifier of the account the charge is billed to (account tag).", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" }, "BillingAccountName": { "description": "The display name of the billing account. Null when the name could not be resolved.", "type": "string", "example": "Example Account", "nullable": true }, "BillingCurrency": { "description": "Specifies the billing currency code (ISO 4217).", "type": "string", "example": "USD" }, "BillingPeriodStart": { "description": "Indicates the start of the billing period. There is no `BillingPeriodEnd` counterpart; see the known gaps described on this schema.", "type": "string", "format": "date-time", "example": "2025-02-01T00:00:00Z" }, "ChargeCategory": { "description": "Describes the nature of the charge. Always \"Usage\" for this endpoint, which only returns metered usage.", "type": "string", "example": "Usage", "enum": [ "Usage" ] }, "ChargeClass": { "description": "Indicates whether the row corrects a previously invoiced billing period. Always null for this endpoint, which does not return corrections.", "type": "string", "nullable": true }, "ChargeDescription": { "description": "A human-readable summary of the charge.", "type": "string", "example": "Workers Standard usage measured in Count", "nullable": true }, "ChargePeriodEnd": { "description": "Indicates the end of the charge period.", "type": "string", "format": "date-time", "example": "2025-02-02T00:00:00Z" }, "ChargePeriodStart": { "description": "Indicates the start of the charge period.", "type": "string", "format": "date-time", "example": "2025-02-01T00:00:00Z" }, "ConsumedQuantity": { "description": "Specifies the quantity consumed during this charge period.", "type": "number", "example": 150000 }, "ConsumedUnit": { "description": "A display name for the unit of measurement used for the product (for example, \"GB-months\", \"GB-seconds\"). May be empty when the unit is implicit in the service name.", "type": "string", "example": "GB-months" }, "ContractedCost": { "description": "Specifies the cost for this charge period in the billing currency.", "type": "number", "example": 0.75 }, "CumulatedContractedCost": { "description": "Specifies the cumulated cost for the billing period in the billing currency.", "type": "number", "example": 2.25 }, "CumulatedPricingQuantity": { "description": "Specifies the portion of usage that is actually subject to a unit price.", "type": "integer", "example": 4500000 }, "EffectiveCost": { "description": "The amortized cost of the charge. PayGo has no upfront commitments, so this equals ContractedCost.", "type": "number", "example": 0.75 }, "HostProviderName": { "description": "The provider that hosts the infrastructure or platform the service runs on.", "type": "string", "example": "Cloudflare, Inc." }, "InvoiceIssuerName": { "description": "The entity that issues the invoice for this charge.", "type": "string", "example": "Cloudflare, Inc." }, "ListCost": { "description": "The cost at published list prices, before any discount. PayGo has no commitment discounts, so this equals ContractedCost.", "type": "number", "example": 0.75 }, "PricingQuantity": { "description": "Specifies the pricing quantity for this charge period.", "type": "integer", "example": 150000 }, "PricingUnit": { "description": "The unit that PricingQuantity is expressed in. Unlike ConsumedUnit this is never empty; it falls back to \"Count\" when the service has no explicit unit.", "type": "string", "example": "Count" }, "ServiceFamilyName": { "description": "Identifies the product family for the Cloudflare service.", "type": "string", "example": "Workers" }, "ServiceName": { "description": "Identifies the Cloudflare service.", "type": "string", "example": "Workers Standard" }, "ServiceProviderName": { "description": "The provider of the purchased service.", "type": "string", "example": "Cloudflare, Inc." }, "SubscriptionId": { "description": "The identifier for the Cloudflare subscription.", "type": "string", "example": "3F3CD4CQ6N7FXO7IK6NVFJBOYA", "nullable": true }, "ZoneId": { "description": "The identifier for the Cloudflare zone (zone tag).", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "nullable": true }, "ZoneName": { "description": "The display name of the Cloudflare zone.", "type": "string", "example": "example.com", "nullable": true } }, "required": [ "ServiceProviderName", "InvoiceIssuerName", "HostProviderName", "BillingAccountId", "BillingAccountName", "ServiceName", "ChargeCategory", "ChargeClass", "ChargeDescription", "ChargePeriodStart", "ChargePeriodEnd", "BillingPeriodStart", "BillingCurrency", "ConsumedQuantity", "ConsumedUnit", "PricingQuantity", "PricingUnit", "CumulatedPricingQuantity", "ListCost", "ContractedCost", "EffectiveCost", "BilledCost", "CumulatedContractedCost" ] }, "billable-usage-api_usage_response": { "description": "Represents a successful response containing billable usage records.", "type": "object", "properties": { "errors": { "description": "Contains error details if the request failed.", "type": "array", "items": { "$ref": "#/components/schemas/billable-usage-api_message" }, "nullable": true }, "messages": { "description": "Contains informational notices about the response.", "type": "array", "items": { "$ref": "#/components/schemas/billable-usage-api_message" }, "nullable": true }, "result": { "description": "Contains the array of billable usage records.", "type": "array", "items": { "$ref": "#/components/schemas/billable-usage-api_usage_record" } }, "success": { "description": "Indicates whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "billable-usage-api_v2_filter_by": { "description": "Usage filters. Filters of different kinds are combined with AND, so a record must match every filter present to be returned.", "type": "object", "properties": { "MetricIds": { "description": "Restrict results to rows whose `x_BillableMetricId` matches one of these billable metric ids (e.g. `workers_standard_requests`). Values must be unique.", "type": "array", "items": { "maxLength": 128, "type": "string" }, "example": [ "workers_standard_requests", "http_transferred_bytes" ], "maxItems": 20, "uniqueItems": true }, "ProductFamilyIds": { "description": "Restrict results to billable metrics belonging to these product families. Values must be unique UUIDs.", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "3f1b9c1e-0000-4000-8000-000000000000" ], "maxItems": 10, "uniqueItems": true }, "Tags": { "description": "Restrict results by customer resource tags. Filters for different keys are combined with AND, while values within one filter are combined with OR. Keys must be unique and are case-sensitive.", "type": "array", "items": { "$ref": "#/components/schemas/billable-usage-api_v2_tag_filter" }, "maxItems": 10, "uniqueItems": true } }, "additionalProperties": false }, "billable-usage-api_v2_group_by": { "description": "A customer resource-tag key used to split result rows.", "type": "object", "properties": { "Key": { "description": "Case-sensitive customer resource-tag key.", "type": "string", "example": "team", "maxLength": 256, "minLength": 1 }, "Type": { "description": "Dimension category. Currently only customer resource tags are supported.", "type": "string", "example": "TAG", "enum": [ "TAG" ] } }, "additionalProperties": false, "required": [ "Type", "Key" ] }, "billable-usage-api_v2_tag_filter": { "description": "Values accepted for one customer resource-tag key.", "type": "object", "properties": { "Key": { "description": "Case-sensitive customer resource-tag key.", "type": "string", "example": "team", "maxLength": 256, "minLength": 1 }, "Values": { "description": "Tag values to match. Values are combined with OR and must be unique. An empty string matches a key-only tag.", "type": "array", "items": { "maxLength": 1024, "type": "string" }, "example": [ "fintech" ], "maxItems": 20, "minItems": 1, "uniqueItems": true } }, "additionalProperties": false, "required": [ "Key", "Values" ] }, "billable-usage-api_v2_time_period": { "description": "Charge period to query, i.e. when consumption happened, not when it was billed. `From` is inclusive and `To` is exclusive. `From` and `To` must be supplied together; supplying one without the other is an error. When both are omitted the range defaults to the start of the current month through today.", "type": "object", "properties": { "From": { "description": "Start of the range (ISO 8601). Required if `To` is set.", "type": "string", "format": "date-time", "example": "2025-05-01T00:00:00Z" }, "To": { "description": "End of the range (ISO 8601). Required if `From` is set. Must be after `From` and no more than 31 days after it.", "type": "string", "format": "date-time", "example": "2025-05-31T00:00:00Z" } }, "additionalProperties": false }, "billable-usage-api_v2_usage_query": { "description": "Filter criteria for a usage query. Every field is optional; an empty object is equivalent to omitting the body entirely. Unknown fields are rejected.", "type": "object", "properties": { "FilterBy": { "$ref": "#/components/schemas/billable-usage-api_v2_filter_by" }, "GroupBy": { "description": "Customer resource tags used to split result rows. At most two unique tag keys may be supplied.", "type": "array", "items": { "$ref": "#/components/schemas/billable-usage-api_v2_group_by" }, "maxItems": 2, "uniqueItems": true }, "TimePeriod": { "$ref": "#/components/schemas/billable-usage-api_v2_time_period" } }, "additionalProperties": false }, "billable-usage-api_v2_usage_response": { "description": "Successful response containing an array of FOCUS-aligned cost and usage records.", "type": "object", "properties": { "errors": { "description": "Contains error details if the request failed.", "type": "array", "items": { "$ref": "#/components/schemas/billable-usage-api_message" }, "nullable": true }, "messages": { "description": "Contains informational notices about the response.", "type": "array", "items": { "$ref": "#/components/schemas/billable-usage-api_message" }, "nullable": true }, "result": { "description": "Contains the array of cost and usage records.", "type": "array", "items": { "$ref": "#/components/schemas/billable-usage-api_cost_and_usage_data" } }, "success": { "description": "Indicates whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "bot-management_ai_bots_migration_opt_out": { "description": "Temporary migration flag tracking zones opted out of AI bots managed-rule updates.", "type": "boolean", "example": false, "default": false, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_ai_bots_protection": { "description": "Enable rule to block AI Scrapers and Crawlers.", "type": "string", "example": "block", "enum": [ "block", "disabled", "only_on_ad_pages" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_ai_search": { "description": "Configure robots.txt policy for AI search bots.", "type": "string", "example": "block", "enum": [ "disabled", "block", "only_on_ad_pages" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_ai_training": { "description": "Configure robots.txt policy for AI model training bots.", "type": "string", "example": "disallow", "enum": [ "disabled", "disallow", "block", "only_on_ad_pages" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_ai_user": { "description": "Configure robots.txt policy for AI assistant and agent bots.", "type": "string", "example": "only_on_ad_pages", "enum": [ "disabled", "block", "only_on_ad_pages" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/bot-management_messages" }, "messages": { "$ref": "#/components/schemas/bot-management_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "bot-management_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/bot-management_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/bot-management_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "bot-management_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/bot-management_api-response-common" } ] }, "bot-management_auto_update_model": { "description": "Automatically update to the newest bot detection models created by Cloudflare as they are released. [Learn more.](https://developers.cloudflare.com/bots/reference/machine-learning-models#model-versions-and-release-notes)", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_base_config": { "allOf": [ { "properties": { "ai_bots_migration_opt_out": { "$ref": "#/components/schemas/bot-management_ai_bots_migration_opt_out" }, "ai_bots_protection": { "$ref": "#/components/schemas/bot-management_ai_bots_protection" }, "ai_search": { "$ref": "#/components/schemas/bot-management_ai_search" }, "ai_training": { "$ref": "#/components/schemas/bot-management_ai_training" }, "ai_user": { "$ref": "#/components/schemas/bot-management_ai_user" }, "bot_preference_sync_enabled": { "$ref": "#/components/schemas/bot-management_bot_preference_sync_enabled" }, "cf_robots_variant": { "$ref": "#/components/schemas/bot-management_cf_robots_variant" }, "content_bots_protection": { "$ref": "#/components/schemas/bot-management_content_bots_protection" }, "crawler_protection": { "$ref": "#/components/schemas/bot-management_crawler_protection" }, "enable_js": { "$ref": "#/components/schemas/bot-management_enable_js" }, "is_robots_txt_managed": { "$ref": "#/components/schemas/bot-management_is_robots_txt_managed" }, "using_latest_model": { "$ref": "#/components/schemas/bot-management_using_latest_model" } } } ], "title": "Shared Config" }, "bot-management_bm_cookie_enabled": { "description": "Indicates that the bot management cookie can be placed on end user devices accessing the site. Defaults to true", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_bm_subscription_config": { "allOf": [ { "$ref": "#/components/schemas/bot-management_base_config" }, { "properties": { "auto_update_model": { "$ref": "#/components/schemas/bot-management_auto_update_model" }, "bm_cookie_enabled": { "$ref": "#/components/schemas/bot-management_bm_cookie_enabled" }, "stale_zone_configuration": { "description": "A read-only field that shows which unauthorized settings are currently active on the zone. These settings typically result from upgrades or downgrades.", "type": "object", "properties": { "fight_mode": { "$ref": "#/components/schemas/bot-management_fight_mode_turned_on" }, "optimize_wordpress": { "$ref": "#/components/schemas/bot-management_optimize_wordpress_turned_on" }, "sbfm_definitely_automated": { "$ref": "#/components/schemas/bot-management_sbfm_definitely_automated_turned_on" }, "sbfm_likely_automated": { "$ref": "#/components/schemas/bot-management_sbfm_likely_automated_turned_on" }, "sbfm_static_resource_protection": { "$ref": "#/components/schemas/bot-management_sbfm_static_resource_protection_turned_on" }, "sbfm_verified_bots": { "$ref": "#/components/schemas/bot-management_sbfm_verified_bots_turned_on" } }, "readOnly": true, "title": "stale_zone_configuration" }, "suppress_session_score": { "$ref": "#/components/schemas/bot-management_suppress_session_score" } } } ], "title": "BM Enterprise Subscription" }, "bot-management_bot_fight_mode_config": { "allOf": [ { "$ref": "#/components/schemas/bot-management_base_config" }, { "properties": { "fight_mode": { "$ref": "#/components/schemas/bot-management_fight_mode" }, "stale_zone_configuration": { "description": "A read-only field that shows which unauthorized settings are currently active on the zone. These settings typically result from upgrades or downgrades.", "type": "object", "properties": { "optimize_wordpress": { "$ref": "#/components/schemas/bot-management_optimize_wordpress_turned_on" }, "sbfm_definitely_automated": { "$ref": "#/components/schemas/bot-management_sbfm_definitely_automated_turned_on" }, "sbfm_likely_automated": { "$ref": "#/components/schemas/bot-management_sbfm_likely_automated_turned_on" }, "sbfm_static_resource_protection": { "$ref": "#/components/schemas/bot-management_sbfm_static_resource_protection_turned_on" }, "sbfm_verified_bots": { "$ref": "#/components/schemas/bot-management_sbfm_verified_bots_turned_on" }, "suppress_session_score": { "$ref": "#/components/schemas/bot-management_suppress_session_score_turned_off" } }, "readOnly": true, "title": "stale_zone_configuration" } } } ], "title": "Bot Fight Mode" }, "bot-management_bot_management_response_body": { "allOf": [ { "$ref": "#/components/schemas/bot-management_api-response-single" }, { "properties": { "result": { "oneOf": [ { "$ref": "#/components/schemas/bot-management_bot_fight_mode_config" }, { "$ref": "#/components/schemas/bot-management_sbfm_definitely_config" }, { "$ref": "#/components/schemas/bot-management_sbfm_likely_config" }, { "$ref": "#/components/schemas/bot-management_bm_subscription_config" } ] } }, "type": "object" } ] }, "bot-management_bot_preference_sync_enabled": { "description": "Enable Bot Preference Sync for this zone. When enabled, Cloudflare can serve robots.txt content derived from the zone's AI Search, AI User, and AI Training preferences.", "type": "boolean", "example": true, "default": false, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_cf_robots_variant": { "description": "Specifies the Robots Access Control License variant to use.", "type": "string", "example": "policy_only", "enum": [ "off", "policy_only" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_config_single": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/bot-management_bot_fight_mode_config" }, { "$ref": "#/components/schemas/bot-management_sbfm_definitely_config" }, { "$ref": "#/components/schemas/bot-management_sbfm_likely_config" }, { "$ref": "#/components/schemas/bot-management_bm_subscription_config" } ] }, "bot-management_content_bots_protection": { "description": "Enable rule to block content bots. When enabled, blocks automated traffic with low bot scores, excluding safe verified bot categories. Exceptions should be managed via skip rules.", "type": "string", "example": "disabled", "enum": [ "block", "disabled" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_crawler_protection": { "description": "Enable rule to punish AI Scrapers and Crawlers via a link maze.", "type": "string", "example": "enabled", "enum": [ "enabled", "disabled" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_enable_js": { "description": "Use lightweight, invisible JavaScript detections to improve Bot Management. [Learn more about JavaScript Detections](https://developers.cloudflare.com/bots/reference/javascript-detections/).", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_feedback_report": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "description": { "type": "string" }, "expression": { "description": "Wirefilter expression describing the traffic being reported.", "type": "string" }, "first_request_seen_at": { "type": "string", "format": "date-time" }, "last_request_seen_at": { "type": "string", "format": "date-time" }, "requests": { "type": "integer", "format": "int64" }, "requests_by_attribute": { "$ref": "#/components/schemas/bot-management_requests_by_attribute" }, "requests_by_score": { "$ref": "#/components/schemas/bot-management_requests_by_score" }, "requests_by_score_src": { "$ref": "#/components/schemas/bot-management_requests_by_score_src" }, "subtype": { "type": "string" }, "type": { "$ref": "#/components/schemas/bot-management_feedback_type" } }, "required": [ "type", "description", "expression", "first_request_seen_at", "last_request_seen_at", "requests", "requests_by_score", "requests_by_score_src", "requests_by_attribute" ] }, "bot-management_feedback_type": { "description": "Type of feedback report.", "type": "string", "example": "false_positive", "enum": [ "false_positive", "false_negative" ] }, "bot-management_fight_mode": { "description": "Whether to enable Bot Fight Mode.", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_fight_mode_turned_on": { "description": "Indicates that the zone's Bot Fight Mode is turned on.", "type": "boolean", "title": "fight_mode", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "bot-management_is_robots_txt_managed": { "description": "Enable cloudflare managed robots.txt. If an existing robots.txt is detected, then managed robots.txt will be prepended to the existing robots.txt.", "type": "boolean", "example": false, "default": false, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "bot-management_metric_requests": { "type": "object", "properties": { "metric": { "type": "string" }, "requests": { "type": "integer", "format": "int64" } }, "required": [ "metric", "requests" ] }, "bot-management_optimize_wordpress": { "description": "Whether to optimize Super Bot Fight Mode protections for Wordpress.", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_optimize_wordpress_turned_on": { "description": "Indicates that the zone's wordpress optimization for SBFM is turned on.", "type": "boolean", "title": "optimize_wordpress", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_requests_by_attribute": { "description": "Top attributes contributing to the feedback sample. Keys include topASNs, topCountries, topHosts, topIPs, topJA3Hashes, topJA4s, topPaths, topUserAgents.", "type": "object", "additionalProperties": { "items": { "$ref": "#/components/schemas/bot-management_metric_requests" }, "type": "array" } }, "bot-management_requests_by_score": { "description": "Map of bot scores (1-99) to request counts. Sum must equal `requests`.", "type": "object", "additionalProperties": { "format": "int64", "type": "integer" } }, "bot-management_requests_by_score_src": { "description": "Map of score source to request counts. Sum must equal `requests`.", "type": "object", "additionalProperties": { "format": "int64", "type": "integer" } }, "bot-management_sbfm_definitely_automated": { "description": "Super Bot Fight Mode (SBFM) action to take on definitely automated requests.", "type": "string", "example": "allow", "enum": [ "allow", "block", "managed_challenge" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_sbfm_definitely_automated_turned_on": { "description": "Indicates that the zone's definitely automated requests are being blocked or challenged.", "type": "string", "title": "sbfm_definitely_automated", "x-auditable": true }, "bot-management_sbfm_definitely_config": { "allOf": [ { "$ref": "#/components/schemas/bot-management_base_config" }, { "properties": { "optimize_wordpress": { "$ref": "#/components/schemas/bot-management_optimize_wordpress" }, "sbfm_definitely_automated": { "$ref": "#/components/schemas/bot-management_sbfm_definitely_automated" }, "sbfm_static_resource_protection": { "$ref": "#/components/schemas/bot-management_sbfm_static_resource_protection" }, "sbfm_verified_bots": { "$ref": "#/components/schemas/bot-management_sbfm_verified_bots" }, "stale_zone_configuration": { "description": "A read-only field that shows which unauthorized settings are currently active on the zone. These settings typically result from upgrades or downgrades.", "type": "object", "properties": { "fight_mode": { "$ref": "#/components/schemas/bot-management_fight_mode_turned_on" }, "sbfm_likely_automated": { "$ref": "#/components/schemas/bot-management_sbfm_likely_automated_turned_on" } }, "readOnly": true, "title": "stale_zone_configuration" } } } ], "title": "SBFM Pro Plan" }, "bot-management_sbfm_likely_automated": { "description": "Super Bot Fight Mode (SBFM) action to take on likely automated requests.", "type": "string", "example": "allow", "enum": [ "allow", "block", "managed_challenge" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_sbfm_likely_automated_turned_on": { "description": "Indicates that the zone's likely automated requests are being blocked or challenged.", "type": "string", "title": "sbfm_likely_automated", "x-auditable": true }, "bot-management_sbfm_likely_config": { "allOf": [ { "$ref": "#/components/schemas/bot-management_base_config" }, { "properties": { "optimize_wordpress": { "$ref": "#/components/schemas/bot-management_optimize_wordpress" }, "sbfm_definitely_automated": { "$ref": "#/components/schemas/bot-management_sbfm_definitely_automated" }, "sbfm_likely_automated": { "$ref": "#/components/schemas/bot-management_sbfm_likely_automated" }, "sbfm_static_resource_protection": { "$ref": "#/components/schemas/bot-management_sbfm_static_resource_protection" }, "sbfm_verified_bots": { "$ref": "#/components/schemas/bot-management_sbfm_verified_bots" }, "stale_zone_configuration": { "description": "A read-only field that shows which unauthorized settings are currently active on the zone. These settings typically result from upgrades or downgrades.", "type": "object", "properties": { "fight_mode": { "$ref": "#/components/schemas/bot-management_fight_mode_turned_on" } }, "readOnly": true, "title": "stale_zone_configuration" } } } ], "title": "SBFM Biz Plan" }, "bot-management_sbfm_static_resource_protection": { "description": "Super Bot Fight Mode (SBFM) to enable static resource protection.\nEnable if static resources on your application need bot protection.\nNote: Static resource protection can also result in legitimate traffic being blocked.\n", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_sbfm_static_resource_protection_turned_on": { "description": "Indicates that the zone's static resource protection is turned on.", "type": "string", "title": "sbfm_static_resource_protection", "x-auditable": true }, "bot-management_sbfm_verified_bots": { "description": "Super Bot Fight Mode (SBFM) action to take on verified bots requests.", "type": "string", "example": "allow", "enum": [ "allow", "block" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_sbfm_verified_bots_turned_on": { "description": "Indicates that the zone's verified bot requests are being blocked.", "type": "string", "title": "sbfm_verified_bots", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_suppress_session_score": { "description": "Whether to disable tracking the highest bot score for a session in the Bot Management cookie.", "type": "boolean", "example": false, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_suppress_session_score_turned_off": { "description": "Indicates that the zone's session score tracking is disabled.", "type": "boolean", "title": "suppress_session_score", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "bot-management_using_latest_model": { "description": "A read-only field that indicates whether the zone currently is running the latest ML model.\n", "type": "boolean", "example": true, "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "brand-protection-api_Error": { "type": "object", "properties": { "code": { "description": "Error code", "type": "integer" }, "errors": { "description": "Errors", "type": "object", "additionalProperties": {} }, "message": { "description": "Error message", "type": "string" }, "status": { "description": "Error name", "type": "string" } } }, "brand-protection-api_ImageFile": { "type": "object", "properties": { "image": { "type": "string", "format": "binary" } } }, "brand-protection-api_Logo": { "type": "object", "properties": { "id": { "type": "integer" }, "tag": { "type": "string" }, "upload_path": { "type": "string" } } }, "brand-protection-api_LogoMatch": { "type": "object", "properties": { "matches": { "type": "array", "items": { "additionalProperties": {}, "type": "object" } }, "total": { "type": "integer" } } }, "brand-protection-api_PaginationMetadata": { "type": "object", "properties": { "first_page": { "type": "integer" }, "last_page": { "type": "integer" }, "next_page": { "type": "integer" }, "page": { "type": "integer" }, "previous_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "brand-protection-api_Query": { "type": "object", "properties": { "max_time": { "type": "string", "format": "date-time", "nullable": true }, "min_time": { "type": "string", "format": "date-time", "nullable": true }, "scan": { "type": "boolean" }, "string_matches": {}, "tag": { "type": "string" } } }, "brand-protection-api_QueryBulk": { "type": "object", "properties": { "queries": { "type": "array", "items": { "additionalProperties": {}, "type": "object" } } } }, "brand-protection-api_QueryMatch": { "type": "object", "properties": { "matches": { "type": "array", "items": { "additionalProperties": {}, "type": "object" } }, "total": { "type": "integer" } } }, "brand-protection-api_URLInfo": { "type": "object", "properties": { "result": { "type": "array", "items": { "additionalProperties": {}, "type": "object" } } } }, "brand-protection-api_URLSubmit": { "type": "object", "properties": { "skipped_urls": { "type": "array", "items": { "additionalProperties": {}, "type": "object" } }, "submitted_urls": { "type": "array", "items": { "additionalProperties": {}, "type": "object" } } } }, "brapi_SerializedAXNode": { "description": "Accessibility tree node", "type": "object", "properties": { "autocomplete": { "type": "string" }, "checked": { "oneOf": [ { "type": "boolean" }, { "enum": [ "mixed" ], "type": "string" } ] }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/brapi_SerializedAXNode" } }, "description": { "type": "string" }, "disabled": { "type": "boolean" }, "expanded": { "type": "boolean" }, "focused": { "type": "boolean" }, "haspopup": { "type": "string" }, "invalid": { "type": "string" }, "keyshortcuts": { "type": "string" }, "level": { "type": "number" }, "modal": { "type": "boolean" }, "multiline": { "type": "boolean" }, "multiselectable": { "type": "boolean" }, "name": { "type": "string" }, "orientation": { "type": "string" }, "pressed": { "oneOf": [ { "type": "boolean" }, { "enum": [ "mixed" ], "type": "string" } ] }, "readonly": { "type": "boolean" }, "required": { "type": "boolean" }, "role": { "type": "string" }, "roledescription": { "type": "string" }, "selected": { "type": "boolean" }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "valuemax": { "type": "number" }, "valuemin": { "type": "number" }, "valuetext": { "type": "string" } }, "required": [ "role" ] }, "brex_ApiMessage": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } }, "brex_BrowserExtensionConfig": { "allOf": [ { "$ref": "#/components/schemas/brex_BrowserExtensionConfigBase" }, { "properties": { "created_at": { "description": "ISO 8601 timestamp of when the configuration was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "ISO 8601 timestamp of the last configuration update.", "type": "string", "format": "date-time" } }, "required": [ "created_at", "updated_at" ], "type": "object" } ] }, "brex_BrowserExtensionConfigBase": { "type": "object", "properties": { "min_extension_version": { "description": "Minimum required browser extension version.", "type": "string" }, "team_domain": { "description": "Team domain for the browser extension.", "type": "string" } }, "required": [ "team_domain" ] }, "brex_BrowserExtensionConfigInput": { "type": "object", "properties": { "min_extension_version": { "description": "Minimum required browser extension version.", "type": "string" }, "team_name": { "description": "Access team name. The service derives `team_domain` as `.cloudflareaccess.com`.", "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$" } }, "required": [ "team_name" ] }, "brex_ConfigResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/brex_ApiMessage" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/brex_ApiMessage" } }, "result": { "$ref": "#/components/schemas/brex_BrowserExtensionConfig" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] }, "brex_CreateConfigRequest": { "type": "object", "properties": { "config": { "$ref": "#/components/schemas/brex_BrowserExtensionConfigInput" } }, "required": [ "config" ] }, "brex_DeleteResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/brex_ApiMessage" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/brex_ApiMessage" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] }, "brex_DeviceState": { "type": "object", "properties": { "account_id": { "description": "Cloudflare account internal ID.", "type": "string" }, "created_at": { "description": "When the device state row was created.", "type": "string", "format": "date-time" }, "installed_extensions": { "type": "array", "items": { "$ref": "#/components/schemas/brex_InstalledExtension" } }, "observed_at": { "description": "When the browser extension took the inventory snapshot.", "type": "string", "format": "date-time" }, "physical_device_id": { "description": "Physical device ID from trusted device identity.", "type": "string", "nullable": true }, "registration_id": { "description": "Browser extension registration ID.", "type": "string" }, "updated_at": { "description": "When the device state row was last updated.", "type": "string", "format": "date-time" } }, "required": [ "account_id", "registration_id", "installed_extensions", "observed_at", "created_at", "updated_at" ] }, "brex_ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/brex_ApiMessage" }, "minItems": 1 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/brex_ApiMessage" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] }, "brex_InstalledExtension": { "type": "object", "properties": { "enabled": { "description": "Whether the extension is enabled.", "type": "boolean" }, "hostPermissions": { "description": "Browser extension host permissions (URL patterns).", "type": "array", "items": { "type": "string" } }, "id": { "description": "Browser extension ID.", "type": "string" }, "installType": { "description": "How the extension was installed.", "type": "string", "enum": [ "development", "normal", "admin", "sideload", "other" ] }, "name": { "description": "Browser extension display name.", "type": "string" }, "permissions": { "description": "Browser extension API permissions.", "type": "array", "items": { "type": "string" } }, "version": { "description": "Browser extension version string.", "type": "string" } }, "required": [ "id", "name", "version", "enabled", "installType", "permissions", "hostPermissions" ] }, "brex_InventoriesResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/brex_ApiMessage" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/brex_ApiMessage" } }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/brex_DeviceState" } }, "result_info": { "$ref": "#/components/schemas/brex_PaginationInfo" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "result_info", "success", "errors", "messages" ] }, "brex_InventoryResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/brex_ApiMessage" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/brex_ApiMessage" } }, "result": { "$ref": "#/components/schemas/brex_DeviceState" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "result", "success", "errors", "messages" ] }, "brex_PaginationInfo": { "type": "object", "properties": { "cursor": { "description": "Opaque cursor for the next page. Null when there are no more results.", "type": "string", "nullable": true }, "per_page": { "description": "Number of results returned per page.", "type": "integer" } }, "required": [ "per_page", "cursor" ] }, "brex_UpdateConfigRequest": { "type": "object", "properties": { "config": { "$ref": "#/components/schemas/brex_BrowserExtensionConfigInput" } }, "required": [ "config" ] }, "builds_APIResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "example": 12000 }, "message": { "type": "string", "example": "Not found" } }, "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "nullable": true }, "result_info": { "$ref": "#/components/schemas/builds_PaginationInfo" }, "success": { "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages", "result" ] }, "builds_BuildLogsResponse": { "type": "object", "properties": { "cursor": { "$ref": "#/components/schemas/builds_cursor" }, "lines": { "type": "array", "items": { "items": { "anyOf": [ { "description": "Unix epoch timestamp", "example": 1636472400, "type": "number" }, { "description": "Log message", "example": "Building worker...", "type": "string" } ] }, "maxItems": 2, "minItems": 2, "type": "array" } }, "truncated": { "type": "boolean", "example": false } } }, "builds_BuildOutcome": { "type": "string", "example": "success", "enum": [ "success", "fail", "skipped", "cancelled", "terminated" ] }, "builds_BuildResponse": { "type": "object", "properties": { "build_outcome": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/builds_BuildOutcome" } ], "nullable": true }, "build_trigger_metadata": { "$ref": "#/components/schemas/builds_BuildTriggerMetadataResponse" }, "build_uuid": { "$ref": "#/components/schemas/builds_build_uuid" }, "created_on": { "$ref": "#/components/schemas/builds_created_on" }, "initializing_on": { "type": "string", "format": "date-time", "nullable": true }, "modified_on": { "$ref": "#/components/schemas/builds_modified_on" }, "pull_request": { "type": "object", "nullable": true, "properties": { "created_on": { "$ref": "#/components/schemas/builds_created_on" }, "pull_request_url": { "type": "string", "format": "uri", "example": "https://github.com/cloudflare/workers-sdk/pull/123" } } }, "running_on": { "type": "string", "format": "date-time", "nullable": true }, "status": { "$ref": "#/components/schemas/builds_BuildStatus" }, "stopped_on": { "$ref": "#/components/schemas/builds_stopped_on" }, "trigger": { "description": "Trigger information without build_token_uuid", "type": "object", "properties": { "branch_excludes": { "$ref": "#/components/schemas/builds_branch_excludes" }, "branch_includes": { "$ref": "#/components/schemas/builds_branch_includes" }, "build_caching_enabled": { "$ref": "#/components/schemas/builds_build_caching_enabled" }, "build_command": { "$ref": "#/components/schemas/builds_build_command" }, "created_on": { "$ref": "#/components/schemas/builds_created_on" }, "deleted_on": { "$ref": "#/components/schemas/builds_deleted_on" }, "deploy_command": { "$ref": "#/components/schemas/builds_deploy_command" }, "external_script_id": { "$ref": "#/components/schemas/builds_external_script_id" }, "modified_on": { "$ref": "#/components/schemas/builds_modified_on" }, "path_excludes": { "$ref": "#/components/schemas/builds_path_excludes" }, "path_includes": { "$ref": "#/components/schemas/builds_path_includes" }, "repo_connection": { "$ref": "#/components/schemas/builds_UpsertRepoConnectionResponse" }, "root_directory": { "$ref": "#/components/schemas/builds_root_directory" }, "trigger_name": { "$ref": "#/components/schemas/builds_trigger_name" }, "trigger_uuid": { "$ref": "#/components/schemas/builds_trigger_uuid" } } } } }, "builds_BuildSeedRepoInput": { "type": "object", "properties": { "branch": { "description": "Repository branch to seed.", "allOf": [ { "$ref": "#/components/schemas/builds_branch" } ] }, "files": { "description": "Files to add or replace for this build. Maximum 2.", "type": "array", "items": { "$ref": "#/components/schemas/builds_BuildSeedRepoInputFile" }, "maxItems": 2 }, "owner": { "description": "Repository owner or namespace.", "type": "string", "example": "cloudflare" }, "path": { "description": "Path within the repository to seed.", "type": "string", "example": "/" }, "provider": { "description": "Source control provider for the seed repository.", "type": "string", "enum": [ "github", "gitlab" ] }, "repository": { "description": "Repository name.", "type": "string", "example": "workers-sdk" } }, "required": [ "provider", "owner", "repository" ] }, "builds_BuildSeedRepoInputFile": { "type": "object", "properties": { "content": { "example": "name = \"my-worker\"\nmain = \"src/index.js\"\n", "type": "string" }, "filename": { "type": "string", "example": "wrangler.toml" }, "isBase64": { "description": "Whether content is Base64-encoded.", "type": "boolean", "default": false }, "replace": { "description": "Existing text in the target file to replace with content.", "type": "string" } }, "required": [ "filename", "content" ] }, "builds_BuildStatus": { "type": "string", "example": "running", "enum": [ "queued", "initializing", "running", "stopped" ] }, "builds_BuildTriggerMetadataResponse": { "type": "object", "properties": { "author": { "type": "string", "example": "developer@cloudflare.com" }, "branch": { "$ref": "#/components/schemas/builds_branch" }, "build_command": { "$ref": "#/components/schemas/builds_build_command" }, "build_token_name": { "$ref": "#/components/schemas/builds_build_token_name" }, "build_token_uuid": { "$ref": "#/components/schemas/builds_build_token_uuid" }, "build_trigger_source": { "$ref": "#/components/schemas/builds_BuildTriggerSource" }, "commit_hash": { "$ref": "#/components/schemas/builds_commit_hash" }, "commit_message": { "type": "string", "example": "Add new feature" }, "deploy_command": { "$ref": "#/components/schemas/builds_deploy_command" }, "environment_variables": { "type": "object", "additionalProperties": { "type": "string" } }, "provider_account_name": { "$ref": "#/components/schemas/builds_provider_account_name" }, "provider_type": { "$ref": "#/components/schemas/builds_SCMProviderType" }, "repo_name": { "$ref": "#/components/schemas/builds_repo_name" }, "root_directory": { "$ref": "#/components/schemas/builds_root_directory" } } }, "builds_BuildTriggerSource": { "type": "string", "example": "push", "enum": [ "push", "pull_request", "manual", "api" ] }, "builds_BuildsByVersionResponse": { "type": "object", "properties": { "builds": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/builds_BuildResponse" } } } }, "builds_CanceledBuildResponse": { "type": "object", "properties": { "build_outcome": { "$ref": "#/components/schemas/builds_BuildOutcome" }, "build_uuid": { "$ref": "#/components/schemas/builds_build_uuid" }, "stopped_on": { "$ref": "#/components/schemas/builds_stopped_on" } } }, "builds_ConfigAutofillResponse": { "type": "object", "properties": { "config_file": { "type": "string", "example": "wrangler.toml", "nullable": true }, "default_worker_name": { "type": "string", "example": "my-worker", "nullable": true }, "env_worker_names": { "type": "object", "example": { "production": "my-worker-prod", "staging": "my-worker-staging" }, "additionalProperties": { "type": "string" }, "nullable": true }, "package_manager": { "description": "Package manager inferred from repository lockfiles; defaults to npm when none is detected.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/builds_PackageManager" } ] }, "scripts": { "type": "object", "example": { "build": "npm run build", "test": "npm test" }, "additionalProperties": { "type": "string" }, "nullable": true } } }, "builds_CreateBuildRequest": { "type": "object", "properties": { "branch": { "description": "Git branch name (required if commit_hash not provided)", "allOf": [ { "$ref": "#/components/schemas/builds_branch" } ] }, "commit_hash": { "description": "Git commit hash (required if branch not provided)", "allOf": [ { "$ref": "#/components/schemas/builds_commit_hash" } ] }, "seed_repo": { "description": "Optional repository and file overrides used to seed this build.", "allOf": [ { "$ref": "#/components/schemas/builds_BuildSeedRepoInput" } ] } }, "anyOf": [ { "required": [ "commit_hash" ] }, { "required": [ "branch" ] } ] }, "builds_CreateBuildTokenRequest": { "type": "object", "properties": { "build_token_name": { "$ref": "#/components/schemas/builds_build_token_name" }, "build_token_secret": { "type": "string", "example": "super-secret-token" }, "cloudflare_token_id": { "$ref": "#/components/schemas/builds_cloudflare_token_id" } }, "required": [ "build_token_name", "build_token_secret", "cloudflare_token_id" ] }, "builds_CreateBuildTokenResponse": { "type": "object", "properties": { "build_token_name": { "$ref": "#/components/schemas/builds_build_token_name" }, "build_token_uuid": { "$ref": "#/components/schemas/builds_build_token_uuid" }, "cloudflare_token_id": { "$ref": "#/components/schemas/builds_cloudflare_token_id" }, "owner_type": { "$ref": "#/components/schemas/builds_owner_type" } } }, "builds_CreateDeployHookRequest": { "type": "object", "properties": { "branch": { "$ref": "#/components/schemas/builds_branch" }, "deploy_hook_name": { "$ref": "#/components/schemas/builds_deploy_hook_name" } }, "required": [ "deploy_hook_name", "branch" ] }, "builds_CreateTriggerRequest": { "type": "object", "properties": { "branch_excludes": { "$ref": "#/components/schemas/builds_branch_excludes" }, "branch_includes": { "$ref": "#/components/schemas/builds_branch_includes" }, "build_caching_enabled": { "$ref": "#/components/schemas/builds_build_caching_enabled" }, "build_command": { "$ref": "#/components/schemas/builds_build_command" }, "build_token_uuid": { "$ref": "#/components/schemas/builds_build_token_uuid" }, "deploy_command": { "$ref": "#/components/schemas/builds_deploy_command" }, "external_script_id": { "$ref": "#/components/schemas/builds_external_script_id" }, "path_excludes": { "$ref": "#/components/schemas/builds_path_excludes" }, "path_includes": { "$ref": "#/components/schemas/builds_path_includes" }, "repo_connection_uuid": { "$ref": "#/components/schemas/builds_repo_connection_uuid" }, "root_directory": { "$ref": "#/components/schemas/builds_root_directory" }, "trigger_name": { "$ref": "#/components/schemas/builds_trigger_name" } }, "required": [ "external_script_id", "build_token_uuid", "trigger_name", "build_command", "deploy_command", "root_directory", "branch_includes", "branch_excludes", "path_includes", "path_excludes", "repo_connection_uuid" ] }, "builds_CreateWorkerBuildSettingsInput": { "description": "Build and deploy settings when creating a Worker build configuration", "type": "object", "properties": { "build_caching_enabled": { "default": true, "allOf": [ { "$ref": "#/components/schemas/builds_build_caching_enabled" } ] }, "build_command": { "$ref": "#/components/schemas/builds_build_command" }, "build_token_uuid": { "$ref": "#/components/schemas/builds_build_token_uuid" }, "deploy_command": { "$ref": "#/components/schemas/builds_deploy_command" }, "environment_variables": { "$ref": "#/components/schemas/builds_EnvironmentVariablesRequest" }, "path_excludes": { "$ref": "#/components/schemas/builds_path_excludes" }, "path_includes": { "$ref": "#/components/schemas/builds_path_includes" }, "root_directory": { "default": "/", "allOf": [ { "$ref": "#/components/schemas/builds_root_directory" } ] } }, "required": [ "build_command", "deploy_command", "build_token_uuid" ] }, "builds_CreateWorkerGitRepositoryFunfettiInput": { "description": "GitHub or GitLab repository input for creating a Worker build configuration", "type": "object", "properties": { "branch": { "description": "Git branch to watch for builds", "type": "string", "example": "main", "maxLength": 256, "minLength": 1 }, "provider_account_id": { "$ref": "#/components/schemas/builds_provider_account_id" }, "provider_account_name": { "$ref": "#/components/schemas/builds_provider_account_name" }, "provider_type": { "type": "string", "example": "github", "enum": [ "github", "gitlab" ] }, "repo_id": { "$ref": "#/components/schemas/builds_repo_id" }, "repo_name": { "$ref": "#/components/schemas/builds_repo_name" } }, "required": [ "repo_id", "repo_name", "provider_type", "provider_account_id", "provider_account_name", "branch" ] }, "builds_CreateWorkerGitRepositoryGrantInput": { "description": "Grant-backed repository input for creating a Worker build configuration", "type": "object", "properties": { "branch": { "description": "Git branch to watch for builds", "type": "string", "example": "main", "maxLength": 256, "minLength": 1 }, "grant_id": { "description": "Grant ID required for grant-backed providers", "type": "string", "example": "grant-123", "minLength": 1 }, "provider_account_id": { "$ref": "#/components/schemas/builds_provider_account_id" }, "provider_account_name": { "$ref": "#/components/schemas/builds_provider_account_name" }, "provider_type": { "type": "string", "example": "gitlab_internal", "enum": [ "gitlab_internal", "origin" ] }, "repo_id": { "$ref": "#/components/schemas/builds_repo_id" }, "repo_name": { "$ref": "#/components/schemas/builds_repo_name" } }, "required": [ "repo_id", "repo_name", "provider_type", "provider_account_id", "provider_account_name", "branch", "grant_id" ] }, "builds_CreateWorkerGitRepositoryInput": { "discriminator": { "mapping": { "github": "#/components/schemas/builds_CreateWorkerGitRepositoryFunfettiInput", "gitlab": "#/components/schemas/builds_CreateWorkerGitRepositoryFunfettiInput", "gitlab_internal": "#/components/schemas/builds_CreateWorkerGitRepositoryGrantInput", "origin": "#/components/schemas/builds_CreateWorkerGitRepositoryGrantInput" }, "propertyName": "provider_type" }, "oneOf": [ { "$ref": "#/components/schemas/builds_CreateWorkerGitRepositoryFunfettiInput" }, { "$ref": "#/components/schemas/builds_CreateWorkerGitRepositoryGrantInput" } ] }, "builds_CreateWorkerRequest": { "description": "Request body for creating a Worker build configuration.", "type": "object", "properties": { "git_repository": { "$ref": "#/components/schemas/builds_CreateWorkerGitRepositoryInput" }, "production_settings": { "$ref": "#/components/schemas/builds_CreateWorkerBuildSettingsInput" }, "script_tag": { "$ref": "#/components/schemas/builds_external_script_id" } }, "required": [ "script_tag", "git_repository", "production_settings" ] }, "builds_DeployHookResponse": { "type": "object", "properties": { "branch": { "$ref": "#/components/schemas/builds_branch" }, "created_on": { "$ref": "#/components/schemas/builds_created_on" }, "deploy_hook_name": { "$ref": "#/components/schemas/builds_deploy_hook_name" }, "deploy_hook_uuid": { "$ref": "#/components/schemas/builds_deploy_hook_uuid" }, "external_script_id": { "$ref": "#/components/schemas/builds_external_script_id" }, "modified_on": { "$ref": "#/components/schemas/builds_modified_on" } } }, "builds_DetailedDeployHookResponse": { "type": "object", "properties": { "branch": { "$ref": "#/components/schemas/builds_branch" }, "created_on": { "$ref": "#/components/schemas/builds_created_on" }, "deploy_hook_name": { "$ref": "#/components/schemas/builds_deploy_hook_name" }, "deploy_hook_uuid": { "$ref": "#/components/schemas/builds_deploy_hook_uuid" }, "external_script_id": { "$ref": "#/components/schemas/builds_external_script_id" }, "latest_build": { "type": "object", "nullable": true, "properties": { "created_on": { "$ref": "#/components/schemas/builds_created_on" } } }, "modified_on": { "$ref": "#/components/schemas/builds_modified_on" } } }, "builds_EnvironmentVariablesRequest": { "description": "Map of environment-variable names to build-time values. Names must begin with a letter or underscore and contain only letters, numbers, and underscores.", "type": "object", "example": { "API_KEY": { "is_secret": true, "value": "secret-key" }, "NODE_ENV": { "is_secret": false, "value": "production" } }, "additionalProperties": { "properties": { "is_secret": { "$ref": "#/components/schemas/builds_is_secret" }, "value": { "description": "Value made available to the build. Maximum length is 5000 characters.", "type": "string", "example": "production", "maxLength": 5000 } }, "required": [ "is_secret", "value" ], "type": "object" } }, "builds_EnvironmentVariablesResponse": { "type": "object", "example": { "API_KEY": { "created_on": "2023-01-01T00:00:00Z", "is_secret": true, "value": null }, "NODE_ENV": { "created_on": "2023-01-01T00:00:00Z", "is_secret": false, "value": "production" } }, "additionalProperties": { "properties": { "created_on": { "$ref": "#/components/schemas/builds_created_on" }, "is_secret": { "$ref": "#/components/schemas/builds_is_secret" }, "value": { "description": "Value is null for secret environment variables", "type": "string", "nullable": true } }, "required": [ "is_secret", "created_on" ], "type": "object" } }, "builds_ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "example": 12000 }, "message": { "type": "string", "example": "Not found" } }, "required": [ "message" ], "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "example": false } }, "required": [ "success", "errors", "messages", "result" ] }, "builds_GetAccountLimitResponse": { "type": "object", "properties": { "build_minutes_refresh_on": { "description": "When build minutes will refresh (only for non-paid plans)", "type": "string", "format": "date-time", "nullable": true }, "has_reached_build_minutes_limit": { "description": "Whether build minutes limit has been reached (only for non-paid plans)", "type": "boolean", "nullable": true } } }, "builds_InsertBuildResponse": { "type": "object", "properties": { "build_uuid": { "$ref": "#/components/schemas/builds_build_uuid" }, "created_on": { "$ref": "#/components/schemas/builds_created_on" } } }, "builds_LatestBuildsResponse": { "type": "object", "properties": { "builds": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/builds_BuildResponse" } } } }, "builds_ListTokensResponse": { "type": "object", "properties": { "build_token_name": { "$ref": "#/components/schemas/builds_build_token_name" }, "build_token_uuid": { "$ref": "#/components/schemas/builds_build_token_uuid" }, "cloudflare_token_id": { "$ref": "#/components/schemas/builds_cloudflare_token_id" }, "owner_type": { "$ref": "#/components/schemas/builds_owner_type" } } }, "builds_PackageManager": { "type": "string", "example": "npm", "enum": [ "npm", "yarn", "pnpm", "bun", "uv" ] }, "builds_PaginationInfo": { "type": "object", "properties": { "count": { "type": "integer", "example": 25 }, "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total_count": { "type": "integer", "example": 150 }, "total_pages": { "type": "integer", "example": 3 } } }, "builds_SCMProviderType": { "description": "Source control provider.", "type": "string", "example": "github", "enum": [ "github", "gitlab", "gitlab_internal", "origin" ] }, "builds_TriggerDeployHookResponse": { "type": "object", "properties": { "already_exists": { "description": "True if a pending build already exists for this branch", "type": "boolean", "example": false }, "build_uuid": { "$ref": "#/components/schemas/builds_build_uuid" }, "created_on": { "$ref": "#/components/schemas/builds_created_on" }, "status": { "$ref": "#/components/schemas/builds_BuildStatus" } } }, "builds_TriggerResponse": { "type": "object", "properties": { "branch_excludes": { "$ref": "#/components/schemas/builds_branch_excludes" }, "branch_includes": { "$ref": "#/components/schemas/builds_branch_includes" }, "build_caching_enabled": { "$ref": "#/components/schemas/builds_build_caching_enabled" }, "build_command": { "$ref": "#/components/schemas/builds_build_command" }, "build_token_name": { "$ref": "#/components/schemas/builds_build_token_name" }, "build_token_uuid": { "$ref": "#/components/schemas/builds_build_token_uuid" }, "created_on": { "$ref": "#/components/schemas/builds_created_on" }, "deleted_on": { "$ref": "#/components/schemas/builds_deleted_on" }, "deploy_command": { "$ref": "#/components/schemas/builds_deploy_command" }, "external_script_id": { "$ref": "#/components/schemas/builds_external_script_id" }, "modified_on": { "$ref": "#/components/schemas/builds_modified_on" }, "path_excludes": { "$ref": "#/components/schemas/builds_path_excludes" }, "path_includes": { "$ref": "#/components/schemas/builds_path_includes" }, "repo_connection": { "$ref": "#/components/schemas/builds_UpsertRepoConnectionResponse" }, "root_directory": { "$ref": "#/components/schemas/builds_root_directory" }, "trigger_name": { "$ref": "#/components/schemas/builds_trigger_name" }, "trigger_uuid": { "$ref": "#/components/schemas/builds_trigger_uuid" } } }, "builds_UpdateTriggerRequest": { "type": "object", "properties": { "branch_excludes": { "$ref": "#/components/schemas/builds_branch_excludes" }, "branch_includes": { "$ref": "#/components/schemas/builds_branch_includes" }, "build_caching_enabled": { "$ref": "#/components/schemas/builds_build_caching_enabled" }, "build_command": { "$ref": "#/components/schemas/builds_build_command" }, "build_token_uuid": { "$ref": "#/components/schemas/builds_build_token_uuid" }, "deploy_command": { "$ref": "#/components/schemas/builds_deploy_command" }, "path_excludes": { "$ref": "#/components/schemas/builds_path_excludes" }, "path_includes": { "$ref": "#/components/schemas/builds_path_includes" }, "root_directory": { "$ref": "#/components/schemas/builds_root_directory" }, "trigger_name": { "$ref": "#/components/schemas/builds_trigger_name" } } }, "builds_UpdateWorkerBuildSettingsInput": { "description": "Partial build settings for updating a Worker build configuration", "type": "object", "properties": { "build_caching_enabled": { "$ref": "#/components/schemas/builds_build_caching_enabled" }, "build_command": { "$ref": "#/components/schemas/builds_build_command" }, "build_token_uuid": { "$ref": "#/components/schemas/builds_build_token_uuid" }, "deploy_command": { "$ref": "#/components/schemas/builds_deploy_command" }, "environment_variables": { "description": "Environment variable updates. Set the variable entry to null to delete it.", "type": "object", "additionalProperties": { "nullable": true, "properties": { "is_secret": { "$ref": "#/components/schemas/builds_is_secret" }, "value": { "description": "Value made available to the build. Maximum length is 5000 characters.", "type": "string", "maxLength": 5000 } }, "required": [ "is_secret", "value" ], "type": "object" } }, "path_excludes": { "$ref": "#/components/schemas/builds_path_excludes" }, "path_includes": { "$ref": "#/components/schemas/builds_path_includes" }, "root_directory": { "$ref": "#/components/schemas/builds_root_directory" } }, "minProperties": 1 }, "builds_UpdateWorkerRequest": { "description": "Request body for updating a Worker build configuration. At least one field must be provided.", "type": "object", "properties": { "git_repository": { "description": "Git repository settings to update", "type": "object", "minProperties": 1, "properties": { "branch": { "description": "New git branch to watch for builds", "type": "string", "example": "main", "maxLength": 256, "minLength": 1 } } }, "production_settings": { "$ref": "#/components/schemas/builds_UpdateWorkerBuildSettingsInput" } }, "minProperties": 1 }, "builds_UpsertRepoConnectionRequest": { "type": "object", "properties": { "provider_account_id": { "$ref": "#/components/schemas/builds_provider_account_id" }, "provider_account_name": { "$ref": "#/components/schemas/builds_provider_account_name" }, "provider_type": { "$ref": "#/components/schemas/builds_SCMProviderType" }, "repo_id": { "$ref": "#/components/schemas/builds_repo_id" }, "repo_name": { "$ref": "#/components/schemas/builds_repo_name" } }, "required": [ "repo_id", "repo_name", "provider_type", "provider_account_id", "provider_account_name" ] }, "builds_UpsertRepoConnectionResponse": { "type": "object", "properties": { "created_on": { "$ref": "#/components/schemas/builds_created_on" }, "deleted_on": { "$ref": "#/components/schemas/builds_deleted_on" }, "modified_on": { "$ref": "#/components/schemas/builds_modified_on" }, "provider_account_id": { "$ref": "#/components/schemas/builds_provider_account_id" }, "provider_account_name": { "$ref": "#/components/schemas/builds_provider_account_name" }, "provider_type": { "$ref": "#/components/schemas/builds_SCMProviderType" }, "repo_connection_uuid": { "$ref": "#/components/schemas/builds_repo_connection_uuid" }, "repo_id": { "$ref": "#/components/schemas/builds_repo_id" }, "repo_name": { "$ref": "#/components/schemas/builds_repo_name" } } }, "builds_WorkerBuildSettings": { "description": "Build and deploy settings for a Worker script environment", "type": "object", "properties": { "build_caching_enabled": { "$ref": "#/components/schemas/builds_build_caching_enabled" }, "build_command": { "$ref": "#/components/schemas/builds_build_command" }, "build_token_uuid": { "$ref": "#/components/schemas/builds_build_token_uuid" }, "deploy_command": { "$ref": "#/components/schemas/builds_deploy_command" }, "environment_variables": { "$ref": "#/components/schemas/builds_EnvironmentVariablesResponse" }, "path_excludes": { "$ref": "#/components/schemas/builds_path_excludes" }, "path_includes": { "$ref": "#/components/schemas/builds_path_includes" }, "root_directory": { "$ref": "#/components/schemas/builds_root_directory" } } }, "builds_WorkerGitRepository": { "description": "Git repository details linked to a Worker script build configuration", "type": "object", "properties": { "branch": { "description": "Git branch to watch for builds", "type": "string", "example": "main", "maxLength": 256, "minLength": 1 }, "grant_id": { "description": "Internal grant ID for GitLab internal integrations", "type": "string", "nullable": true }, "provider_account_id": { "$ref": "#/components/schemas/builds_provider_account_id" }, "provider_account_name": { "$ref": "#/components/schemas/builds_provider_account_name" }, "provider_type": { "$ref": "#/components/schemas/builds_SCMProviderType" }, "repo_id": { "$ref": "#/components/schemas/builds_repo_id" }, "repo_name": { "$ref": "#/components/schemas/builds_repo_name" } } }, "builds_WorkerResponse": { "description": "Worker build configuration including git repository linkage and production settings", "type": "object", "properties": { "git_repository": { "$ref": "#/components/schemas/builds_WorkerGitRepository" }, "production_settings": { "$ref": "#/components/schemas/builds_WorkerBuildSettings" }, "script_tag": { "$ref": "#/components/schemas/builds_external_script_id" } } }, "builds_account_id": { "description": "Account identifier.", "type": "string", "example": "account-123" }, "builds_branch": { "description": "Git branch name.", "type": "string", "example": "main" }, "builds_branch_excludes": { "description": "Branch patterns that must not start builds.", "type": "array", "items": { "type": "string" }, "example": [] }, "builds_branch_includes": { "description": "Branch patterns that can start builds.", "type": "array", "items": { "type": "string" }, "example": [ "main" ] }, "builds_build_caching_enabled": { "description": "Whether builds reuse cached dependencies and build artifacts.", "type": "boolean", "example": false, "default": false }, "builds_build_command": { "description": "Command to build the Worker.", "type": "string", "example": "npm run build" }, "builds_build_token_name": { "type": "string", "example": "My Build Token" }, "builds_build_token_uuid": { "description": "UUID of the build token used when deploying the Worker.", "type": "string", "format": "uuid" }, "builds_build_uuid": { "description": "Build UUID.", "type": "string", "format": "uuid" }, "builds_cloudflare_token_id": { "type": "string", "example": "cf-token-123" }, "builds_commit_hash": { "description": "Git commit hash", "type": "string", "example": "abc123def456" }, "builds_created_on": { "type": "string", "format": "date-time" }, "builds_cursor": { "description": "Pagination cursor for log retrieval.", "type": "string", "example": "eyJsaW5lIjoxMDAsInRpbWVzdGFtcCI6MTYzNjQ3MjQwMH0" }, "builds_deleted_on": { "type": "string", "format": "date-time", "nullable": true }, "builds_deploy_command": { "description": "Command to deploy the Worker.", "type": "string", "example": "npx wrangler deploy" }, "builds_deploy_hook_name": { "description": "Deploy hook name (1-58 characters).", "type": "string", "example": "Production Deploy Hook", "maxLength": 58, "minLength": 1 }, "builds_deploy_hook_uuid": { "description": "Deploy hook UUID.", "type": "string", "format": "uuid" }, "builds_environment_variable_key": { "description": "Environment variable key.", "type": "string", "example": "NODE_ENV" }, "builds_external_script_id": { "description": "System-generated tag of the Worker. This is not the Worker name.", "type": "string", "example": "dd7160bb9cef458093557736f4b9e75b" }, "builds_external_script_ids": { "description": "Comma-separated list of system-generated worker script tags (max 20).", "type": "string", "example": "dd7160bb9cef458093557736f4b9e75b,42fb14fe81df47139d3be684e4c637a6,ff7cf9a7582f4c0d90a4b95cb17d659e" }, "builds_is_secret": { "description": "Whether to hide the value after it is saved. Secret values remain available to builds but appear as `null` when you list variables; non-secret values remain visible.", "type": "boolean", "example": false }, "builds_modified_on": { "type": "string", "format": "date-time" }, "builds_owner_type": { "type": "string", "example": "user" }, "builds_path_excludes": { "description": "Path patterns that must not start builds.", "type": "array", "items": { "type": "string" }, "example": [ "*.md" ] }, "builds_path_includes": { "description": "Path patterns that can start builds.", "type": "array", "items": { "type": "string" }, "example": [ "*" ], "default": [ "*" ] }, "builds_provider_account_id": { "description": "Provider-specific identifier of the account or namespace that owns the repository.", "type": "string", "example": "cloudflare" }, "builds_provider_account_name": { "description": "Human-readable name of the account or namespace that owns the repository.", "type": "string", "example": "Cloudflare" }, "builds_repo_connection_uuid": { "description": "Repository connection UUID.", "type": "string", "format": "uuid" }, "builds_repo_id": { "description": "Provider-specific repository identifier.", "type": "string", "example": "workers-sdk" }, "builds_repo_name": { "description": "Human-readable repository name.", "type": "string", "example": "workers-sdk" }, "builds_root_directory": { "description": "Repository directory in which build and deploy commands run.", "type": "string", "example": "/" }, "builds_script_name": { "description": "Human-readable name of the Worker.", "type": "string", "example": "my-worker" }, "builds_stopped_on": { "type": "string", "format": "date-time", "nullable": true }, "builds_trigger_name": { "description": "Human-readable name of the build trigger.", "type": "string", "example": "Production Deploy" }, "builds_trigger_uuid": { "description": "Trigger UUID.", "type": "string", "format": "uuid" }, "builds_version_ids": { "description": "Comma-separated list of version UUIDs (max 20).", "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000,223e4567-e89b-12d3-a456-426614174001" }, "cache-purge_Everything": { "type": "object", "properties": { "purge_everything": { "description": "For more information, please refer to [purge everything documentation page](https://developers.cloudflare.com/cache/how-to/purge-cache/purge-everything/).", "type": "boolean", "example": true, "x-auditable": true } }, "title": "Purge everything" }, "cache-purge_FlexPurgeByHostnames": { "type": "object", "properties": { "hosts": { "description": "For more information purging by hostnames, please refer to [purge by hostname documentation page](https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-hostname/).", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "www.example.com", "images.example.com" ] } }, "title": "Purge by hostnames" }, "cache-purge_FlexPurgeByPrefixes": { "type": "object", "properties": { "prefixes": { "description": "For more information on purging by prefixes, please refer to [purge by prefix documentation page](https://developers.cloudflare.com/cache/how-to/purge-cache/purge_by_prefix/).", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "www.example.com/foo", "images.example.com/bar/baz" ] } }, "title": "Purge by prefixes" }, "cache-purge_FlexPurgeByTags": { "type": "object", "properties": { "tags": { "description": "For more information on cache tags and purging by tags, please refer to [purge by cache-tags documentation page](https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-tags/).", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "a-cache-tag", "another-cache-tag" ] } }, "title": "Purge by tags" }, "cache-purge_SingleFile": { "type": "object", "properties": { "files": { "description": "For more information on purging files, please refer to [purge by single-file documentation page](https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-single-file/).", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "http://www.example.com/css/styles.css", "http://www.example.com/js/index.js" ] } }, "title": "Purge files" }, "cache-purge_SingleFileWithUrlAndHeaders": { "type": "object", "properties": { "files": { "description": "For more information on purging files with URL and headers, please refer to [purge by single-file documentation page](https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-single-file/).", "type": "array", "items": { "properties": { "headers": { "type": "object", "example": { "CF-Device-Type": "desktop", "CF-IPCountry": "US" }, "additionalProperties": { "type": "string", "x-auditable": true } }, "url": { "type": "string", "example": "http://www.example.com/cat_picture.jpg", "x-auditable": true } }, "type": "object" }, "example": [ { "headers": { "Accept-Language": "zh-CN", "CF-Device-Type": "desktop", "CF-IPCountry": "US" }, "url": "http://www.example.com/cat_picture.jpg" }, { "headers": { "Accept-Language": "en-US", "CF-Device-Type": "mobile", "CF-IPCountry": "EU" }, "url": "http://www.example.com/dog_picture.jpg" } ] } }, "title": "Purge files with URL and headers" }, "cache-purge_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/cache-purge_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/cache-purge_messages" } ] }, "result": { "type": "object", "nullable": true }, "success": { "description": "Indicates the API call's success or failure.", "type": "boolean", "example": false } }, "required": [ "success", "errors", "messages", "result" ] }, "cache-purge_api-response-single-id": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/cache-purge_messages" }, "messages": { "$ref": "#/components/schemas/cache-purge_messages" }, "result": { "type": "object", "nullable": true, "properties": { "id": { "$ref": "#/components/schemas/cache-purge_identifier" } }, "required": [ "id" ] }, "success": { "description": "Indicates the API call's success or failure.", "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages" ] }, "cache-purge_identifier": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 }, "cache-purge_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "cache-rules_aegis": { "description": "Aegis provides dedicated egress IPs (from Cloudflare to your origin) for your layer 7 WAF and CDN services. The egress IPs are reserved exclusively for your account so that you can increase your origin security by only allowing traffic from a small list of IP addresses.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "aegis", "enum": [ "aegis" ], "x-auditable": true }, "value": { "$ref": "#/components/schemas/cache-rules_aegis_value" } }, "type": "object" } ], "title": "Aegis" }, "cache-rules_aegis_response_value": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/cache-rules_aegis" } } }, "cache-rules_aegis_value": { "description": "Value of the zone setting.", "type": "object", "properties": { "enabled": { "description": "Whether the feature is enabled or not.", "type": "boolean", "x-auditable": true }, "pool_id": { "description": "Egress pool id which refers to a grouping of dedicated egress IPs through which Cloudflare will connect to origin.", "type": "string", "example": "pool-id", "x-auditable": true } } }, "cache-rules_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/cache-rules_messages" }, "messages": { "$ref": "#/components/schemas/cache-rules_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "cache-rules_api-response-common-failure": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/cache-rules_messages" } ], "minLength": 1 }, "messages": { "type": "array", "items": { "type": "object" }, "example": [], "allOf": [ { "$ref": "#/components/schemas/cache-rules_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "cache-rules_base": { "type": "object", "properties": { "id": { "description": "Identifier of the zone setting.", "type": "string", "x-auditable": true }, "modified_on": { "description": "Last time this setting was modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "nullable": true, "readOnly": true, "x-auditable": true } }, "required": [ "id" ] }, "cache-rules_cache_reserve": { "description": "Increase cache lifetimes by automatically storing all cacheable files into Cloudflare's persistent object storage buckets. Requires Cache Reserve subscription. Note: using Tiered Cache with Cache Reserve is highly recommended to reduce Reserve operations costs. See the [developer docs](https://developers.cloudflare.com/cache/about/cache-reserve) for more information.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "cache_reserve", "enum": [ "cache_reserve" ], "x-auditable": true } }, "type": "object" } ], "title": "Cache Reserve" }, "cache-rules_cache_reserve_clear": { "description": "You can use Cache Reserve Clear to clear your Cache Reserve, but you must first disable Cache Reserve. In most cases, this will be accomplished within 24 hours. You cannot re-enable Cache Reserve while this process is ongoing. Keep in mind that you cannot undo or cancel this operation.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "cache_reserve_clear", "enum": [ "cache_reserve_clear" ], "x-auditable": true } }, "type": "object" } ], "title": "Cache Reserve Clear" }, "cache-rules_cache_reserve_clear_end_ts": { "description": "The time that the latest Cache Reserve Clear operation completed.", "type": "string", "format": "date-time", "example": "2023-10-02T12:00:00.12345Z", "x-auditable": true }, "cache-rules_cache_reserve_clear_response_value": { "type": "object", "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_cache_reserve_clear" }, { "properties": { "end_ts": { "$ref": "#/components/schemas/cache-rules_cache_reserve_clear_end_ts" }, "start_ts": { "$ref": "#/components/schemas/cache-rules_cache_reserve_clear_start_ts" }, "state": { "$ref": "#/components/schemas/cache-rules_cache_reserve_clear_state" } }, "required": [ "state", "start_ts" ], "type": "object" } ] } } }, "cache-rules_cache_reserve_clear_start_ts": { "description": "The time that the latest Cache Reserve Clear operation started.", "type": "string", "format": "date-time", "example": "2023-10-02T10:00:00.12345Z", "x-auditable": true }, "cache-rules_cache_reserve_clear_state": { "description": "The current state of the Cache Reserve Clear operation.", "type": "string", "example": "In-progress", "enum": [ "In-progress", "Completed" ], "x-auditable": true }, "cache-rules_cache_reserve_response_value": { "type": "object", "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_cache_reserve" }, { "properties": { "value": { "$ref": "#/components/schemas/cache-rules_cache_reserve_value" } }, "required": [ "value" ], "type": "object" } ] } } }, "cache-rules_cache_reserve_value": { "description": "Value of the Cache Reserve zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ], "x-auditable": true }, "cache-rules_editable": { "description": "Whether the setting is editable.", "type": "boolean", "x-auditable": true }, "cache-rules_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "cache-rules_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "cache-rules_modified_on": { "description": "The time when the setting was last modified.", "type": "string", "format": "date-time", "x-auditable": true }, "cache-rules_origin_cloud_region_batch_item_result": { "description": "Result for a single item in a batch operation.", "type": "object", "properties": { "error": { "description": "Error message explaining why the item failed. Present only on failed items.", "type": "string" }, "origin-ip": { "description": "The origin IP address for this item.", "type": "string", "example": "192.0.2.1" }, "region": { "description": "Cloud vendor region identifier. Present on succeeded items for patch operations.", "type": "string", "example": "us-east-1" }, "vendor": { "description": "Cloud vendor identifier. Present on succeeded items for patch operations.", "type": "string", "example": "aws" } }, "required": [ "origin-ip" ] }, "cache-rules_origin_cloud_region_batch_result": { "description": "Response result for a batch origin cloud region operation.", "type": "object", "properties": { "editable": { "description": "Whether the setting can be modified by the current user.", "type": "boolean" }, "id": { "type": "string", "example": "origin_public_cloud_region", "enum": [ "origin_public_cloud_region" ], "x-auditable": true }, "modified_on": { "description": "Time the mapping set was last modified. Null when no items were successfully applied.", "type": "string", "format": "date-time", "nullable": true, "x-auditable": true }, "value": { "type": "object", "properties": { "failed": { "description": "Items that could not be applied, with error details.", "items": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_batch_item_result" }, "type": "array" }, "succeeded": { "description": "Items that were successfully applied.", "items": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_batch_item_result" }, "type": "array" } }, "required": [ "succeeded", "failed" ] } }, "required": [ "id", "editable", "value" ] }, "cache-rules_origin_cloud_region_entry": { "description": "A single origin IP-to-cloud-region mapping.", "type": "object", "properties": { "modified_on": { "description": "Time this mapping was last modified.", "type": "string", "format": "date-time", "x-auditable": true }, "origin-ip": { "description": "The origin IP address (IPv4 or IPv6, canonicalized).", "type": "string", "example": "192.0.2.1", "x-auditable": true }, "region": { "description": "Cloud vendor region identifier.", "type": "string", "example": "us-east-1", "x-auditable": true }, "vendor": { "description": "Cloud vendor hosting the origin.", "type": "string", "example": "aws", "enum": [ "aws", "azure", "gcp", "oci" ], "x-auditable": true } }, "required": [ "origin-ip", "vendor", "region" ] }, "cache-rules_origin_cloud_region_request": { "description": "Request body for creating or updating an origin cloud region mapping.", "type": "object", "properties": { "ip": { "description": "Origin IP address (IPv4 or IPv6). Normalized to canonical form before storage (RFC 5952 for IPv6).", "type": "string", "example": "192.0.2.1", "x-auditable": true }, "region": { "description": "Cloud vendor region identifier. Must be a valid region for the specified vendor as returned by the supported_regions endpoint.", "type": "string", "example": "us-east-1", "x-auditable": true }, "vendor": { "description": "Cloud vendor hosting the origin. Must be one of the supported vendors.", "type": "string", "example": "aws", "enum": [ "aws", "azure", "gcp", "oci" ], "x-auditable": true } }, "required": [ "ip", "vendor", "region" ] }, "cache-rules_origin_cloud_region_single_result": { "description": "Response result for a single origin cloud region mapping.", "type": "object", "properties": { "editable": { "description": "Whether the setting can be modified by the current user.", "type": "boolean" }, "id": { "type": "string", "example": "origin_public_cloud_region", "enum": [ "origin_public_cloud_region" ], "x-auditable": true }, "modified_on": { "description": "Time the mapping was last modified.", "type": "string", "format": "date-time", "x-auditable": true }, "value": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_entry" } }, "required": [ "id", "editable", "value" ] }, "cache-rules_origin_cloud_region_v2_batch_item_result": { "description": "Result for a single item in a batch operation.", "type": "object", "properties": { "error": { "description": "Error message explaining why the item failed. Present only on failed items.", "type": "string" }, "origin_ip": { "description": "The origin IP address for this item.", "type": "string", "example": "192.0.2.1" }, "region": { "description": "Cloud vendor region identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).", "type": "string", "example": "us-east-1" }, "vendor": { "description": "Cloud vendor identifier. Present on succeeded items (the new value for upsert, the deleted value for delete).", "type": "string", "example": "aws" } }, "required": [ "origin_ip" ] }, "cache-rules_origin_cloud_region_v2_batch_result": { "description": "Response result for a batch origin cloud region operation.", "type": "object", "properties": { "failed": { "description": "Items that could not be applied, with error details.", "type": "array", "items": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_v2_batch_item_result" } }, "succeeded": { "description": "Items that were successfully applied.", "type": "array", "items": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_v2_batch_item_result" } } }, "required": [ "succeeded", "failed" ] }, "cache-rules_origin_cloud_region_v2_delete_result": { "description": "Response result for a delete operation. Identifies the deleted mapping.", "type": "object", "properties": { "origin_ip": { "description": "The origin IP address whose mapping was deleted.", "type": "string", "example": "192.0.2.1", "x-auditable": true } }, "required": [ "origin_ip" ] }, "cache-rules_origin_cloud_region_v2_entry": { "description": "A single origin IP-to-cloud-region mapping.", "type": "object", "properties": { "modified_on": { "description": "Time this mapping was last modified.", "type": "string", "format": "date-time", "x-auditable": true }, "origin_ip": { "description": "The origin IP address (IPv4 or IPv6). Normalized to canonical form (RFC 5952 for IPv6).", "type": "string", "example": "192.0.2.1", "x-auditable": true }, "region": { "description": "Cloud vendor region identifier.", "type": "string", "example": "us-east-1", "x-auditable": true }, "vendor": { "description": "Cloud vendor hosting the origin.", "type": "string", "example": "aws", "enum": [ "aws", "azure", "gcp", "oci" ], "x-auditable": true } }, "required": [ "origin_ip", "vendor", "region" ] }, "cache-rules_origin_cloud_region_v2_request": { "description": "Request body for creating or replacing an origin cloud region mapping.", "type": "object", "properties": { "origin_ip": { "description": "Origin IP address (IPv4 or IPv6). For the single PUT endpoint (`PUT /origin/cloud_regions/{origin_ip}`), this field must match the path parameter or the request will be rejected with a 400 error. For the batch PUT endpoint, this field identifies which mapping to upsert.", "type": "string", "example": "192.0.2.1", "x-auditable": true }, "region": { "description": "Cloud vendor region identifier. Must be a valid region for the specified vendor as returned by the supported_regions endpoint.", "type": "string", "example": "us-east-1", "x-auditable": true }, "vendor": { "description": "Cloud vendor hosting the origin. Must be one of the supported vendors.", "type": "string", "example": "aws", "enum": [ "aws", "azure", "gcp", "oci" ], "x-auditable": true } }, "required": [ "origin_ip", "vendor", "region" ] }, "cache-rules_origin_cloud_region_v2_result_info": { "description": "Pagination metadata for list responses.", "type": "object", "properties": { "count": { "description": "Number of items returned in this response.", "type": "integer", "example": 2 }, "page": { "description": "Current page number.", "type": "integer", "example": 1 }, "per_page": { "description": "Number of items per page.", "type": "integer", "example": 20 }, "total_count": { "description": "Total number of mappings configured for the zone.", "type": "integer", "example": 2 }, "total_pages": { "description": "Total number of pages.", "type": "integer", "example": 1 } }, "required": [ "page", "per_page", "count", "total_count", "total_pages" ] }, "cache-rules_origin_cloud_regions_list_result": { "description": "Response result for a list of origin cloud region mappings.", "type": "object", "properties": { "editable": { "description": "Whether the setting can be modified by the current user.", "type": "boolean" }, "id": { "type": "string", "example": "origin_public_cloud_region", "enum": [ "origin_public_cloud_region" ], "x-auditable": true }, "modified_on": { "description": "Time the mapping set was last modified. Null when no mappings exist.", "type": "string", "format": "date-time", "nullable": true, "x-auditable": true }, "value": { "type": "array", "items": { "$ref": "#/components/schemas/cache-rules_origin_cloud_region_entry" } } }, "required": [ "id", "editable", "value" ] }, "cache-rules_origin_h2_max_streams": { "description": "Origin H2 Max Streams configures the max number of concurrent requests that Cloudflare will send within the same connection when communicating with the origin server, if the origin supports it. Note that if your origin does not support H2 multiplexing, 5xx errors may be observed, particularly 520s. Also note that the default value is `100` for all plan types except Enterprise where it is `1`. `1` means that H2 multiplexing is disabled.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_base" }, { "properties": { "id": { "description": "Value of the zone setting.", "type": "string", "example": "origin_h2_max_streams", "enum": [ "origin_h2_max_streams" ], "x-auditable": true }, "value": { "$ref": "#/components/schemas/cache-rules_origin_h2_max_streams_value" } }, "type": "object" } ], "title": "Origin H2 Max Streams" }, "cache-rules_origin_h2_max_streams_response_value": { "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_origin_h2_max_streams" } }, "type": "object" } ] }, "cache-rules_origin_h2_max_streams_value": { "description": "Value of the Origin H2 Max Streams Setting.", "type": "integer", "example": 50, "maximum": 1000, "minimum": 1, "x-auditable": true }, "cache-rules_origin_max_http_version": { "description": "Origin Max HTTP Setting Version sets the highest HTTP version Cloudflare will attempt to use with your origin. This setting allows Cloudflare to make HTTP/2 requests to your origin. (Refer to [Enable HTTP/2 to Origin](https://developers.cloudflare.com/cache/how-to/enable-http2-to-origin/), for more information.). The default value is \"2\" for all plan types except Enterprise where it is \"1\".", "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_base" }, { "properties": { "id": { "description": "Value of the zone setting.", "type": "string", "example": "origin_max_http_version", "enum": [ "origin_max_http_version" ], "x-auditable": true }, "value": { "$ref": "#/components/schemas/cache-rules_origin_max_http_version_value" } }, "type": "object" } ], "title": "Origin Max HTTP Version" }, "cache-rules_origin_max_http_version_response_value": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/cache-rules_origin_max_http_version" } } }, "cache-rules_origin_max_http_version_value": { "description": "Value of the Origin Max HTTP Version Setting.", "type": "string", "enum": [ "2", "1" ], "x-auditable": true }, "cache-rules_origin_post_quantum_encryption": { "description": "Instructs Cloudflare to use Post-Quantum (PQ) key agreement algorithms when connecting to your origin. Preferred instructs Cloudflare to opportunistically send a Post-Quantum keyshare in the first message to the origin (for fastest connections when the origin supports and prefers PQ), supported means that PQ algorithms are advertised but only used when requested by the origin, and off means that PQ algorithms are not advertised.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_base" }, { "properties": { "id": { "description": "Value of the zone setting.", "type": "string", "example": "origin_pqe", "enum": [ "origin_pqe" ], "x-auditable": true } }, "type": "object" } ], "title": "Origin Post-Quantum Encryption" }, "cache-rules_origin_post_quantum_encryption_response_value": { "type": "object", "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_origin_post_quantum_encryption" }, { "properties": { "value": { "$ref": "#/components/schemas/cache-rules_origin_post_quantum_encryption_value" } }, "required": [ "value" ], "type": "object" } ] } } }, "cache-rules_origin_post_quantum_encryption_value": { "description": "Value of the Origin Post Quantum Encryption Setting.", "type": "string", "default": "supported", "enum": [ "preferred", "supported", "off" ], "x-auditable": true }, "cache-rules_origin_tls_compliance_modes": { "description": "Origin TLS Compliance Modes constrains the set of TLS key-exchange algorithms Cloudflare may use when establishing the TLS connection to the zone's origin. The value is a list of named compliance modes (currently `fips` and `pqh`). Multiple modes are combined as the intersection of their permitted algorithm lists.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "origin_tls_compliance_modes", "enum": [ "origin_tls_compliance_modes" ], "x-auditable": true } }, "type": "object" } ], "title": "Origin TLS Compliance Modes" }, "cache-rules_origin_tls_compliance_modes_response_value": { "type": "object", "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_origin_tls_compliance_modes" }, { "properties": { "value": { "$ref": "#/components/schemas/cache-rules_origin_tls_compliance_modes_value" } }, "required": [ "value" ], "type": "object" } ] } } }, "cache-rules_origin_tls_compliance_modes_value": { "description": "List of TLS compliance modes that constrain the key-exchange algorithms Cloudflare may use when establishing the TLS connection to the zone's origin. Currently supported values are `fips` (FIPS-approved curves) and `pqh` (post-quantum hybrid). Future modes (e.g. `cnsa2`) may be added; clients should treat unknown values as opaque strings. Multiple modes are combined as the intersection of their permitted algorithm lists; selections whose intersection is empty are rejected. An empty list clears the constraint.", "type": "array", "items": { "maxLength": 64, "type": "string", "x-auditable": true }, "example": [ "fips", "pqh" ], "maxItems": 20, "uniqueItems": true, "x-auditable": true }, "cache-rules_patch": { "description": "Update enablement of Tiered Caching.", "type": "object", "properties": { "value": { "$ref": "#/components/schemas/cache-rules_value" } }, "required": [ "value" ] }, "cache-rules_regional_tiered_cache": { "description": "Instructs Cloudflare to check a regional hub data center on the way to your upper tier. This can help improve performance for smart and custom tiered cache topologies.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "tc_regional", "enum": [ "tc_regional" ], "x-auditable": true } }, "type": "object" } ], "title": "Regional Tiered Cache" }, "cache-rules_regional_tiered_cache_response_value": { "type": "object", "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_regional_tiered_cache" }, { "properties": { "value": { "$ref": "#/components/schemas/cache-rules_regional_tiered_cache_value" } }, "required": [ "value" ], "type": "object" } ] } } }, "cache-rules_regional_tiered_cache_value": { "description": "Value of the Regional Tiered Cache zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ], "x-auditable": true }, "cache-rules_result-object": { "type": "object", "properties": { "editable": { "$ref": "#/components/schemas/cache-rules_editable" }, "id": { "$ref": "#/components/schemas/cache-rules_setting_id" }, "modified_on": { "$ref": "#/components/schemas/cache-rules_modified_on" }, "value": { "$ref": "#/components/schemas/cache-rules_setting_value" } }, "required": [ "id", "value", "editable" ] }, "cache-rules_result-object-delete": { "type": "object", "properties": { "editable": { "$ref": "#/components/schemas/cache-rules_editable" }, "id": { "$ref": "#/components/schemas/cache-rules_setting_id" }, "modified_on": { "$ref": "#/components/schemas/cache-rules_modified_on" } }, "required": [ "id", "editable" ] }, "cache-rules_setting_id": { "description": "The identifier of the caching setting.", "type": "string", "x-auditable": true }, "cache-rules_setting_value": { "description": "The value of the setting.", "type": "string", "x-auditable": true }, "cache-rules_smart_tiered_cache": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "tiered_cache_smart_topology_enable", "enum": [ "tiered_cache_smart_topology_enable" ], "x-auditable": true } }, "type": "object" } ], "title": "Smart Tiered Cache" }, "cache-rules_smart_tiered_cache_patch": { "description": "Update enablement of Smart Tiered Cache.", "type": "object", "properties": { "value": { "description": "Enable or disable the Smart Tiered Cache.", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "required": [ "value" ] }, "cache-rules_smart_tiered_cache_response_value": { "type": "object", "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_smart_tiered_cache" }, { "properties": { "value": { "$ref": "#/components/schemas/cache-rules_smart_tiered_cache_value" } }, "required": [ "value" ], "type": "object" } ] } } }, "cache-rules_smart_tiered_cache_value": { "description": "Value of the Smart Tiered Cache zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ], "x-auditable": true }, "cache-rules_supported_cloud_region": { "description": "A single supported cloud region with associated Tiered Cache upper-tier colocations.", "type": "object", "properties": { "name": { "description": "Cloud vendor region identifier.", "type": "string", "example": "us-east-1" }, "upper_tier_colos": { "description": "Cloudflare Tiered Cache upper-tier colocation codes co-located with this cloud region. Requests from zones with a matching origin mapping will be routed through these colos.", "type": "array", "items": { "type": "string" }, "example": [ "IAD", "EWR" ] } }, "required": [ "name", "upper_tier_colos" ] }, "cache-rules_supported_cloud_regions_result": { "description": "Cloud vendors and their supported regions for origin cloud region mappings.", "type": "object", "properties": { "obtained_codes": { "description": "Whether Cloudflare airport codes (IATA colo identifiers) were successfully resolved for the `upper_tier_colos` field on each region. When `false`, the `upper_tier_colos` arrays may be empty or incomplete.", "type": "boolean" }, "vendors": { "description": "Map of vendor name to list of supported regions.", "type": "object", "additionalProperties": { "items": { "$ref": "#/components/schemas/cache-rules_supported_cloud_region" }, "type": "array" } } }, "required": [ "vendors", "obtained_codes" ] }, "cache-rules_tiered_cache": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "tiered_caching", "enum": [ "tiered_caching" ], "x-auditable": true } }, "type": "object" } ], "title": "Tiered Cache" }, "cache-rules_tiered_cache_response_value": { "type": "object", "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_tiered_cache" }, { "properties": { "value": { "$ref": "#/components/schemas/cache-rules_tiered_cache_value" } }, "required": [ "value" ], "type": "object" } ] } } }, "cache-rules_tiered_cache_value": { "description": "Value of the Tiered Cache zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ], "x-auditable": true }, "cache-rules_value": { "description": "Enables Tiered Caching.", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true }, "cache-rules_variants": { "description": "Variant support enables caching variants of images with certain file extensions in addition to the original. This only applies when the origin server sends the 'Vary: Accept' response header. If the origin server sends 'Vary: Accept' but does not serve the variant requested, the response will not be cached. This will be indicated with BYPASS cache status in the response headers.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "variants", "enum": [ "variants" ], "x-auditable": true } }, "type": "object" } ], "title": "Variants Caching" }, "cache-rules_variants_response_value": { "type": "object", "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_variants" }, { "properties": { "value": { "$ref": "#/components/schemas/cache-rules_variants_value" } }, "required": [ "value" ], "type": "object" } ] } } }, "cache-rules_variants_value": { "description": "Value of the zone setting.", "type": "object", "properties": { "avif": { "description": "List of strings with the MIME types of all the variants that should be served for avif.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "image/webp", "image/jpeg" ], "uniqueItems": true }, "bmp": { "description": "List of strings with the MIME types of all the variants that should be served for bmp.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "image/webp", "image/jpeg" ], "uniqueItems": true }, "gif": { "description": "List of strings with the MIME types of all the variants that should be served for gif.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "image/webp", "image/jpeg" ], "uniqueItems": true }, "jp2": { "description": "List of strings with the MIME types of all the variants that should be served for jp2.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "image/webp", "image/avif" ], "uniqueItems": true }, "jpeg": { "description": "List of strings with the MIME types of all the variants that should be served for jpeg.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "image/webp", "image/avif" ], "uniqueItems": true }, "jpg": { "description": "List of strings with the MIME types of all the variants that should be served for jpg.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "image/webp", "image/avif" ], "uniqueItems": true }, "jpg2": { "description": "List of strings with the MIME types of all the variants that should be served for jpg2.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "image/webp", "image/avif" ], "uniqueItems": true }, "png": { "description": "List of strings with the MIME types of all the variants that should be served for png.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "image/webp", "image/avif" ], "uniqueItems": true }, "tif": { "description": "List of strings with the MIME types of all the variants that should be served for tif.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "image/webp", "image/avif" ], "uniqueItems": true }, "tiff": { "description": "List of strings with the MIME types of all the variants that should be served for tiff.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "image/webp", "image/avif" ], "uniqueItems": true }, "webp": { "description": "List of strings with the MIME types of all the variants that should be served for webp.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "image/jpeg", "image/avif" ], "uniqueItems": true } } }, "cache-rules_zone_cache_settings_delete_response_single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_result-object-delete" } }, "type": "object" } ] }, "cache-rules_zone_cache_settings_response_single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cache-rules_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/cache-rules_result-object" } }, "type": "object" } ] }, "cache_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/cache_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/cache_messages" } ] }, "result": { "$ref": "#/components/schemas/cache_result" }, "success": { "description": "Indicates the API call's success or failure.", "type": "boolean", "example": false } }, "required": [ "success", "errors", "messages", "result" ] }, "cache_api-response-single-id": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/cache_messages" }, "messages": { "$ref": "#/components/schemas/cache_messages" }, "result": { "$ref": "#/components/schemas/cache_result" }, "success": { "description": "Indicates the API call's success or failure.", "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages", "result" ] }, "cache_auto_origin_tls_kex_failure_response": { "type": "object", "properties": { "errors": { "allOf": [ { "$ref": "#/components/schemas/cache_messages" } ], "minLength": 1 }, "messages": { "$ref": "#/components/schemas/cache_messages" }, "result": { "$ref": "#/components/schemas/cache_auto_origin_tls_kex_result" }, "success": { "description": "Indicates the API call's success or failure.", "type": "boolean", "example": false } }, "required": [ "success", "errors", "messages", "result" ] }, "cache_auto_origin_tls_kex_patch": { "description": "Update enablement of Auto-Origin TLS KEX selection.", "type": "object", "properties": { "enabled": { "$ref": "#/components/schemas/cache_auto_origin_tls_kex_value" } }, "required": [ "enabled" ] }, "cache_auto_origin_tls_kex_response": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/cache_messages" }, "messages": { "$ref": "#/components/schemas/cache_messages" }, "result": { "$ref": "#/components/schemas/cache_auto_origin_tls_kex_result" }, "success": { "description": "Indicates the API call's success or failure.", "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages", "result" ] }, "cache_auto_origin_tls_kex_result": { "type": "object", "properties": { "enabled": { "description": "Whether Auto-Origin TLS KEX selection is enabled for the zone.", "allOf": [ { "$ref": "#/components/schemas/cache_auto_origin_tls_kex_value" } ], "readOnly": true }, "id": { "type": "string", "example": "auto_origin_tls_kex", "readOnly": true }, "modified_on": { "description": "Last time this setting was modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true } }, "required": [ "id", "enabled", "modified_on" ] }, "cache_auto_origin_tls_kex_value": { "description": "Controls enablement of Auto-Origin TLS KEX selection for the zone.", "type": "boolean", "example": true }, "cache_identifier": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 }, "cache_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "cache_result": { "type": "object", "properties": { "editable": { "description": "Whether this setting can be updated or not.", "type": "boolean", "readOnly": true }, "id": { "type": "string", "example": "ssl_automatic_mode", "readOnly": true }, "modified_on": { "description": "Last time this setting was modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true }, "next_scheduled_scan": { "description": "Next time this zone will be scanned by the Automatic SSL/TLS.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "nullable": true, "readOnly": true }, "value": { "description": "Current setting of the automatic SSL/TLS.", "type": "string", "example": "auto", "enum": [ "auto", "custom" ], "readOnly": true } }, "required": [ "id", "modified_on", "value", "editable" ] }, "cache_schemas_patch": { "description": "Update enablement of Automatic SSL/TLS.", "type": "object", "properties": { "value": { "$ref": "#/components/schemas/cache_schemas_value" } }, "required": [ "value" ] }, "cache_schemas_value": { "description": "Controls enablement of Automatic SSL/TLS.", "type": "string", "example": "auto", "enum": [ "auto", "custom" ] }, "calls_account_identifier": { "description": "The account identifier tag.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "calls_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/calls_messages" }, "messages": { "$ref": "#/components/schemas/calls_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "calls_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/calls_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/calls_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "calls_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/calls_api-response-common" } ] }, "calls_app": { "type": "object", "properties": { "created": { "$ref": "#/components/schemas/calls_created" }, "modified": { "$ref": "#/components/schemas/calls_modified" }, "name": { "$ref": "#/components/schemas/calls_name" }, "uid": { "$ref": "#/components/schemas/calls_identifier" } }, "required": [ "uid", "name", "created", "modified" ] }, "calls_app_editable_fields": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/calls_name" } } }, "calls_app_response_collection": { "allOf": [ { "$ref": "#/components/schemas/calls_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/calls_app" } } }, "type": "object" } ] }, "calls_app_response_single": { "allOf": [ { "$ref": "#/components/schemas/calls_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/calls_app" } }, "type": "object" } ] }, "calls_app_response_single_with_secret": { "allOf": [ { "$ref": "#/components/schemas/calls_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/calls_app_with_secret" } }, "type": "object" } ] }, "calls_app_with_secret": { "type": "object", "properties": { "created": { "$ref": "#/components/schemas/calls_created" }, "modified": { "$ref": "#/components/schemas/calls_modified" }, "name": { "$ref": "#/components/schemas/calls_name" }, "secret": { "$ref": "#/components/schemas/calls_secret" }, "uid": { "$ref": "#/components/schemas/calls_identifier" } }, "required": [ "uid", "name", "secret", "created", "modified" ] }, "calls_created": { "description": "The date and time the item was created.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z" }, "calls_identifier": { "description": "A Cloudflare-generated unique identifier for a item.", "type": "string", "example": "2a95132c15732412d22c1476fa83f27a", "maxLength": 32, "minLength": 32, "x-auditable": true }, "calls_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "calls_modified": { "description": "The date and time the item was last modified.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z" }, "calls_name": { "description": "A short description of Calls app, not shown to end users.", "type": "string", "example": "production-realtime-app", "default": "", "x-auditable": true }, "calls_secret": { "description": "Bearer token", "type": "string", "example": "66bcf64aa8907b9f9d90ac17746a77ce394c393b92b3916633dc02846e608ad4", "maxLength": 64, "minLength": 64, "x-sensitive": true }, "calls_turn_key": { "description": "Bearer token", "type": "string", "example": "66bcf64aa8907b9f9d90ac17746a77ce394c393b92b3916633dc02846e608ad4", "maxLength": 64, "minLength": 64, "x-sensitive": true }, "calls_turn_key_collection": { "allOf": [ { "$ref": "#/components/schemas/calls_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/calls_turn_key_object" } } }, "type": "object" } ] }, "calls_turn_key_editable_fields": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/calls_turn_key_name" } } }, "calls_turn_key_name": { "description": "A short description of a TURN key, not shown to end users.", "type": "string", "example": "my-turn-key", "default": "", "x-auditable": true }, "calls_turn_key_object": { "type": "object", "properties": { "created": { "$ref": "#/components/schemas/calls_created" }, "modified": { "$ref": "#/components/schemas/calls_modified" }, "name": { "$ref": "#/components/schemas/calls_name" }, "uid": { "$ref": "#/components/schemas/calls_identifier" } }, "required": [ "uid", "name", "created", "modified" ] }, "calls_turn_key_response_single": { "allOf": [ { "$ref": "#/components/schemas/calls_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/calls_turn_key_object" } }, "type": "object" } ] }, "calls_turn_key_single_with_secret": { "allOf": [ { "$ref": "#/components/schemas/calls_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/calls_turn_key_with_key" } }, "type": "object" } ] }, "calls_turn_key_with_key": { "type": "object", "properties": { "created": { "$ref": "#/components/schemas/calls_created" }, "key": { "$ref": "#/components/schemas/calls_turn_key" }, "modified": { "$ref": "#/components/schemas/calls_modified" }, "name": { "$ref": "#/components/schemas/calls_turn_key_name" }, "uid": { "$ref": "#/components/schemas/calls_identifier" } }, "required": [ "uid", "name", "key", "created", "modified" ] }, "cc_AccountID": { "description": "A unique identifier for the user's account.", "type": "string" }, "cc_Application": { "description": "Describes an application and the parameters that govern how it places its instances.", "type": "object", "properties": { "account_id": { "$ref": "#/components/schemas/cc_AccountID" }, "active_rollout_id": { "$ref": "#/components/schemas/cc_RolloutID" }, "configuration": { "$ref": "#/components/schemas/cc_UserDeploymentConfiguration" }, "constraints": { "$ref": "#/components/schemas/cc_ApplicationConstraints" }, "created_at": { "$ref": "#/components/schemas/cc_ISO8601Timestamp" }, "durable_objects": { "$ref": "#/components/schemas/cc_ApplicationDurableObjectsConfiguration" }, "health": { "$ref": "#/components/schemas/cc_ApplicationHealth" }, "id": { "$ref": "#/components/schemas/cc_ApplicationID" }, "instances": { "description": "Number of deployments to create.", "type": "integer" }, "max_instances": { "description": "Maximum number of instances the application allows. This is relevant for applications that auto-scale.", "type": "integer" }, "name": { "$ref": "#/components/schemas/cc_ApplicationName" }, "observability": { "description": "Top-level observability settings for the application.\nThis field is mutually exclusive with configuration.observability.\n", "allOf": [ { "$ref": "#/components/schemas/cc_ApplicationObservability" } ] }, "rollout_active_grace_period": { "$ref": "#/components/schemas/cc_ApplicationRolloutActiveGracePeriod" }, "scheduling_policy": { "$ref": "#/components/schemas/cc_SchedulingPolicy" }, "updated_at": { "$ref": "#/components/schemas/cc_ISO8601Timestamp" }, "version": { "type": "integer" } }, "required": [ "id", "created_at", "updated_at", "account_id", "name", "version", "scheduling_policy", "instances", "configuration" ] }, "cc_ApplicationConstraints": { "type": "object", "properties": { "jurisdiction": { "description": "Currently supports only \"eu\" and \"fedramp\". Overlap between jurisdiction and region is allowed for ENAM, WNAM (FedRAMP) and EEUR, WEUR (EU).", "type": "string" }, "regions": { "type": "array", "items": { "$ref": "#/components/schemas/cc_Region" } } } }, "cc_ApplicationDurableObjectsConfiguration": { "description": "Durable object configuration stored on and returned from a Cloudchamber application.", "oneOf": [ { "$ref": "#/components/schemas/cc_DurableObjectsConfigurationNamespaceId" } ] }, "cc_ApplicationHealth": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/cc_ApplicationHealthErrors" }, "instances": { "$ref": "#/components/schemas/cc_ApplicationHealthInstances" }, "summary": { "description": "High-level health assessment. Only populated for \"new_instances\" strategy.\nBased on a sample of target-version instances rather than a full count.\n- \"pending\": Zero target-version instances exist yet.\n- \"healthy\": Every sampled target-version instance reports running or active.\n- \"degraded\": Some sampled instances remain starting or scheduling.\n- \"unhealthy\": One or more sampled instances have failed.\n", "type": "string", "enum": [ "healthy", "degraded", "unhealthy", "pending" ] } }, "required": [ "instances", "errors" ] }, "cc_ApplicationHealthError": { "type": "object", "properties": { "event": { "$ref": "#/components/schemas/cc_PlacementEvent" }, "instance_id": { "$ref": "#/components/schemas/cc_InstanceID" } }, "required": [ "instance_id", "event" ] }, "cc_ApplicationHealthErrors": { "type": "array", "items": { "$ref": "#/components/schemas/cc_ApplicationHealthError" } }, "cc_ApplicationHealthInstances": { "description": "Shows a count of application instance states.", "type": "object", "properties": { "active": { "description": "Number of instances whose runtime reports the container as running (container_status = \"running\"). This is a subset of the placements that remain up: an instance that is already bound to a Durable Object and serving traffic is counted under \"assigned\" until its container_status catches up to \"running\", so container_status can briefly lag Durable Object attachment under churn. To estimate running, Durable-Object-bound instances, sum \"active\" + \"assigned\" rather than reading \"active\" alone.\n", "type": "integer" }, "assigned": { "description": "Number of instances bound to a Durable Object with a running placement whose container_status remains behind \"running\". These count as live, serving instances; \"active\" + \"assigned\" approximates the running, Durable-Object-bound count.\n", "type": "integer" } }, "required": [ "active", "assigned" ] }, "cc_ApplicationID": { "description": "An Application ID represents an identifier of an application.", "type": "string" }, "cc_ApplicationName": { "description": "The application name.", "type": "string" }, "cc_ApplicationObservability": { "description": "Settings for application observability such as logging. Supported fields depend\non the application's scheduling policy. Durable Object-managed applications\naccept only `logs.enabled`.\n", "type": "object", "properties": { "logs": { "$ref": "#/components/schemas/cc_ObservabilityLogs" } } }, "cc_ApplicationRollout": { "description": "Represents the status and metadata of a rollout process for an application.\nFor \"rolling\" strategy: includes steps and progress with instance counts.\nFor \"new_instances\" strategy: the response omits steps and progress. Use percentage,\nversion_distribution, and health.summary for status.\n", "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/cc_ISO8601Timestamp" }, "current_configuration": { "$ref": "#/components/schemas/cc_ModifyUserDeploymentConfiguration" }, "current_version": { "description": "Current application version before the rollout.", "type": "integer" }, "description": { "type": "string" }, "health": { "$ref": "#/components/schemas/cc_ApplicationHealth" }, "id": { "$ref": "#/components/schemas/cc_RolloutID" }, "kind": { "description": "Kind of the rollout process.\n - \"full_auto\": For rolling rollouts, starts progressing steps upon rollout creation. For new_instances rollouts, advances percentage targets automatically after target-version health is observed.\n - \"full_manual\": Requires manually progressing each step in the rollout using the UpdateRollout's action paramater.\n - \"durable_objects_auto\": Default when the application is a DO application.\n", "type": "string", "enum": [ "full_auto", "full_manual", "durable_objects_auto" ] }, "last_updated_at": { "description": "Timestamp of the most recent update to status, health, or progress.", "allOf": [ { "$ref": "#/components/schemas/cc_ISO8601Timestamp" } ] }, "percentage": { "description": "Current target version percentage (0-100). Only present for \"new_instances\" strategy.\n", "type": "integer" }, "progress": { "$ref": "#/components/schemas/cc_ApplicationRolloutProgress" }, "started_at": { "description": "Timestamp when the rollout started.", "type": "string", "format": "date-time" }, "status": { "description": "Current status of the rollout.", "type": "string", "enum": [ "pending", "progressing", "completed", "reverted", "replaced" ] }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/cc_RolloutStep" } }, "strategy": { "description": "The rollout strategy.\n- \"rolling\": Step-based rollout with health gates. Actively replaces instances to reach each step's target percentage. Response includes steps and progress.\n- \"new_instances\": Percentage control over version distribution. Version sync actively replaces instances to match the configured percentage. \"full_auto\" ramps through fixed percentage targets after target-version health is observed. Response includes percentage, version_distribution, and health.summary.\n", "type": "string", "enum": [ "rolling", "new_instances" ] }, "target_configuration": { "$ref": "#/components/schemas/cc_ModifyUserDeploymentConfiguration" }, "target_version": { "description": "Target application version after the rollout is complete and applied to all current instances.", "type": "integer" }, "version_distribution": { "description": "Version percentage distribution. Only present for \"new_instances\" strategy.\nFor \"rolling\" strategy, see progress.version_distribution instead.\n", "type": "object", "properties": { "current_version_percentage": { "description": "Percentage of instances on the current (old) version.", "type": "integer" }, "target_version_percentage": { "description": "Percentage of instances on the target (new) version.", "type": "integer" } }, "required": [ "target_version_percentage", "current_version_percentage" ] } }, "required": [ "id", "created_at", "last_updated_at", "description", "kind", "strategy", "current_version", "target_version", "current_configuration", "target_configuration", "status", "health" ] }, "cc_ApplicationRolloutActiveGracePeriod": { "description": "Grace period for active instances to stay alive before becoming eligible for shutdown signal due to a rollout, in seconds.\nDefaults to 0.\n", "type": "integer", "default": 0, "maximum": 604800, "minimum": 0 }, "cc_ApplicationRolloutProgress": { "description": "Progress details of an application rollout.", "type": "object", "properties": { "current_step": { "description": "Current step being executed in the rollout process. Initialized to 0.", "type": "integer" }, "total_instances": { "description": "Total number of instances the rollout affects.", "type": "integer" }, "total_steps": { "description": "Total number of steps in the rollout.", "type": "integer" }, "updated_instances": { "description": "Number of instances updated in the rollout process.", "type": "integer" }, "version_distribution": { "description": "Expected distribution of instances per version, based on the current percentage split.\nPopulated during active rollouts. Values derive from the version percentage weights\nrather than actual running instance counts.\n", "type": "object", "properties": { "current_version_instances": { "description": "Expected number of instances remaining on the current (old) version based on the current percentage split. Only populated for \"rolling\" strategy.", "type": "integer" }, "current_version_percentage": { "description": "The percentage of new instances being scheduled on the current version (100 - target_version_percentage).\nOnly populated for \"new_instances\" strategy.\n", "type": "integer" }, "target_version_instances": { "description": "Expected number of instances scheduled for the target (new) version based on the current percentage split. Only populated for \"rolling\" strategy.", "type": "integer" }, "target_version_percentage": { "description": "The active percentage of new instances being scheduled on the target version.\nFor \"rolling\", this reflects the step_size.percentage of the current active step.\nFor \"new_instances\", this reflects the user-set percentage.\n", "type": "integer" } } } }, "required": [ "total_steps", "current_step", "updated_instances", "total_instances" ] }, "cc_ApplicationVersion": { "description": "An application with the configuration of its version.", "type": "object", "properties": { "configuration": { "$ref": "#/components/schemas/cc_ModifyUserDeploymentConfiguration" }, "percentage": { "type": "integer" }, "version": { "type": "integer" } }, "required": [ "configuration", "percentage", "version" ] }, "cc_Command": { "description": "The command that runs when the container starts, passed to the entrypoint.\nYou can override this at run-time. If you override only the command,\nit gets passed to the default entrypoint specified in the image.\n", "type": "array", "items": { "$ref": "#/components/schemas/cc_ExecFormParam" }, "example": [ "myapp", "--default-option" ] }, "cc_ContainerImagePreparation": { "description": "Durable preparation state for a container image.", "type": "object", "properties": { "artifact_digest": { "description": "Digest of the prepared runtime artifact when status is ready.", "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, "image": { "$ref": "#/components/schemas/cc_Image" }, "reason": { "description": "Human-readable pending or terminal error detail.", "type": "string" }, "status": { "$ref": "#/components/schemas/cc_ContainerImagePreparationStatus" } }, "required": [ "image", "status" ] }, "cc_ContainerImagePreparationStatus": { "description": "Current durable preparation state for a container image.", "type": "string", "enum": [ "pending", "ready", "error" ] }, "cc_ContainerInstance": { "description": "A container instance belonging to an application.", "allOf": [ { "$ref": "#/components/schemas/cc_ContainerInstanceBase" }, { "properties": { "application_id": { "$ref": "#/components/schemas/cc_ApplicationID" }, "image": { "description": "The image for the current container placement, or the image currently configured for the application when the instance lacks a placement.\n", "allOf": [ { "$ref": "#/components/schemas/cc_Image" } ] } }, "required": [ "application_id", "image" ], "type": "object" } ] }, "cc_ContainerInstanceBase": { "description": "The last-reported state of a logical container instance.", "type": "object", "properties": { "application_id": { "$ref": "#/components/schemas/cc_ApplicationID" }, "configuration": { "$ref": "#/components/schemas/cc_ContainerInstanceConfiguration" }, "id": { "$ref": "#/components/schemas/cc_ContainerInstanceID" }, "image": { "description": "The image for the current container placement, when one is available.\n", "allOf": [ { "$ref": "#/components/schemas/cc_Image" } ] }, "location": { "$ref": "#/components/schemas/cc_ContainerInstanceLocation" }, "name": { "description": "The customer-provided instance name, when available. Its UTF-8 encoding uses at most 1,024 bytes.\n", "type": "string" }, "started_at": { "description": "The time at which the current container placement started, when one exists.", "allOf": [ { "$ref": "#/components/schemas/cc_ISO8601Timestamp" } ] }, "status": { "$ref": "#/components/schemas/cc_ContainerInstanceStatus" } }, "required": [ "id", "status" ] }, "cc_ContainerInstanceConfiguration": { "description": "The resources allocated to the container instance.", "type": "object", "properties": { "disk": { "description": "Disk allocated to the container instance, in decimal MB.", "type": "integer", "minimum": 1 }, "memory": { "description": "Memory allocated to the container instance, in MiB.", "type": "integer", "minimum": 1 }, "vcpu": { "description": "Number of virtual CPUs allocated to the container instance.", "type": "number", "exclusiveMinimum": true, "minimum": 0 } }, "required": [ "vcpu", "memory", "disk" ] }, "cc_ContainerInstanceID": { "description": "A container instance ID (64-character hex Durable Object actor ID).", "type": "string", "maxLength": 64, "minLength": 64, "pattern": "^[a-f0-9]{64}$" }, "cc_ContainerInstanceLocation": { "description": "The location of the instance's current container placement.", "type": "object", "properties": { "name": { "$ref": "#/components/schemas/cc_LocationID" }, "region": { "$ref": "#/components/schemas/cc_Region" } }, "required": [ "name", "region" ] }, "cc_ContainerInstanceStatus": { "description": "The latest known status of a container instance.", "type": "object", "properties": { "exit_code": { "description": "The process exit code, when the runtime reports one.", "type": "integer" }, "state": { "$ref": "#/components/schemas/cc_ContainerInstanceStatusState" }, "updated_at": { "$ref": "#/components/schemas/cc_ISO8601Timestamp" } }, "required": [ "state", "updated_at" ] }, "cc_ContainerInstanceStatusState": { "description": "The current lifecycle state of a container instance.", "type": "string", "enum": [ "provisioning", "running", "failed", "stopping", "stopped", "unhealthy", "inactive", "unknown" ] }, "cc_ContainersAccountRegistryToken": { "description": "Credentials returned for an authenticated registry configured on a Containers account.", "type": "object", "properties": { "account_id": { "$ref": "#/components/schemas/cc_AccountID" }, "password": { "description": "The password to use when authenticating to the image registry.", "type": "string" }, "registry_host": { "description": "The domain of the image registry these credentials target.", "type": "string" }, "username": { "description": "The username to use when authenticating to the image registry.", "type": "string" } }, "required": [ "account_id", "registry_host", "username", "password" ] }, "cc_ContainersApplicationResponse": { "description": "The public Containers API returns an application.", "oneOf": [ { "$ref": "#/components/schemas/cc_ScheduledApplication" }, { "$ref": "#/components/schemas/cc_DurableObjectApplication" } ] }, "cc_ContainersCreateApplicationRequest": { "description": "Create a Containers application.\nSet `scheduling_policy` to `default` for a\nscheduler-backed application with deployment configuration, instance counts,\nconstraints, versions, and rollouts. Set it to `durable_object` for a\nDurable Object-managed application where each Durable Object creates and manages\nthe lifecycle of its container instance. For `durable_object` requests, supply\n`name`, `scheduling_policy`, and `durable_objects`, with optional top-level\n`observability` settings.\n", "oneOf": [ { "$ref": "#/components/schemas/cc_ContainersCreateScheduledApplicationRequest" }, { "$ref": "#/components/schemas/cc_ContainersCreateDurableObjectApplicationRequest" } ] }, "cc_ContainersCreateApplicationRolloutRequest": { "description": "Request body to create a new rollout for a scheduler-backed application.", "type": "object", "properties": { "description": { "description": "Description of the rollout process.", "type": "string" }, "kind": { "description": "Kind of the rollout process. Defaults to \"full_auto\".\n - \"full_auto\": For rolling rollouts, starts progressing steps upon rollout creation. For new_instances rollouts, advances percentage targets automatically after target-version health is observed.\n - \"full_manual\": Requires manually progressing each step in the rollout using the UpdateRollout's action parameter.\n", "type": "string", "default": "full_auto", "enum": [ "full_auto", "full_manual" ] }, "percentage": { "description": "Initial target version percentage (0-100). Version sync actively replaces instances to match.\nRequired when strategy is \"new_instances\" and kind is \"full_manual\". When strategy is \"new_instances\" and kind is \"full_auto\", omitted percentage starts at 10% or the smallest percentage that targets at least one instance. Unused for \"rolling\".\n", "type": "integer", "maximum": 100, "minimum": 0 }, "step_percentage": { "description": "Percentage of rollout to increase in each step when \"steps\" is absent. Applicable values: 5, 10, 20, 25, 50, 100.\nThese create rollouts with 20, 10, 5, 4, 2, 1 steps respectively.\nOnly valid for \"rolling\" strategy.\n", "type": "integer", "enum": [ 5, 10, 20, 25, 50, 100 ] }, "steps": { "description": "Steps defining the rollout process, used when \"step_percentage\" is absent.\nSpecify only one of \"step_percentage\" or \"steps\" when creating a rollout.\n\"steps\" allow granular control over each step.\nOnly valid for \"rolling\" strategy.\n", "type": "array", "items": { "$ref": "#/components/schemas/cc_RolloutStepRequest" } }, "strategy": { "description": "Strategy used for the rollout.\n- \"rolling\": Step-based rollout with health gates. Actively replaces instances to reach each step's target percentage.\n- \"new_instances\": Percentage control over version distribution. Version sync actively replaces instances to match the configured percentage. The \"full_auto\" kind advances through fixed percentage targets after target-version health is observed.\n", "type": "string", "enum": [ "rolling", "new_instances" ] }, "target_configuration": { "$ref": "#/components/schemas/cc_ModifyUserDeploymentConfiguration" } }, "required": [ "target_configuration", "strategy", "description" ] }, "cc_ContainersCreateDurableObjectApplicationRequest": { "description": "Create a Durable Object-managed Containers application. Each Durable Object\ncreates and manages the lifecycle of its container instance. Supply `name`,\n`scheduling_policy`, and `durable_objects`, with optional top-level `observability`\nsettings. Deployment configuration, instance counts, scaling, constraints,\nversions, and rollouts do not apply.\n", "type": "object", "properties": { "durable_objects": { "description": "The customer-owned Durable Object namespace that owns this application and its instances.", "allOf": [ { "$ref": "#/components/schemas/cc_DurableObjectsConfiguration" } ] }, "name": { "description": "The name for this application.", "type": "string" }, "observability": { "$ref": "#/components/schemas/cc_DurableObjectApplicationObservability" }, "scheduling_policy": { "$ref": "#/components/schemas/cc_DurableObjectApplicationSchedulingPolicy" } }, "additionalProperties": false, "required": [ "name", "scheduling_policy", "durable_objects" ] }, "cc_ContainersCreateImageRegistryRequestBody": { "description": "Configuration for connecting Containers to a supported private external image\nregistry. See [Image management](https://developers.cloudflare.com/containers/platform-details/image-management/)\nfor supported providers and credential setup instructions.\n", "type": "object", "properties": { "auth": { "$ref": "#/components/schemas/cc_ContainersImageRegistryAuth" }, "domain": { "description": "Hostname of the private registry, without a scheme or image path. Supported\nhostnames are `docker.io`, AWS ECR hostnames, and Google Artifact Registry\n`*-docker.pkg.dev` hostnames.\n", "type": "string", "example": "docker.io" }, "is_public": { "description": "Omit this field or set it to `false`. Public Docker Hub images do not require\nregistry configuration and cannot be added with this endpoint.\n", "type": "boolean", "enum": [ false ] }, "kind": { "description": "Registry provider. This must match `domain`: `DockerHub` for `docker.io`,\n`ECR` for AWS ECR, or `GAR` for Google Artifact Registry.\n", "allOf": [ { "$ref": "#/components/schemas/cc_ExternalRegistryKind" } ] } }, "required": [ "domain", "auth", "kind" ] }, "cc_ContainersCreateScheduledApplicationRequest": { "description": "Create a scheduler-backed Containers application. The Containers scheduler\nmaintains the requested instance count and applies deployment configuration,\nplacement, scaling, versions, and rollouts.\n", "type": "object", "properties": { "configuration": { "description": "Defines the deployment configuration for every deployment in this application.\n", "allOf": [ { "$ref": "#/components/schemas/cc_UserDeploymentConfiguration" } ] }, "constraints": { "$ref": "#/components/schemas/cc_ApplicationConstraints" }, "durable_objects": { "description": "Optionally associates this scheduler-backed application with a Durable Object namespace.", "allOf": [ { "$ref": "#/components/schemas/cc_DurableObjectsConfiguration" } ] }, "instances": { "description": "The initial number of deployments to create.", "type": "integer", "minimum": 0 }, "max_instances": { "description": "Sets the maximum number of instances that the application can run.", "type": "integer", "minimum": 0 }, "name": { "description": "The name for this application.", "type": "string" }, "observability": { "description": "Top-level observability settings for the application.\nThis field is mutually exclusive with configuration.observability.\n", "allOf": [ { "$ref": "#/components/schemas/cc_ApplicationObservability" } ] }, "rollout_active_grace_period": { "$ref": "#/components/schemas/cc_ApplicationRolloutActiveGracePeriod" }, "scheduling_policy": { "$ref": "#/components/schemas/cc_ScheduledApplicationSchedulingPolicy" } }, "additionalProperties": false, "required": [ "name", "scheduling_policy", "instances", "max_instances", "configuration" ] }, "cc_ContainersDeleteApplicationResponseBody": { "description": "Result of starting asynchronous deletion for a Containers application.", "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "cc_ContainersDeleteImageRegistryResponseBody": { "description": "Result of deleting an image registry from a Containers account.", "type": "object", "properties": { "domain": { "$ref": "#/components/schemas/cc_Domain" } }, "required": [ "domain" ] }, "cc_ContainersImageRegistryAuth": { "description": "Credentials for authenticating to a private external image registry. Store the\nprivate credential in [Secrets Store](https://developers.cloudflare.com/secrets-store/)\nbefore calling the API. Refer to [Image management](https://developers.cloudflare.com/containers/platform-details/image-management/)\nfor the credential required by each supported registry provider.\n", "type": "object", "properties": { "private_credential": { "description": "A reference to the private registry credential in Secrets Store. The referenced\nsecret must have the `containers` scope. Raw secret values are not accepted.\n", "allOf": [ { "$ref": "#/components/schemas/cc_SecretsStoreRef" } ] }, "public_credential": { "description": "The non-secret part of the registry credential: an AWS access key ID for ECR,\na username for Docker Hub, or a service account email for Google Artifact Registry.\n", "type": "string", "example": "example-user" } }, "required": [ "public_credential", "private_credential" ] }, "cc_ContainersListApplications": { "description": "The public Containers API returns a list of applications.", "type": "array", "items": { "$ref": "#/components/schemas/cc_ContainersApplicationResponse" } }, "cc_ContainersListContainerInstances": { "description": "Container instances belonging to an application.", "type": "object", "properties": { "instances": { "type": "array", "items": { "$ref": "#/components/schemas/cc_ContainerInstance" } } }, "required": [ "instances" ] }, "cc_ContainersModifyApplicationConfiguration": { "description": "Application configuration fields you can change without creating a rollout.", "type": "object", "properties": { "authorized_keys": { "type": "array", "items": { "$ref": "#/components/schemas/cc_UserSSHPublicKey" } } } }, "cc_ContainersModifyApplicationRequestBody": { "description": "Request body for modifying a Containers application without replacing its instances.\nDurable Object-managed applications support only top-level observability.logs.enabled.\nThe other fields apply to scheduler-backed applications, where deployment configuration\nchanges such as image, resource allocation, command, and environment variables require\nan application rollout.\n", "type": "object", "properties": { "configuration": { "$ref": "#/components/schemas/cc_ContainersModifyApplicationConfiguration" }, "constraints": { "$ref": "#/components/schemas/cc_ApplicationConstraints" }, "max_instances": { "description": "Maximum number of instances that an autoscaling application can run.", "type": "integer", "minimum": 0 }, "observability": { "description": "Top-level application observability settings. Scheduler-backed applications\nhot-reload these settings across existing instances. An existing Durable\nObject-managed application accepts only `logs.enabled` and publishes these settings\nto runtime metadata without creating deployments or rollouts.\n", "allOf": [ { "$ref": "#/components/schemas/cc_ApplicationObservability" } ] }, "rollout_active_grace_period": { "$ref": "#/components/schemas/cc_ApplicationRolloutActiveGracePeriod" } } }, "cc_CustomerImageRegistry": { "description": "An image registry added in a customer account.", "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/cc_ISO8601Timestamp" }, "domain": { "$ref": "#/components/schemas/cc_Domain" }, "kind": { "description": "The type of registry that is being configured.", "oneOf": [ { "$ref": "#/components/schemas/cc_ExternalRegistryKind" }, { "$ref": "#/components/schemas/cc_DefaultImageRegistryKind" } ] }, "public_key": { "description": "Public component of the registry credentials. For managed registries this is\na base64-encoded public key; for external registries the format depends on\nthe registry provider.\n", "type": "string" } }, "required": [ "domain", "created_at" ] }, "cc_DefaultImageRegistryKind": { "type": "string", "enum": [ "default" ] }, "cc_DeploymentObservability": { "description": "Settings for deployment observability such as logging.", "type": "object", "properties": { "logs": { "$ref": "#/components/schemas/cc_ObservabilityLogs" } } }, "cc_Domain": { "description": "A string representation of a domain name. See RFC-1034 (https://www.ietf.org/rfc/rfc1034.txt). Consider that the limit of a domain name is min 3 and max 253 ASCII characters.", "type": "string", "example": "docker.io" }, "cc_DurableObjectApplication": { "description": "Each Durable Object creates and manages the lifecycle of its container instance.", "type": "object", "properties": { "account_id": { "$ref": "#/components/schemas/cc_AccountID" }, "created_at": { "$ref": "#/components/schemas/cc_ISO8601Timestamp" }, "durable_objects": { "$ref": "#/components/schemas/cc_DurableObjectsConfigurationNamespaceId" }, "health": { "$ref": "#/components/schemas/cc_DurableObjectApplicationHealth" }, "id": { "$ref": "#/components/schemas/cc_ApplicationID" }, "name": { "$ref": "#/components/schemas/cc_ApplicationName" }, "observability": { "$ref": "#/components/schemas/cc_DurableObjectApplicationObservability" }, "scheduling_policy": { "$ref": "#/components/schemas/cc_DurableObjectApplicationSchedulingPolicy" }, "updated_at": { "$ref": "#/components/schemas/cc_ISO8601Timestamp" } }, "required": [ "id", "created_at", "updated_at", "account_id", "name", "scheduling_policy", "durable_objects" ] }, "cc_DurableObjectApplicationHealth": { "description": "Aggregate current activity for the latest observed placement of each instance.\nRuntime snapshots feed periodic background sweeps. Counts refresh after each\ncomplete sweep. Instance listings retain their separate three-month history\nfor failure discovery.\n", "type": "object", "properties": { "instances": { "description": "Counts of observed non-terminal instances.", "type": "object", "properties": { "active": { "description": "Number of instances whose runtime reports running or stopping.", "type": "integer", "minimum": 0 }, "starting": { "description": "Number of instances whose runtime reports starting.", "type": "integer", "minimum": 0 } }, "required": [ "active", "starting" ] }, "summary": { "description": "Present as pending until the first activity sweep completes; omitted afterward.", "type": "string", "enum": [ "pending" ] } }, "required": [ "instances" ] }, "cc_DurableObjectApplicationObservability": { "description": "Application-wide logging settings for a Durable Object-managed application.\nThe application publishes these settings to its runtime metadata. Updating\nthem does not create a deployment or rollout.\n", "type": "object", "properties": { "logs": { "description": "Application-wide logging settings.", "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "default": false } } } }, "additionalProperties": false }, "cc_DurableObjectApplicationSchedulingPolicy": { "description": "Selects a Durable Object-managed application. Each Durable Object creates and\nmanages the lifecycle of its container instance. Configure application-wide\nobservability settings here. Deployment configuration, scaling, placement\nconstraints, versions, and rollouts do not apply.\n", "type": "string", "enum": [ "durable_object" ] }, "cc_DurableObjectsConfiguration": { "description": "Set of properties to configure a Durable Object-backed application.", "oneOf": [ { "$ref": "#/components/schemas/cc_DurableObjectsConfigurationNamespaceId" }, { "$ref": "#/components/schemas/cc_DurableObjectsConfigurationScriptAndClass" } ] }, "cc_DurableObjectsConfigurationNamespaceId": { "description": "Durable object configuration using a namespace ID.", "type": "object", "properties": { "namespace_id": { "description": "The namespace ID of the durable object namespace to use for this application.", "type": "string", "example": "14758f1afd44c09b7992073ccf00b43d" } }, "required": [ "namespace_id" ] }, "cc_DurableObjectsConfigurationScriptAndClass": { "description": "Durable object configuration using script and class names.", "type": "object", "properties": { "class_name": { "description": "The class name of the durable object.", "type": "string" }, "script_name": { "description": "The script name where the durable object class is defined.", "type": "string" } }, "required": [ "script_name", "class_name" ] }, "cc_Entrypoint": { "description": "The entry point for the container, specifying the executable to run when the container starts.\nYou can override this at run-time. If you do, the default command from the image is ignored.\nSpecify both entrypoint and command at run-time to completely replace the image defaults.\n", "type": "array", "items": { "$ref": "#/components/schemas/cc_ExecFormParam" }, "example": [ "/bin/bash" ] }, "cc_EnvironmentVariable": { "description": "An environment variable with a value set.", "type": "object", "properties": { "name": { "$ref": "#/components/schemas/cc_EnvironmentVariableName" }, "value": { "$ref": "#/components/schemas/cc_EnvironmentVariableValue" } }, "required": [ "name", "value" ] }, "cc_EnvironmentVariableName": { "description": "An environment variable name.", "type": "string" }, "cc_EnvironmentVariableValue": { "description": "An environment variable value.", "type": "string" }, "cc_EventName": { "description": "Name of the event that describes the kind event that happened.\n - SchedulerPlaced: It's the first event that creates a container placement. It happens when the Containers runtime was able to retrieve deployment resources and start verifying everything is correct.\n - NetworkingIPAssigned: It's sent when the Containers runtime maps the IP to the container.\n - VMStarted: It's sent when the Containers runtime starts the VM. The container might remain unhealthy at this point.\n - ImagePulled: It's sent when the Containers runtime pulls the image successfully.\n - ImagePullError: It's sent when the Containers runtime is having issues pulling the image. The message and details have more information on what happened for debugging.\n - VMFailedToStart: It's sent when the Containers runtime was unable to boot the VM.\n - VMStopping: It's sent when the scheduler is stopping the VM.\n - VMStopped: It's sent when the VM finally exits.\n - VMFailed: It's sent when the scheduling of the VM failed in the current location.\n - RuntimeStartFailed: It's sent when the runtime hits an internal error.\n - SSHStarted: It's sent when the container gains network connectivity and opens the SSH port. Containers only send this event when SSH keys exist.\n - CheckUpdate: Sent when the status of a health or readiness check changes. This may also affect the health status of the placement.\n - DurableObjectConnected: Sent when a durable object instance connects and gains control of the deployment.\n This event is only sent for durable object deployments. It is sent after VMStarted.\n - ContainerStarted: It's sent when the container starts running.\n", "type": "string", "enum": [ "SchedulerPlaced", "NetworkingIPAssigned", "VMStarted", "ImagePulled", "ImagePullError", "VMFailedToStart", "NetworkingIPAssignmentFailed", "VMRunning", "VMStopping", "VMStopped", "VMFailed", "RuntimeStartFailed", "SSHStarted", "ServiceHealthUpdates", "CheckUpdate", "DurableObjectConnected", "ContainerStarted" ] }, "cc_EventType": { "type": "string", "enum": [ "Info", "Error", "Warn", "UserError", "SystemError" ] }, "cc_ExecFormParam": { "type": "string" }, "cc_ExternalRegistryKind": { "description": "The type of external registry that is being configured.", "type": "string", "example": "ECR", "enum": [ "ECR", "DockerHub", "GAR" ] }, "cc_ISO8601Timestamp": { "description": "UTC timestamp string in ISO 8601 format.", "type": "string", "example": "2021-04-01T12:32:41.488Z" }, "cc_Image": { "description": "Image url.", "type": "string" }, "cc_ImageRegistryCredentialsConfiguration": { "description": "Specifies the configuration for the image registry credential to create. Cloudflare requires both fields for managed registries. For external registries, Cloudflare ignores both fields, and the registry provider determines the returned credentials' permissions and lifetime.", "type": "object", "properties": { "expiration_minutes": { "description": "The number of minutes Cloudflare managed registry credentials stay valid. Required for managed registries and must remain positive. Cloudflare ignores this value for external registries.", "type": "integer", "minimum": 1 }, "permissions": { "description": "The permissions for Cloudflare managed registry credentials. Required for managed registries. Cloudflare ignores this value for external registries.", "type": "array", "items": { "$ref": "#/components/schemas/cc_ImageRegistryPermissions" } } } }, "cc_ImageRegistryPermissions": { "description": "Specifies what permissions the credentials carry.", "type": "string", "enum": [ "pull", "push", "list" ] }, "cc_InstanceID": { "description": "An instance ID represents an identifier of an instance configuration that maintains an underlying placement.", "type": "string" }, "cc_InstanceType": { "description": "The instance type configures vCPU, memory, and disk.\n\n- \"lite\": 1/16 vCPU, 256 MiB memory, 2 GB disk\n- \"basic\": 1/4 vCPU, 1 GiB memory, 4 GB disk\n- \"standard-1\": 1/2 vCPU, 4 GiB memory, 8 GB disk\n- \"standard-2\": 1 vCPU, 6 GiB memory, 12 GB disk\n- \"standard-3\": 2 vCPU, 8 GiB memory, 16 GB disk\n- \"standard-4\": 4 vCPU, 12 GiB memory, 20 GB disk\n", "type": "string", "example": "lite", "default": "lite", "anyOf": [ { "enum": [ "lite", "basic", "standard-1", "standard-2", "standard-3", "standard-4" ], "type": "string" } ] }, "cc_LocationID": { "description": "Unique location code used to identify locations on a logical level.", "type": "string" }, "cc_Messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "cc_ModifyUserDeploymentConfiguration": { "description": "User-specified container configuration changes.", "type": "object", "properties": { "authorized_keys": { "type": "array", "items": { "$ref": "#/components/schemas/cc_UserSSHPublicKey" } }, "command": { "$ref": "#/components/schemas/cc_Command" }, "entrypoint": { "$ref": "#/components/schemas/cc_Entrypoint" }, "environment_variables": { "description": "Container environment variables.", "type": "array", "items": { "$ref": "#/components/schemas/cc_EnvironmentVariable" } }, "image": { "$ref": "#/components/schemas/cc_Image" }, "instance_type": { "$ref": "#/components/schemas/cc_InstanceType" }, "observability": { "$ref": "#/components/schemas/cc_DeploymentObservability" } } }, "cc_ObservabilityLogs": { "description": "Observability logging settings.", "type": "object", "properties": { "enabled": { "type": "boolean", "default": false } } }, "cc_PlacementEvent": { "description": "An event within a Placement or a Job.", "type": "object", "properties": { "details": { "type": "object", "additionalProperties": true }, "id": { "type": "string" }, "message": { "type": "string" }, "name": { "$ref": "#/components/schemas/cc_EventName" }, "statusChange": { "type": "object", "additionalProperties": true }, "time": { "$ref": "#/components/schemas/cc_ISO8601Timestamp" }, "type": { "$ref": "#/components/schemas/cc_EventType" } }, "required": [ "id", "time", "type", "name", "message", "details", "statusChange" ] }, "cc_PrepareContainerImageRequestBody": { "description": "A digest-pinned managed container image to prepare for the new runtime.", "type": "object", "properties": { "image": { "$ref": "#/components/schemas/cc_Image" } }, "additionalProperties": false, "required": [ "image" ] }, "cc_Region": { "description": "Represents a group of datacenters. Choose one of \"AFR\", \"APAC\", \"EEUR\", \"ENAM\", \"WNAM\", \"ME\", \"OC\", \"SAM\", or \"WEUR\".\n", "type": "string", "example": "WNAM" }, "cc_RolloutID": { "description": "An identifier for a specific rollout within an application.", "type": "string" }, "cc_RolloutStep": { "description": "Steps within the rollout process.", "type": "object", "properties": { "completed_at": { "$ref": "#/components/schemas/cc_ISO8601Timestamp" }, "description": { "description": "Description of the rollout step.", "type": "string" }, "id": { "description": "The sequential order of the rollout step, automatically assigned starting from 1, based on the total number of steps in the rollout process.", "type": "integer" }, "reason": { "description": "Reason for the step's current status.", "type": "string" }, "started_at": { "$ref": "#/components/schemas/cc_ISO8601Timestamp" }, "status": { "description": "Status of the rollout step.", "type": "string", "enum": [ "pending", "progressing", "reverting", "completed", "reverted" ] }, "step_size": { "type": "object", "properties": { "percentage": { "description": "Percentage of instances affected in this step. Min 10% and Max 100%.", "type": "integer" } }, "required": [ "percentage" ] } }, "required": [ "id", "step_size", "description", "status" ] }, "cc_RolloutStepRequest": { "description": "Steps defining the rollout process.", "type": "object", "properties": { "description": { "description": "Description of the rollout step.", "type": "string" }, "step_size": { "type": "object", "properties": { "percentage": { "description": "Percentage of instances affected in this step. Min 10% and Max 100%.", "type": "integer" } }, "required": [ "percentage" ] } }, "required": [ "step_size", "description" ] }, "cc_SSHPublicKey": { "description": "An SSH public key.", "type": "string" }, "cc_ScheduledApplication": { "description": "The Containers scheduler manages this application's instances, configuration, versions, and rollouts.", "allOf": [ { "$ref": "#/components/schemas/cc_Application" }, { "properties": { "scheduling_policy": { "$ref": "#/components/schemas/cc_ScheduledApplicationSchedulingPolicy" } }, "required": [ "scheduling_policy" ], "type": "object" } ] }, "cc_ScheduledApplicationSchedulingPolicy": { "description": "Selects a scheduler-backed application. Use `default` when the Containers\nscheduler should maintain the requested number of instances and manage deployment\nconfiguration, placement, scaling, versions, and rollouts.\n", "type": "string", "enum": [ "default" ] }, "cc_SchedulingPolicy": { "description": "The scheduling policy to use for an application.", "type": "string", "enum": [ "default", "durable_object" ] }, "cc_SecretsStoreRef": { "description": "Identifies an existing secret in [Secrets Store](https://developers.cloudflare.com/secrets-store/).\nThis reference does not contain or upload the secret value.\n", "type": "object", "properties": { "secret_name": { "description": "Name of the secret within the store.", "type": "string", "example": "API_KEY", "maxLength": 255, "minLength": 1, "pattern": "^[A-z0-9-_]+$" }, "store_id": { "description": "Identifier of the Secrets Store containing the secret.", "type": "string", "example": "14758f1afd44c09b7992073ccf00b43d", "maxLength": 32, "minLength": 32, "pattern": "^[a-f0-9]{32}$" } }, "required": [ "store_id", "secret_name" ] }, "cc_UserDeploymentConfiguration": { "description": "User-specified container configuration.", "type": "object", "properties": { "authorized_keys": { "type": "array", "items": { "$ref": "#/components/schemas/cc_UserSSHPublicKey" } }, "command": { "$ref": "#/components/schemas/cc_Command" }, "entrypoint": { "$ref": "#/components/schemas/cc_Entrypoint" }, "environment_variables": { "description": "Container environment variables.", "type": "array", "items": { "$ref": "#/components/schemas/cc_EnvironmentVariable" } }, "image": { "$ref": "#/components/schemas/cc_Image" }, "instance_type": { "$ref": "#/components/schemas/cc_InstanceType" }, "observability": { "$ref": "#/components/schemas/cc_DeploymentObservability" } }, "required": [ "image" ] }, "cc_UserSSHPublicKey": { "description": "User-provided SSH public key.", "type": "object", "properties": { "name": { "description": "Optional human readable name for this key.", "type": "string" }, "public_key": { "$ref": "#/components/schemas/cc_SSHPublicKey" } }, "required": [ "public_key" ] }, "cc_V4BaseErrorResponse": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/cc_Messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/cc_Messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean" } }, "required": [ "success", "errors", "messages", "result" ] }, "cc_V4BasePaginatedResponse": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cc_V4BaseResponse" }, { "properties": { "result_info": { "type": "object", "properties": { "next_page_token": { "description": "The token to use to retrieve the next page of results.", "type": "string" }, "page_token": { "description": "The page token sent in the request.", "type": "string" }, "per_page": { "description": "The number of items per page requested.", "type": "integer" } } } }, "required": [ "result_info" ], "type": "object" } ] }, "cc_V4BaseResponse": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/cc_Messages" }, "messages": { "$ref": "#/components/schemas/cc_Messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages" ] }, "client-side-security_api-get-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/client-side-security_api-response-common" }, { "properties": { "result": { "type": "object", "nullable": true } } } ] }, "client-side-security_api-list-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/client-side-security_api-response-common" }, { "properties": { "result_info": { "$ref": "#/components/schemas/client-side-security_result_info" } }, "required": [ "result_info" ] } ] }, "client-side-security_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/client-side-security_messages" }, "messages": { "$ref": "#/components/schemas/client-side-security_messages" }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success" ] }, "client-side-security_api-response-common-failure": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/client-side-security_messages" }, "messages": { "$ref": "#/components/schemas/client-side-security_messages" }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors" ] }, "client-side-security_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/client-side-security_api-response-common" }, { "properties": { "result": { "anyOf": [ { "type": "object" }, { "items": {}, "type": "array" }, { "type": "string" } ] } } } ] }, "client-side-security_connection": { "properties": { "added_at": { "type": "string", "format": "date-time", "example": "2021-08-18T10:51:10.09615Z" }, "domain_reported_malicious": { "type": "boolean", "example": false }, "first_page_url": { "type": "string", "example": "blog.cloudflare.com/page" }, "first_seen_at": { "type": "string", "format": "date-time", "example": "2021-08-18T10:51:08Z" }, "host": { "type": "string", "example": "blog.cloudflare.com" }, "id": { "$ref": "#/components/schemas/client-side-security_id" }, "last_seen_at": { "type": "string", "format": "date-time", "example": "2021-09-02T09:57:54Z" }, "malicious_domain_categories": { "type": "array", "items": { "type": "string" }, "example": [ "Malware" ] }, "malicious_url_categories": { "type": "array", "items": { "type": "string" }, "example": [ "Malware" ] }, "page_urls": { "type": "array", "items": { "type": "string" }, "example": [ "blog.cloudflare.com/page1", "blog.cloudflare.com/page2" ] }, "url": { "type": "string", "example": "https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.6.0/js/bootstrap.min.js" }, "url_contains_cdn_cgi_path": { "type": "boolean", "example": false }, "url_reported_malicious": { "type": "boolean", "example": false } }, "required": [ "id", "url", "added_at", "first_seen_at", "last_seen_at", "host", "url_contains_cdn_cgi_path" ] }, "client-side-security_cookie": { "properties": { "domain_attribute": { "type": "string", "example": "cloudflare.com" }, "expires_attribute": { "type": "string", "format": "date-time", "example": "2021-10-02T09:57:54Z" }, "first_seen_at": { "type": "string", "format": "date-time", "example": "2021-08-18T10:51:08Z" }, "host": { "type": "string", "example": "blog.cloudflare.com" }, "http_only_attribute": { "type": "boolean", "example": true }, "id": { "$ref": "#/components/schemas/client-side-security_id" }, "last_seen_at": { "type": "string", "format": "date-time", "example": "2021-09-02T09:57:54Z" }, "max_age_attribute": { "type": "integer", "example": 3600 }, "name": { "type": "string", "example": "session_id" }, "page_urls": { "type": "array", "items": { "type": "string" }, "example": [ "blog.cloudflare.com/page1", "blog.cloudflare.com/page2" ] }, "path_attribute": { "type": "string", "example": "/" }, "same_site_attribute": { "type": "string", "example": "strict", "enum": [ "lax", "strict", "none" ] }, "secure_attribute": { "type": "boolean", "example": true }, "type": { "type": "string", "example": "first_party", "enum": [ "first_party", "unknown" ] } }, "required": [ "id", "type", "name", "host", "first_seen_at", "last_seen_at" ] }, "client-side-security_cryptomining_score": { "description": "The cryptomining score of the JavaScript content.", "type": "integer", "maximum": 99, "minimum": 1, "nullable": true }, "client-side-security_dataflow_score": { "description": "The dataflow score of the JavaScript content. This field has been deprecated in favour of js_integrity_score.", "type": "integer", "maximum": 99, "minimum": 1, "nullable": true }, "client-side-security_enabled": { "description": "When true, indicates that Client-Side Security is enabled.", "type": "boolean", "example": true, "x-auditable": true }, "client-side-security_fetched_at": { "description": "The timestamp of when the script was last fetched.", "type": "string", "nullable": true }, "client-side-security_get-zone-connection-response": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_api-get-response-collection" }, { "properties": { "result": { "$ref": "#/components/schemas/client-side-security_connection" } }, "required": [ "result" ] } ] }, "client-side-security_get-zone-cookie-response": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_api-get-response-collection" }, { "properties": { "result": { "$ref": "#/components/schemas/client-side-security_cookie" } }, "required": [ "result" ] } ] }, "client-side-security_get-zone-policy-response": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_api-get-response-collection" }, { "properties": { "result": { "$ref": "#/components/schemas/client-side-security_policy-with-id" } }, "required": [ "result" ] } ] }, "client-side-security_get-zone-script-response": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_api-get-response-collection" }, { "properties": { "result": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_script" }, { "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/client-side-security_version" }, "example": [ { "cryptomining_score": 20, "fetched_at": "2021-08-18T10:51:08Z", "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b423", "js_integrity_score": 2, "magecart_score": 10, "malware_score": 5 } ], "nullable": true } } } ] } }, "required": [ "result" ] } ] }, "client-side-security_get-zone-settings-response": { "properties": { "enabled": { "$ref": "#/components/schemas/client-side-security_enabled" }, "updated_at": { "$ref": "#/components/schemas/client-side-security_updated_at" }, "use_cloudflare_reporting_endpoint": { "$ref": "#/components/schemas/client-side-security_use_cloudflare_reporting_endpoint" }, "use_connection_url_path": { "$ref": "#/components/schemas/client-side-security_use_connection_url_path" } }, "required": [ "enabled", "updated_at", "use_cloudflare_reporting_endpoint", "use_connection_url_path" ] }, "client-side-security_hash": { "description": "The computed hash of the analyzed script.", "type": "string", "maxLength": 64, "minLength": 64, "nullable": true }, "client-side-security_id": { "description": "Identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "client-side-security_js_integrity_score": { "description": "The integrity score of the JavaScript content.", "type": "integer", "maximum": 99, "minimum": 1, "nullable": true }, "client-side-security_list-zone-connections-response": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_api-list-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/client-side-security_connection" } } }, "type": "object" } ] }, "client-side-security_list-zone-cookies-response": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_api-list-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/client-side-security_cookie" } } }, "required": [ "result" ], "type": "object" } ] }, "client-side-security_list-zone-policies-response": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_api-list-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/client-side-security_policy-with-id" } } }, "required": [ "result" ], "type": "object" } ] }, "client-side-security_list-zone-scripts-response": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_api-list-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/client-side-security_script" } } }, "required": [ "result" ], "type": "object" } ] }, "client-side-security_magecart_score": { "description": "The magecart score of the JavaScript content.", "type": "integer", "maximum": 99, "minimum": 1, "nullable": true }, "client-side-security_malware_score": { "description": "The malware score of the JavaScript content.", "type": "integer", "maximum": 99, "minimum": 1, "nullable": true }, "client-side-security_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "client-side-security_obfuscation_score": { "description": "The obfuscation score of the JavaScript content. This field has been deprecated in favour of js_integrity_score.", "type": "integer", "maximum": 99, "minimum": 1, "nullable": true }, "client-side-security_policy": { "properties": { "action": { "$ref": "#/components/schemas/client-side-security_policy-action" }, "description": { "$ref": "#/components/schemas/client-side-security_policy-description" }, "enabled": { "$ref": "#/components/schemas/client-side-security_policy-enabled" }, "expression": { "$ref": "#/components/schemas/client-side-security_policy-expression" }, "value": { "$ref": "#/components/schemas/client-side-security_policy-value" } }, "required": [ "description", "action", "expression", "enabled", "value" ] }, "client-side-security_policy-action": { "description": "The action to take if the expression matches", "type": "string", "example": "allow", "enum": [ "allow", "log", "add_reporting_directives" ], "x-auditable": true }, "client-side-security_policy-description": { "description": "A description for the policy", "type": "string", "example": "Checkout page CSP policy", "x-auditable": true }, "client-side-security_policy-enabled": { "description": "Whether the policy is enabled", "type": "boolean", "example": true, "x-auditable": true }, "client-side-security_policy-expression": { "description": "The expression which must match for the policy to be applied, using the Cloudflare Firewall rule expression syntax", "type": "string", "example": "ends_with(http.request.uri.path, \"/checkout\")", "x-auditable": true }, "client-side-security_policy-value": { "description": "The policy which will be applied", "type": "string", "example": "script-src 'none';", "x-auditable": true }, "client-side-security_policy-with-id": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_policy" }, { "properties": { "id": { "$ref": "#/components/schemas/client-side-security_id" } }, "required": [ "id" ] } ], "required": [ "id", "description", "action", "expression", "enabled", "value" ] }, "client-side-security_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters", "type": "number", "example": 2000 }, "total_pages": { "description": "Total number of pages", "type": "number", "example": 100 } }, "required": [ "page", "per_page", "count", "total_count", "total_pages" ] }, "client-side-security_script": { "properties": { "added_at": { "type": "string", "format": "date-time", "example": "2021-08-18T10:51:10.09615Z" }, "cryptomining_score": { "$ref": "#/components/schemas/client-side-security_cryptomining_score" }, "dataflow_score": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_dataflow_score" } ], "deprecated": true }, "domain_reported_malicious": { "type": "boolean", "example": false }, "fetched_at": { "$ref": "#/components/schemas/client-side-security_fetched_at" }, "first_page_url": { "type": "string", "example": "blog.cloudflare.com/page" }, "first_seen_at": { "type": "string", "format": "date-time", "example": "2021-08-18T10:51:08Z" }, "hash": { "$ref": "#/components/schemas/client-side-security_hash" }, "host": { "type": "string", "example": "blog.cloudflare.com" }, "id": { "$ref": "#/components/schemas/client-side-security_id" }, "js_integrity_score": { "$ref": "#/components/schemas/client-side-security_js_integrity_score" }, "last_seen_at": { "type": "string", "format": "date-time", "example": "2021-09-02T09:57:54Z" }, "magecart_score": { "$ref": "#/components/schemas/client-side-security_magecart_score" }, "malicious_domain_categories": { "type": "array", "items": { "type": "string" }, "example": [ "Malware" ] }, "malicious_url_categories": { "type": "array", "items": { "type": "string" }, "example": [ "Malware" ] }, "malware_score": { "$ref": "#/components/schemas/client-side-security_malware_score" }, "obfuscation_score": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_obfuscation_score" } ], "deprecated": true }, "page_urls": { "type": "array", "items": { "type": "string" }, "example": [ "blog.cloudflare.com/page1", "blog.cloudflare.com/page2" ] }, "url": { "type": "string", "example": "https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/4.6.0/js/bootstrap.min.js" }, "url_contains_cdn_cgi_path": { "type": "boolean", "example": false }, "url_reported_malicious": { "type": "boolean", "example": false } }, "required": [ "id", "url", "added_at", "first_seen_at", "last_seen_at", "host", "url_contains_cdn_cgi_path" ] }, "client-side-security_update-zone-settings-response": { "properties": { "enabled": { "$ref": "#/components/schemas/client-side-security_enabled" }, "updated_at": { "$ref": "#/components/schemas/client-side-security_updated_at" }, "use_cloudflare_reporting_endpoint": { "$ref": "#/components/schemas/client-side-security_use_cloudflare_reporting_endpoint" }, "use_connection_url_path": { "$ref": "#/components/schemas/client-side-security_use_connection_url_path" } }, "required": [ "enabled", "updated_at", "use_cloudflare_reporting_endpoint", "use_connection_url_path" ] }, "client-side-security_updated_at": { "description": "The timestamp of when Client-Side Security was last updated.", "type": "string", "example": "2022-10-12T17:56:52.083582+01:00", "x-auditable": true }, "client-side-security_use_cloudflare_reporting_endpoint": { "description": "When true, CSP reports will be sent to https://csp-reporting.cloudflare.com/cdn-cgi/script_monitor/report", "type": "boolean", "example": true, "x-auditable": true }, "client-side-security_use_connection_url_path": { "description": "When true, the paths associated with connections URLs will also be analyzed.", "type": "boolean", "example": true, "x-auditable": true }, "client-side-security_version": { "description": "The version of the analyzed script.", "type": "object", "properties": { "cryptomining_score": { "$ref": "#/components/schemas/client-side-security_cryptomining_score" }, "dataflow_score": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_dataflow_score" } ], "deprecated": true }, "fetched_at": { "$ref": "#/components/schemas/client-side-security_fetched_at" }, "hash": { "$ref": "#/components/schemas/client-side-security_hash" }, "js_integrity_score": { "$ref": "#/components/schemas/client-side-security_js_integrity_score" }, "magecart_score": { "$ref": "#/components/schemas/client-side-security_magecart_score" }, "malware_score": { "$ref": "#/components/schemas/client-side-security_malware_score" }, "obfuscation_score": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_obfuscation_score" } ], "deprecated": true } } }, "client-side-security_zone_settings_response_single": { "allOf": [ { "$ref": "#/components/schemas/client-side-security_api-response-single" }, { "properties": { "result": { "type": "object" } } } ] }, "cloud-connector_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/cloud-connector_messages" }, "messages": { "$ref": "#/components/schemas/cloud-connector_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "cloud-connector_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/cloud-connector_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/cloud-connector_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "cloud-connector_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "cloud-connector_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "cloud-connector_provider": { "description": "Cloud Provider type", "type": "string", "example": "aws_s3", "enum": [ "aws_s3", "cloudflare_r2", "gcp_storage", "azure_storage", "oci_storage" ], "x-auditable": true }, "cloud-connector_rule": { "type": "object", "properties": { "description": { "type": "string", "example": "Rule description", "x-auditable": true }, "enabled": { "type": "boolean", "example": true, "x-auditable": true }, "expression": { "type": "string", "example": "http.cookie eq \"a=b\"", "x-auditable": true }, "id": { "type": "string", "example": "95c365e17e1b46599cd99e5b231fac4e", "x-auditable": true }, "parameters": { "description": "Parameters of Cloud Connector Rule", "properties": { "host": { "description": "Host to perform Cloud Connection to", "type": "string", "example": "examplebucket.s3.eu-north-1.amazonaws.com", "x-auditable": true } }, "type": "object" }, "provider": { "$ref": "#/components/schemas/cloud-connector_provider" } } }, "cloud-connector_rules": { "description": "List of Cloud Connector rules", "type": "array", "items": { "$ref": "#/components/schemas/cloud-connector_rule" } }, "cloud-connector_zone_identifier": { "$ref": "#/components/schemas/cloud-connector_identifier" }, "cloudflare-pipelines_ConnectionSchema": { "description": "Defines the schema of the events in the data stream.", "type": "object", "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/cloudflare-pipelines_SourceField" } }, "inferred": { "type": "boolean", "nullable": true } } }, "cloudflare-pipelines_DecimalEncoding": { "type": "string", "enum": [ "number", "string", "bytes" ] }, "cloudflare-pipelines_FieldType": { "discriminator": { "propertyName": "type" }, "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "int32" ] } }, "required": [ "type" ], "title": "Int32", "type": "object" }, { "properties": { "type": { "type": "string", "enum": [ "int64" ] } }, "required": [ "type" ], "title": "Int64", "type": "object" }, { "properties": { "type": { "type": "string", "enum": [ "float32" ] } }, "required": [ "type" ], "title": "Float32", "type": "object" }, { "properties": { "type": { "type": "string", "enum": [ "float64" ] } }, "required": [ "type" ], "title": "Float64", "type": "object" }, { "properties": { "type": { "type": "string", "enum": [ "bool" ] } }, "required": [ "type" ], "title": "Bool", "type": "object" }, { "properties": { "type": { "type": "string", "enum": [ "string" ] } }, "required": [ "type" ], "title": "String", "type": "object" }, { "properties": { "type": { "type": "string", "enum": [ "binary" ] } }, "required": [ "type" ], "title": "Binary", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/cloudflare-pipelines_TimestampField" }, { "properties": { "type": { "type": "string", "enum": [ "timestamp" ] } }, "required": [ "type" ], "type": "object" } ], "title": "Timestamp" }, { "properties": { "type": { "type": "string", "enum": [ "json" ] } }, "required": [ "type" ], "title": "Json", "type": "object" }, { "allOf": [ { "$ref": "#/components/schemas/cloudflare-pipelines_StructField" }, { "properties": { "type": { "type": "string", "enum": [ "struct" ] } }, "required": [ "type" ], "type": "object" } ], "title": "Struct" }, { "allOf": [ { "$ref": "#/components/schemas/cloudflare-pipelines_ListField" }, { "properties": { "type": { "type": "string", "enum": [ "list" ] } }, "required": [ "type" ], "type": "object" } ], "title": "List" } ] }, "cloudflare-pipelines_Format": { "description": "Defines the data format of the events.", "discriminator": { "propertyName": "type" }, "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/cloudflare-pipelines_JsonFormat" }, { "properties": { "type": { "type": "string", "enum": [ "json" ] } }, "required": [ "type" ], "type": "object" } ], "title": "Json" }, { "allOf": [ { "$ref": "#/components/schemas/cloudflare-pipelines_ParquetFormat" }, { "properties": { "type": { "type": "string", "enum": [ "parquet" ] } }, "required": [ "type" ], "type": "object" } ], "title": "Parquet" } ] }, "cloudflare-pipelines_JsonCompression": { "description": "Specifies the compression applied to JSON sink output.", "type": "string", "default": "uncompressed", "enum": [ "uncompressed", "gzip" ] }, "cloudflare-pipelines_JsonFormat": { "type": "object", "properties": { "decimal_encoding": { "$ref": "#/components/schemas/cloudflare-pipelines_DecimalEncoding" }, "timestamp_format": { "$ref": "#/components/schemas/cloudflare-pipelines_TimestampFormat" }, "unstructured": { "type": "boolean" } } }, "cloudflare-pipelines_ListField": { "type": "object", "properties": { "items": { "$ref": "#/components/schemas/cloudflare-pipelines_SourceField" } }, "required": [ "items" ] }, "cloudflare-pipelines_ParquetCompression": { "type": "string", "enum": [ "uncompressed", "snappy", "gzip", "zstd", "lz4" ] }, "cloudflare-pipelines_ParquetFormat": { "type": "object", "properties": { "compression": { "$ref": "#/components/schemas/cloudflare-pipelines_ParquetCompression" }, "row_group_bytes": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true } } }, "cloudflare-pipelines_PipelineEdge": { "type": "object", "properties": { "dest_id": { "type": "integer", "format": "int32", "minimum": 0 }, "edge_type": { "type": "string" }, "key_type": { "type": "string" }, "src_id": { "type": "integer", "format": "int32", "minimum": 0 }, "value_type": { "type": "string" } }, "required": [ "src_id", "dest_id", "key_type", "value_type", "edge_type" ] }, "cloudflare-pipelines_PipelineGraph": { "description": "Indicates the processing flow to implement the SQL.", "type": "object", "properties": { "edges": { "type": "array", "items": { "$ref": "#/components/schemas/cloudflare-pipelines_PipelineEdge" } }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/cloudflare-pipelines_PipelineNode" } } }, "required": [ "nodes", "edges" ] }, "cloudflare-pipelines_PipelineNode": { "type": "object", "properties": { "description": { "type": "string" }, "node_id": { "type": "integer", "format": "int32", "minimum": 0 }, "operator": { "type": "string" }, "parallelism": { "type": "integer", "format": "int32", "minimum": 0 } }, "required": [ "node_id", "operator", "description", "parallelism" ] }, "cloudflare-pipelines_SinkFormat": { "description": "Defines the output data format of a sink.", "discriminator": { "mapping": { "json": "#/components/schemas/cloudflare-pipelines_SinkJsonFormat", "parquet": "#/components/schemas/cloudflare-pipelines_SinkParquetFormat" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/cloudflare-pipelines_SinkJsonFormat" }, { "$ref": "#/components/schemas/cloudflare-pipelines_SinkParquetFormat" } ] }, "cloudflare-pipelines_SinkJsonFormat": { "allOf": [ { "$ref": "#/components/schemas/cloudflare-pipelines_JsonFormat" }, { "properties": { "compression": { "$ref": "#/components/schemas/cloudflare-pipelines_JsonCompression" }, "type": { "type": "string", "enum": [ "json" ] } }, "required": [ "type" ], "type": "object" } ], "title": "Json" }, "cloudflare-pipelines_SinkParquetFormat": { "allOf": [ { "$ref": "#/components/schemas/cloudflare-pipelines_ParquetFormat" }, { "properties": { "type": { "type": "string", "enum": [ "parquet" ] } }, "required": [ "type" ], "type": "object" } ], "title": "Parquet" }, "cloudflare-pipelines_SourceField": { "allOf": [ { "$ref": "#/components/schemas/cloudflare-pipelines_FieldType" }, { "properties": { "metadata_key": { "type": "string", "nullable": true }, "name": { "type": "string" }, "required": { "type": "boolean" }, "sql_name": { "type": "string" } }, "required": [ "name" ], "type": "object" } ] }, "cloudflare-pipelines_StructField": { "type": "object", "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/cloudflare-pipelines_SourceField" } }, "name": { "type": "string", "nullable": true } }, "required": [ "fields" ] }, "cloudflare-pipelines_TimestampField": { "type": "object", "properties": { "unit": { "$ref": "#/components/schemas/cloudflare-pipelines_TimestampUnit" } } }, "cloudflare-pipelines_TimestampFormat": { "type": "string", "enum": [ "rfc3339", "unix_millis" ] }, "cloudflare-pipelines_TimestampUnit": { "type": "string", "enum": [ "second", "millisecond", "microsecond", "nanosecond" ] }, "cloudflare-pipelines_r2Table": { "type": "object", "properties": { "account_id": { "description": "Cloudflare Account ID for the bucket", "type": "string", "title": "Account ID" }, "bucket": { "description": "R2 Bucket to write to", "type": "string", "title": "Bucket" }, "credentials": { "type": "object", "additionalProperties": false, "properties": { "access_key_id": { "description": "Cloudflare Account ID for the bucket", "type": "string", "format": "var-str", "title": "Access Key ID" }, "secret_access_key": { "description": "Cloudflare Account ID for the bucket", "type": "string", "format": "var-str", "title": "Access Key ID", "x-sensitive": true } }, "required": [ "access_key_id", "secret_access_key" ], "title": "R2 Credentials" }, "file_naming": { "description": "Controls filename prefix/suffix and strategy.", "type": "object", "additionalProperties": false, "properties": { "prefix": { "description": "The prefix to use in file name. i.e prefix-.parquet", "type": "string", "title": "Filename Prefix" }, "strategy": { "description": "Filename generation strategy.", "type": "string", "enum": [ "serial", "uuid", "uuid_v7", "ulid" ], "title": "Filename Strategy" }, "suffix": { "description": "This will overwrite the default file suffix. i.e .parquet, use with caution", "type": "string", "title": "Filename Suffix" } }, "title": "File Naming" }, "jurisdiction": { "description": "Jurisdiction this bucket is hosted in", "type": "string", "title": "Jurisdiction" }, "partitioning": { "description": "Data-layout partitioning for sinks.", "type": "object", "additionalProperties": false, "properties": { "time_pattern": { "description": "The pattern of the date string", "type": "string", "example": "year=%Y/month=%m/day=%d/hour=%H", "title": "Time Partition Pattern" } }, "title": "Partitioning Configuration" }, "path": { "description": "Subpath within the bucket to write to", "type": "string", "title": "Path" }, "rolling_policy": { "description": "Rolling policy for file sinks (when & why to close a file and open a new one).", "type": "object", "additionalProperties": false, "properties": { "file_size_bytes": { "description": "Files will be rolled after reaching this number of bytes", "type": "integer", "format": "uint64", "minimum": 0, "title": "File Size" }, "inactivity_seconds": { "description": "Number of seconds of inactivity to wait before rolling over to a new file", "type": "integer", "format": "uint64", "minimum": 1, "title": "Inactivity Seconds" }, "interval_seconds": { "description": "Number of seconds to wait before rolling over to a new file", "type": "integer", "format": "uint64", "minimum": 1, "title": "Interval Seconds" } }, "title": "File Rolling Policy" } }, "additionalProperties": false, "required": [ "account_id", "bucket", "credentials" ], "title": "R2 Sink" }, "cloudflare-pipelines_r2TablePublic": { "description": "R2 Sink public configuration.", "type": "object", "properties": { "account_id": { "description": "Cloudflare Account ID for the bucket", "type": "string", "title": "Account ID" }, "bucket": { "description": "R2 Bucket to write to", "type": "string", "title": "Bucket" }, "file_naming": { "description": "Controls filename prefix/suffix and strategy.", "type": "object", "additionalProperties": false, "properties": { "prefix": { "description": "The prefix to use in file name. i.e prefix-.parquet", "type": "string", "title": "Filename Prefix" }, "strategy": { "description": "Filename generation strategy.", "type": "string", "enum": [ "serial", "uuid", "uuid_v7", "ulid" ], "title": "Filename Strategy" }, "suffix": { "description": "This will overwrite the default file suffix. i.e .parquet, use with caution", "type": "string", "title": "Filename Suffix" } }, "title": "File Naming" }, "jurisdiction": { "description": "Jurisdiction this bucket is hosted in", "type": "string", "title": "Jurisdiction" }, "partitioning": { "description": "Data-layout partitioning for sinks.", "type": "object", "additionalProperties": false, "properties": { "time_pattern": { "description": "The pattern of the date string", "type": "string", "example": "year=%Y/month=%m/day=%d/hour=%H", "title": "Time Partition Pattern" } }, "title": "Partitioning Configuration" }, "path": { "description": "Subpath within the bucket to write to", "type": "string", "title": "Path" }, "rolling_policy": { "description": "Rolling policy for file sinks (when & why to close a file and open a new one).", "type": "object", "additionalProperties": false, "properties": { "file_size_bytes": { "description": "Files will be rolled after reaching this number of bytes", "type": "integer", "format": "uint64", "minimum": 0, "title": "File Size" }, "inactivity_seconds": { "description": "Number of seconds of inactivity to wait before rolling over to a new file", "type": "integer", "format": "uint64", "minimum": 1, "title": "Inactivity Seconds" }, "interval_seconds": { "description": "Number of seconds to wait before rolling over to a new file", "type": "integer", "format": "uint64", "minimum": 1, "title": "Interval Seconds" } }, "title": "File Rolling Policy" } }, "additionalProperties": false, "required": [ "account_id", "bucket" ], "title": "R2 Sink Public" }, "cloudflare-pipelines_r2_data_catalogTable": { "description": "R2 Data Catalog Sink", "type": "object", "properties": { "account_id": { "description": "Cloudflare Account ID", "type": "string", "format": "uri", "example": "6791973bbe876d621f9e557f891e90b3" }, "bucket": { "description": "The R2 Bucket that hosts this catalog", "type": "string", "example": "my-bucket" }, "namespace": { "description": "Table namespace", "type": "string", "title": "Namespace" }, "rolling_policy": { "description": "Rolling policy for file sinks (when & why to close a file and open a new one).", "type": "object", "additionalProperties": false, "properties": { "file_size_bytes": { "description": "Files will be rolled after reaching this number of bytes", "type": "integer", "format": "uint64", "minimum": 0, "title": "File Size" }, "inactivity_seconds": { "description": "Number of seconds of inactivity to wait before rolling over to a new file", "type": "integer", "format": "uint64", "minimum": 1, "title": "Inactivity Seconds" }, "interval_seconds": { "description": "Number of seconds to wait before rolling over to a new file", "type": "integer", "format": "uint64", "minimum": 1, "title": "Interval Seconds" } }, "title": "File Rolling Policy" }, "table_name": { "description": "Table name", "type": "string", "title": "Table Name" }, "token": { "description": "Authentication token", "type": "string", "format": "var-str", "example": "\"asdfkj2h34kjhkj\"", "x-sensitive": true } }, "additionalProperties": false, "required": [ "account_id", "bucket", "token", "table_name" ], "title": "R2DataCatalogSinkTable" }, "cloudflare-pipelines_r2_data_catalogTablePublic": { "description": "R2 Data Catalog Sink public configuration.", "type": "object", "properties": { "account_id": { "description": "Cloudflare Account ID", "type": "string", "format": "uri", "example": "6791973bbe876d621f9e557f891e90b3" }, "bucket": { "description": "The R2 Bucket that hosts this catalog", "type": "string", "example": "my-bucket" }, "namespace": { "description": "Table namespace", "type": "string", "title": "Namespace" }, "rolling_policy": { "description": "Rolling policy for file sinks (when & why to close a file and open a new one).", "type": "object", "additionalProperties": false, "properties": { "file_size_bytes": { "description": "Files will be rolled after reaching this number of bytes", "type": "integer", "format": "uint64", "minimum": 0, "title": "File Size" }, "inactivity_seconds": { "description": "Number of seconds of inactivity to wait before rolling over to a new file", "type": "integer", "format": "uint64", "minimum": 1, "title": "Inactivity Seconds" }, "interval_seconds": { "description": "Number of seconds to wait before rolling over to a new file", "type": "integer", "format": "uint64", "minimum": 1, "title": "Interval Seconds" } }, "title": "File Rolling Policy" }, "table_name": { "description": "Table name", "type": "string", "title": "Table Name" } }, "additionalProperties": false, "required": [ "account_id", "bucket", "table_name" ], "title": "R2DataCatalogSinkTablePublic" }, "cloudflare-pipelines_worker-pipelines-common-success": { "description": "Indicates whether the API call was successful.", "type": "boolean", "example": true }, "cloudflare-pipelines_workers-pipelines-account-id": { "description": "Specifies the public ID of the account.", "type": "string", "example": "0123105f4ecef8ad9ca31a8372d0c353" }, "cloudflare-pipelines_workers-pipelines-pipeline": { "description": "[DEPRECATED] Describes the configuration of a pipeline. Use the new streams/sinks/pipelines API instead.", "type": "object", "properties": { "destination": { "type": "object", "properties": { "batch": { "type": "object", "properties": { "max_bytes": { "description": "Specifies rough maximum size of files.", "type": "integer", "default": 100000000, "maximum": 100000000, "minimum": 1000 }, "max_duration_s": { "description": "Specifies duration to wait to aggregate batches files.", "type": "number", "default": 300, "maximum": 300, "minimum": 0.25 }, "max_rows": { "description": "Specifies rough maximum number of rows per file.", "type": "integer", "default": 10000000, "maximum": 10000000, "minimum": 100 } }, "required": [ "max_rows", "max_bytes", "max_duration_s" ] }, "compression": { "type": "object", "properties": { "type": { "description": "Specifies the desired compression algorithm and format.", "type": "string", "example": "gzip", "default": "gzip", "enum": [ "none", "gzip", "deflate" ] } }, "required": [ "type" ] }, "format": { "description": "Specifies the format of data to deliver.", "type": "string", "enum": [ "json" ] }, "path": { "type": "object", "example": { "bucket": "bucket", "prefix": "base" }, "properties": { "bucket": { "description": "Specifies the R2 Bucket to store files.", "type": "string", "example": "bucket" }, "filename": { "description": "Specifies the name pattern to for individual data files.", "example": "${slug}${extension}", "allOf": [ { "type": "string" }, { "type": "string" } ] }, "filepath": { "description": "Specifies the name pattern for directory.", "type": "string", "example": "${date}/${hour}" }, "prefix": { "description": "Specifies the base directory within the bucket.", "type": "string", "example": "base" } }, "required": [ "bucket" ] }, "type": { "description": "Specifies the type of destination.", "type": "string", "enum": [ "r2" ] } }, "required": [ "type", "format", "batch", "compression", "path" ] }, "endpoint": { "description": "Indicates the endpoint URL to send traffic.", "type": "string", "example": "https://123f8a8258064ed892a347f173372359.pipelines.cloudflare.com" }, "id": { "description": "Specifies the pipeline identifier.", "type": "string", "example": "123f8a8258064ed892a347f173372359" }, "name": { "description": "Defines the name of the pipeline.", "type": "string", "example": "sample_pipeline", "maxLength": 128, "minLength": 1 }, "source": { "type": "array", "items": { "discriminator": { "mapping": { "binding": "#/components/schemas/cloudflare-pipelines_workers_pipelines_binding_source", "http": "#/components/schemas/cloudflare-pipelines_workers_pipelines_http_source" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/cloudflare-pipelines_workers_pipelines_http_source" }, { "$ref": "#/components/schemas/cloudflare-pipelines_workers_pipelines_binding_source" } ] }, "minItems": 1 }, "version": { "description": "Indicates the version number of last saved configuration.", "type": "number", "example": 2 } }, "deprecated": true, "required": [ "name", "source", "destination", "id", "version", "endpoint" ] }, "cloudflare-pipelines_workers-pipelines-pipeline-id": { "description": "Specifies the public ID of the pipeline.", "type": "string", "example": "043e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "minLength": 32 }, "cloudflare-pipelines_workers-pipelines-sink-id": { "description": "Specifies the publid ID of the sink.", "type": "string", "example": "0223105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "minLength": 32 }, "cloudflare-pipelines_workers-pipelines-stream-id": { "description": "Specifies the public ID of the stream.", "type": "string", "example": "033e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "minLength": 32 }, "cloudflare-pipelines_workers_pipelines_binding_source": { "description": "[DEPRECATED] Worker binding source configuration. Use the new streams API instead.", "type": "object", "properties": { "format": { "description": "Specifies the format of source data.", "type": "string", "enum": [ "json" ] }, "type": { "type": "string" } }, "deprecated": true, "required": [ "type", "format" ] }, "cloudflare-pipelines_workers_pipelines_http_source": { "description": "[DEPRECATED] HTTP source configuration. Use the new streams API instead.", "type": "object", "properties": { "authentication": { "description": "Specifies whether authentication is required to send to this pipeline via HTTP.", "type": "boolean" }, "cors": { "type": "object", "properties": { "origins": { "description": "Specifies allowed origins to allow Cross Origin HTTP Requests.", "type": "array", "items": { "type": "string" }, "example": [ "*" ], "maxItems": 5 } } }, "format": { "description": "Specifies the format of source data.", "type": "string", "enum": [ "json" ] }, "type": { "type": "string" } }, "deprecated": true, "required": [ "type", "format" ] }, "cloudforce-one-events_ArticleTagDiagnosticJsonValue": { "oneOf": [ { "additionalProperties": { "$ref": "#/components/schemas/cloudforce-one-events_ArticleTagDiagnosticJsonValue" }, "type": "object" }, { "items": { "$ref": "#/components/schemas/cloudforce-one-events_ArticleTagDiagnosticJsonValue" }, "type": "array" }, { "nullable": true, "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "cloudforce-one-events_FieldDefinition": { "type": "object", "properties": { "allowedValues": { "type": "array", "items": { "type": "string" }, "example": [ "low", "medium", "high", "critical" ] }, "annotations": { "type": "object", "additionalProperties": false, "properties": { "confidence": { "type": "boolean" }, "tlp": { "type": "boolean" } } }, "deprecated": { "description": "Marks a field as unavailable for new values while retaining its definition for historical values.", "type": "boolean" }, "deprecatedValues": { "description": "Enum values unavailable for new writes but retained in allowedValues for historical display.", "type": "array", "items": { "type": "string" } }, "element": { "description": "Nested FieldDefinition describing the element type of an array field. Required when kind is 'array'. See FieldDefinition (recursive).", "type": "object", "additionalProperties": true, "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-events_FieldDefinition" } ] }, "enforcement": { "type": "string", "enum": [ "error", "warn", "off" ] }, "format": { "type": "string", "enum": [ "date", "url", "duration", "country" ] }, "key": { "type": "string", "example": "family", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,63}$" }, "kind": { "type": "string", "example": "string", "enum": [ "string", "number", "enum", "date", "array", "object" ] }, "label": { "type": "string", "example": "Attacker Name", "maxLength": 128, "minLength": 1 }, "maxLength": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "numberConstraint": { "type": "object", "additionalProperties": false, "properties": { "integer": { "type": "boolean" }, "max": { "type": "number" }, "min": { "type": "number" } } }, "properties": { "description": "Map of property key to FieldDefinition for object fields. Required when kind is 'object'. See FieldDefinition (recursive).", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/cloudforce-one-events_FieldDefinition" } }, "required": { "type": "boolean" } }, "additionalProperties": false, "required": [ "key", "kind" ] }, "cloudforce-one-events_HydratedEntity": { "description": "Hydrated event, indicator, or tag entity.", "type": "object", "additionalProperties": true }, "cloudforce-one-events_RelationshipEdge": { "type": "object", "properties": { "confidence": { "description": "Confidence score 0–100, or null.", "type": "integer", "maximum": 100, "minimum": 0, "nullable": true }, "createdAt": { "description": "ISO 8601 creation timestamp.", "type": "string" }, "datasetId": { "description": "Dataset the relationship belongs to.", "type": "string" }, "entityId": { "description": "UUID of the related entity (other end).", "type": "string" }, "entityType": { "description": "Type of the related entity.", "type": "string", "enum": [ "event", "indicator", "tag" ] }, "metadata": { "description": "Arbitrary JSON metadata, or null.", "type": "object", "additionalProperties": true, "nullable": true }, "relationshipUuid": { "description": "Relationship UUID (use for PATCH/DELETE).", "type": "string", "format": "uuid" }, "type": { "description": "Relationship type.", "type": "string" }, "updatedAt": { "description": "ISO 8601 last-update timestamp.", "type": "string" } }, "required": [ "relationshipUuid", "entityId", "entityType", "type", "confidence", "metadata", "datasetId", "createdAt", "updatedAt" ] }, "cloudforce-one-port-scan-api_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/cloudforce-one-port-scan-api_messages" }, "messages": { "$ref": "#/components/schemas/cloudforce-one-port-scan-api_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "cloudforce-one-port-scan-api_api-response-common-failure": { "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-port-scan-api_api-response-common" }, { "properties": { "errors": { "type": "object", "example": { "code": 10433, "message": "request error" } }, "success": { "type": "boolean", "example": false } } } ] }, "cloudforce-one-port-scan-api_frequency": { "description": "Defines the number of days between each scan (0 = One-off scan).", "type": "number", "example": 7, "title": "Frequency" }, "cloudforce-one-port-scan-api_ips": { "description": "Defines a list of IP addresses or CIDR blocks to scan. The maximum number of total IP addresses allowed is 5000.", "type": "array", "items": { "description": "Defines a list of IP addresses or CIDR blocks to scan. The maximum number of total IP addresses allowed is 5000.", "type": "string" }, "example": [ "1.1.1.1", "2606:4700:4700::1111" ], "title": "IP List" }, "cloudforce-one-port-scan-api_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "cloudforce-one-port-scan-api_port": { "type": "object", "properties": { "number": { "type": "number", "example": 8080 }, "proto": { "type": "string", "example": "tcp" }, "status": { "type": "string", "example": "open" } }, "required": [ "account_id", "ips", "frequency" ], "title": "Port" }, "cloudforce-one-port-scan-api_ports": { "description": "Defines a list of ports to scan. Valid values are:\"default\", \"all\", or a comma-separated list of ports or range of ports (e.g. [\"1-80\", \"443\"]). \"default\" scans the 100 most commonly open ports.", "type": "array", "items": { "description": "Defines a list of ports to scan. Valid values are:\"default\", \"all\", or a comma-separated list of ports or range of ports (e.g. [\"1-80\", \"443\"]). \"default\" scans the 100 most commonly open ports.", "type": "string" }, "example": [ "default" ], "title": "Port List" }, "cloudforce-one-port-scan-api_scan-config": { "type": "object", "properties": { "account_id": { "type": "string", "example": "abcd1234abcd1234abcd1234abcd1234" }, "frequency": { "$ref": "#/components/schemas/cloudforce-one-port-scan-api_frequency" }, "id": { "description": "Defines the Config ID.", "type": "string", "example": "uuid" }, "ips": { "$ref": "#/components/schemas/cloudforce-one-port-scan-api_ips" }, "ports": { "$ref": "#/components/schemas/cloudforce-one-port-scan-api_ports" } }, "required": [ "id", "account_id", "ips", "frequency", "ports" ], "title": "Config" }, "cloudforce-one-requests_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/cloudforce-one-requests_messages" }, "messages": { "$ref": "#/components/schemas/cloudforce-one-requests_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "cloudforce-one-requests_api-response-common-failure": { "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_api-response-common" }, { "properties": { "errors": { "type": "object", "properties": { "code": { "type": "integer", "example": 10433 }, "message": { "type": "string", "example": "request error" } } }, "success": { "type": "boolean", "example": false } }, "type": "object" } ] }, "cloudforce-one-requests_asset-content": { "description": "Asset file to upload.", "type": "string", "example": "@/Users/me/example.docx" }, "cloudforce-one-requests_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 }, "cloudforce-one-requests_labels": { "description": "List of labels.", "type": "array", "items": { "type": "string" }, "example": [ "DoS", "CVE" ], "title": "Labels", "x-auditable": true }, "cloudforce-one-requests_message-content": { "description": "Content of message.", "type": "string", "example": "Can you elaborate on the type of DoS that occurred?", "x-auditable": true }, "cloudforce-one-requests_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "cloudforce-one-requests_priority": { "type": "string", "enum": [ "routine", "high", "urgent" ], "title": "Request Priority", "x-auditable": true }, "cloudforce-one-requests_priority-edit": { "type": "object", "properties": { "labels": { "$ref": "#/components/schemas/cloudforce-one-requests_labels" }, "priority": { "description": "Priority.", "type": "integer", "example": 1, "x-auditable": true }, "requirement": { "description": "Requirement.", "type": "string", "example": "DoS attacks carried out by CVEs", "x-auditable": true }, "tlp": { "$ref": "#/components/schemas/cloudforce-one-requests_tlp" } }, "required": [ "labels", "priority", "requirement", "tlp" ], "title": "Priority Editable Attributes" }, "cloudforce-one-requests_priority-item": { "type": "object", "properties": { "created": { "description": "Priority creation time.", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_time" } ] }, "id": { "$ref": "#/components/schemas/cloudforce-one-requests_uuid" }, "labels": { "$ref": "#/components/schemas/cloudforce-one-requests_labels" }, "priority": { "description": "Priority.", "type": "integer", "example": 1, "x-auditable": true }, "requirement": { "description": "Requirement.", "type": "string", "example": "DoS attacks carried out by CVEs", "x-auditable": true }, "tlp": { "$ref": "#/components/schemas/cloudforce-one-requests_tlp" }, "updated": { "description": "Priority last updated time.", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_time" } ] } }, "required": [ "id", "created", "updated", "labels", "priority", "requirement", "tlp" ], "title": "Priority Item" }, "cloudforce-one-requests_priority-list": { "type": "object", "properties": { "page": { "description": "Page number of results.", "type": "integer" }, "per_page": { "description": "Number of results per page.", "type": "integer", "example": 10 } }, "required": [ "page", "per_page" ], "title": "Priority List Parameters" }, "cloudforce-one-requests_quota": { "type": "object", "properties": { "anniversary_date": { "description": "Anniversary date is when annual quota limit is refreshed.", "example": "2022-04-01T00:00:00Z", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_time" } ] }, "quarter_anniversary_date": { "description": "Quarter anniversary date is when quota limit is refreshed each quarter.", "example": "2022-04-01T00:00:00Z", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_time" } ] }, "quota": { "description": "Tokens for the quarter.", "type": "integer", "example": 120, "x-auditable": true }, "remaining": { "description": "Tokens remaining for the quarter.", "type": "integer", "example": 64, "x-auditable": true } }, "title": "Quota" }, "cloudforce-one-requests_request-asset-edit": { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/cloudforce-one-requests_asset-content" } }, "title": "Request Asset Editable Attributes" }, "cloudforce-one-requests_request-asset-item": { "type": "object", "properties": { "created": { "description": "Defines the asset creation time.", "example": "2022-01-01T00:00:00Z", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_time" } ] }, "description": { "description": "Asset description.", "type": "string", "example": "example description", "x-auditable": true }, "file_type": { "description": "Asset file type.", "type": "string", "example": "docx", "x-auditable": true }, "id": { "description": "Asset ID.", "type": "integer", "x-auditable": true }, "name": { "description": "Asset name.", "type": "string", "example": "example.docx", "x-auditable": true } }, "required": [ "id", "name" ], "title": "Request Asset Item" }, "cloudforce-one-requests_request-asset-list": { "type": "object", "properties": { "page": { "description": "Page number of results.", "type": "integer" }, "per_page": { "description": "Number of results per page.", "type": "integer", "example": 10 } }, "required": [ "page", "per_page" ], "title": "Request Asset List Parameters" }, "cloudforce-one-requests_request-constants": { "type": "object", "properties": { "priority": { "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one-requests_priority" }, "example": [ "routine", "high", "urgent" ] }, "status": { "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one-requests_request-status" }, "example": [ "open", "accepted", "reported", "approved", "completed", "declined" ] }, "tlp": { "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one-requests_tlp" }, "example": [ "clear", "green", "amber", "amber-strict", "red" ] } }, "title": "Request Constants" }, "cloudforce-one-requests_request-content": { "description": "Request content.", "type": "string", "example": "What regions were most effected by the recent DoS?" }, "cloudforce-one-requests_request-edit": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/cloudforce-one-requests_request-content" }, "priority": { "description": "Priority for analyzing the request.", "type": "string", "example": "routine", "x-auditable": true }, "request_type": { "$ref": "#/components/schemas/cloudforce-one-requests_request-type" }, "summary": { "$ref": "#/components/schemas/cloudforce-one-requests_request-summary" }, "tlp": { "$ref": "#/components/schemas/cloudforce-one-requests_tlp" } }, "title": "Request Editable Parameters" }, "cloudforce-one-requests_request-item": { "type": "object", "properties": { "completed": { "$ref": "#/components/schemas/cloudforce-one-requests_time" }, "content": { "$ref": "#/components/schemas/cloudforce-one-requests_request-content" }, "created": { "$ref": "#/components/schemas/cloudforce-one-requests_time" }, "id": { "$ref": "#/components/schemas/cloudforce-one-requests_uuid" }, "message_tokens": { "description": "Tokens for the request messages.", "type": "integer", "example": 1, "x-auditable": true }, "priority": { "$ref": "#/components/schemas/cloudforce-one-requests_time" }, "readable_id": { "$ref": "#/components/schemas/cloudforce-one-requests_request-readable-id" }, "request": { "$ref": "#/components/schemas/cloudforce-one-requests_request-type" }, "status": { "$ref": "#/components/schemas/cloudforce-one-requests_request-status" }, "summary": { "$ref": "#/components/schemas/cloudforce-one-requests_request-summary" }, "tlp": { "$ref": "#/components/schemas/cloudforce-one-requests_tlp" }, "tokens": { "description": "Tokens for the request.", "type": "integer", "example": 16, "x-auditable": true }, "updated": { "$ref": "#/components/schemas/cloudforce-one-requests_time" } }, "required": [ "id", "created", "updated", "content", "priority", "request", "summary", "tlp" ], "title": "Request Item" }, "cloudforce-one-requests_request-list": { "type": "object", "properties": { "completed_after": { "description": "Retrieve requests completed after this time.", "example": "2022-01-01T00:00:00Z", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_time" } ] }, "completed_before": { "description": "Retrieve requests completed before this time.", "example": "2024-01-01T00:00:00Z", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_time" } ] }, "created_after": { "description": "Retrieve requests created after this time.", "example": "2022-01-01T00:00:00Z", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_time" } ] }, "created_before": { "description": "Retrieve requests created before this time.", "example": "2024-01-01T00:00:00Z", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_time" } ] }, "page": { "description": "Page number of results.", "type": "integer" }, "per_page": { "description": "Number of results per page.", "type": "integer", "example": 10 }, "request_type": { "$ref": "#/components/schemas/cloudforce-one-requests_request-type" }, "sort_by": { "description": "Field to sort results by.", "type": "string", "example": "created" }, "sort_order": { "description": "Sort order (asc or desc).", "type": "string", "enum": [ "asc", "desc" ] }, "status": { "$ref": "#/components/schemas/cloudforce-one-requests_request-status" } }, "required": [ "page", "per_page" ], "title": "Request List Parameters" }, "cloudforce-one-requests_request-list-item": { "type": "object", "properties": { "completed": { "description": "Request completion time.", "example": "2024-01-01T00:00:00Z", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_time" } ] }, "created": { "description": "Request creation time.", "example": "2022-04-01T00:00:00Z", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_time" } ] }, "id": { "$ref": "#/components/schemas/cloudforce-one-requests_uuid" }, "message_tokens": { "description": "Tokens for the request messages.", "type": "integer", "example": 16, "x-auditable": true }, "priority": { "$ref": "#/components/schemas/cloudforce-one-requests_priority" }, "readable_id": { "$ref": "#/components/schemas/cloudforce-one-requests_request-readable-id" }, "request": { "$ref": "#/components/schemas/cloudforce-one-requests_request-type" }, "status": { "$ref": "#/components/schemas/cloudforce-one-requests_request-status" }, "summary": { "$ref": "#/components/schemas/cloudforce-one-requests_request-summary" }, "tlp": { "$ref": "#/components/schemas/cloudforce-one-requests_tlp" }, "tokens": { "description": "Tokens for the request.", "type": "integer", "x-auditable": true }, "updated": { "description": "Request last updated time.", "example": "2022-04-01T00:00:00Z", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_time" } ] } }, "required": [ "id", "created", "updated", "priority", "request", "summary", "tlp" ], "title": "Request List Item" }, "cloudforce-one-requests_request-message-edit": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/cloudforce-one-requests_message-content" } }, "title": "Request Message Editable Attributes" }, "cloudforce-one-requests_request-message-item": { "type": "object", "properties": { "author": { "description": "Author of message.", "type": "string", "example": "user@domain.com", "x-auditable": true }, "content": { "$ref": "#/components/schemas/cloudforce-one-requests_message-content" }, "created": { "description": "Defines the message creation time.", "example": "2022-01-01T00:00:00Z", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_time" } ] }, "id": { "description": "Message ID.", "type": "integer", "x-auditable": true }, "is_follow_on_request": { "description": "Whether the message is a follow-on request.", "type": "boolean", "x-auditable": true }, "updated": { "description": "Defines the message last updated time.", "example": "2022-01-01T00:00:00Z", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_time" } ] } }, "required": [ "id", "updated", "content", "author", "is_follow_on_request" ], "title": "Request Message Item" }, "cloudforce-one-requests_request-message-list": { "type": "object", "properties": { "after": { "description": "Retrieve mes ges created after this time.", "example": "2022-01-01T00:00:Z", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_time" } ] }, "before": { "description": "Retrieve messages created before this time.", "example": "2024-01-01T00:00:00Z", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-requests_time" } ] }, "page": { "description": "Page number of results.", "type": "integer" }, "per_page": { "description": "Number of results per page.", "type": "integer", "example": 10 }, "sort_by": { "description": "Field to sort results by.", "type": "string", "example": "created" }, "sort_order": { "description": "Sort order (asc or desc).", "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "page", "per_page" ], "title": "Request Message List Parameters" }, "cloudforce-one-requests_request-readable-id": { "description": "Readable Request ID.", "type": "string", "example": "RFI-2022-000001", "title": "Request Readable ID", "x-auditable": true }, "cloudforce-one-requests_request-status": { "description": "Request Status.", "type": "string", "enum": [ "open", "accepted", "reported", "approved", "completed", "declined" ], "title": "Request Status", "x-auditable": true }, "cloudforce-one-requests_request-summary": { "description": "Brief description of the request.", "type": "string", "example": "DoS attack", "x-auditable": true }, "cloudforce-one-requests_request-type": { "description": "Requested information from request.", "type": "string", "example": "Victomology", "x-auditable": true }, "cloudforce-one-requests_request-types": { "type": "array", "items": { "description": "Request Types.", "type": "string", "x-auditable": true }, "example": [ "Indicators of Compromise", "Victomology" ], "title": "Request Types" }, "cloudforce-one-requests_time": { "type": "string", "format": "date-time", "example": "2022-04-01T05:20:00Z", "x-auditable": true }, "cloudforce-one-requests_tlp": { "description": "The CISA defined Traffic Light Protocol (TLP).", "type": "string", "enum": [ "clear", "amber", "amber-strict", "green", "red" ], "title": "TLP", "x-auditable": true }, "cloudforce-one-requests_uuid": { "description": "UUID.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36 }, "cloudforce-one-whois_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/cloudforce-one-whois_schemas-messages" }, "messages": { "$ref": "#/components/schemas/cloudforce-one-whois_schemas-messages" }, "success": { "description": "Returns a boolean for the success/failure of the API call.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "cloudforce-one-whois_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-whois_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-whois_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Returns a boolean for the success/failure of the API call.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "cloudforce-one-whois_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-whois_api-response-common" } ] }, "cloudforce-one-whois_domain_name": { "type": "string", "example": "cloudflare.com" }, "cloudforce-one-whois_identifier": { "description": "Use to uniquely identify or reference the resource.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "cloudforce-one-whois_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "cloudforce-one-whois_schemas-messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "cloudforce-one-whois_schemas-single_response": { "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-whois_api-response-single" }, { "properties": { "result": { "allOf": [ { "$ref": "#/components/schemas/cloudforce-one-whois_whois" } ] } }, "type": "object" } ] }, "cloudforce-one-whois_whois": { "type": "object", "properties": { "administrative_city": { "type": "string" }, "administrative_country": { "type": "string" }, "administrative_email": { "type": "string" }, "administrative_fax": { "type": "string" }, "administrative_fax_ext": { "type": "string" }, "administrative_id": { "type": "string" }, "administrative_name": { "type": "string" }, "administrative_org": { "type": "string" }, "administrative_phone": { "type": "string" }, "administrative_phone_ext": { "type": "string" }, "administrative_postal_code": { "type": "string" }, "administrative_province": { "type": "string" }, "administrative_referral_url": { "type": "string" }, "administrative_street": { "type": "string" }, "billing_city": { "type": "string" }, "billing_country": { "type": "string" }, "billing_email": { "type": "string" }, "billing_fax": { "type": "string" }, "billing_fax_ext": { "type": "string" }, "billing_id": { "type": "string" }, "billing_name": { "type": "string" }, "billing_org": { "type": "string" }, "billing_phone": { "type": "string" }, "billing_phone_ext": { "type": "string" }, "billing_postal_code": { "type": "string" }, "billing_province": { "type": "string" }, "billing_referral_url": { "type": "string" }, "billing_street": { "type": "string" }, "created_date": { "type": "string", "format": "date-time", "example": "2009-02-17T22:07:54Z" }, "created_date_raw": { "type": "string", "example": "2009-02-17T22:07:54Z" }, "dnssec": { "type": "boolean", "example": true }, "domain": { "$ref": "#/components/schemas/cloudforce-one-whois_domain_name" }, "expiration_date": { "type": "string", "format": "date-time", "example": "2033-02-17T22:07:54Z" }, "expiration_date_raw": { "type": "string", "example": "2033-02-17T22:07:54Z" }, "extension": { "type": "string", "example": "com" }, "found": { "type": "boolean", "example": true }, "id": { "type": "string", "example": "1542998887_DOMAIN_COM-VRSN" }, "nameservers": { "type": "array", "items": { "type": "string" }, "example": [ "ns3.cloudflare.com", "ns4.cloudflare.com", "ns5.cloudflare.com", "ns6.cloudflare.com", "ns7.cloudflare.com" ] }, "punycode": { "type": "string", "example": "cloudflare.com" }, "registrant": { "type": "string" }, "registrant_city": { "type": "string" }, "registrant_country": { "type": "string" }, "registrant_email": { "type": "string" }, "registrant_fax": { "type": "string" }, "registrant_fax_ext": { "type": "string" }, "registrant_id": { "type": "string" }, "registrant_name": { "type": "string" }, "registrant_org": { "type": "string" }, "registrant_phone": { "type": "string" }, "registrant_phone_ext": { "type": "string" }, "registrant_postal_code": { "type": "string" }, "registrant_province": { "type": "string" }, "registrant_referral_url": { "type": "string" }, "registrant_street": { "type": "string" }, "registrar": { "type": "string", "example": "Cloudflare, Inc." }, "registrar_city": { "type": "string" }, "registrar_country": { "type": "string" }, "registrar_email": { "type": "string" }, "registrar_fax": { "type": "string" }, "registrar_fax_ext": { "type": "string" }, "registrar_id": { "type": "string" }, "registrar_name": { "type": "string" }, "registrar_org": { "type": "string" }, "registrar_phone": { "type": "string" }, "registrar_phone_ext": { "type": "string" }, "registrar_postal_code": { "type": "string" }, "registrar_province": { "type": "string" }, "registrar_referral_url": { "type": "string" }, "registrar_street": { "type": "string" }, "status": { "type": "array", "items": { "type": "string" }, "example": [ "clientdeleteprohibited", "clienttransferprohibited", "clientupdateprohibited", "serverdeleteprohibited", "servertransferprohibited", "serverupdateprohibited" ] }, "technical_city": { "type": "string" }, "technical_country": { "type": "string" }, "technical_email": { "type": "string" }, "technical_fax": { "type": "string" }, "technical_fax_ext": { "type": "string" }, "technical_id": { "type": "string" }, "technical_name": { "type": "string" }, "technical_org": { "type": "string" }, "technical_phone": { "type": "string" }, "technical_phone_ext": { "type": "string" }, "technical_postal_code": { "type": "string" }, "technical_province": { "type": "string" }, "technical_referral_url": { "type": "string" }, "technical_street": { "type": "string" }, "updated_date": { "type": "string", "format": "date-time", "example": "2024-01-09T16:45:28Z" }, "updated_date_raw": { "type": "string", "example": "2024-01-09T16:45:28Z" }, "whois_server": { "type": "string", "example": "whois.cloudflare.com" } }, "required": [ "found", "domain", "dnssec", "extension", "nameservers", "punycode", "registrar", "registrant" ] }, "cloudforce-one_AccountExemptions": { "type": "object", "properties": { "namespace": { "type": "array", "items": { "type": "string" }, "example": [ "^test-.*$" ] }, "tag_match": { "type": "array", "items": { "type": "string" }, "example": [ "^staging-.*$" ] }, "worker_name": { "type": "array", "items": { "type": "string" }, "example": [ "^demo-.*$" ] } }, "required": [ "namespace", "tag_match", "worker_name" ] }, "cloudforce-one_ApprovalConflictResponse": { "type": "object", "properties": { "approval_id": { "type": "number", "example": 12345 }, "code": { "type": "string", "example": "approval_pending", "enum": [ "approval_pending" ] }, "error": { "type": "string", "example": "An approval is already pending for this rule." } }, "required": [ "error", "code", "approval_id" ] }, "cloudforce-one_ApprovalPendingResponse": { "type": "object", "properties": { "approval_id": { "type": "number", "example": 1 }, "message": { "type": "string", "example": "Rule creation pending approval" } }, "required": [ "approval_id", "message" ] }, "cloudforce-one_ApprovalProposedChanges": { "description": "Contains structured proposed rule changes, or null for unresolved persisted data.", "nullable": true, "oneOf": [ { "properties": { "content": { "type": "string" }, "created_at": { "type": "number" }, "created_by": { "type": "string" }, "description": { "type": "string" }, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "is_public": { "type": "boolean" }, "name": { "type": "string" }, "namespaces": { "type": "array", "items": { "type": "string" } }, "path": { "type": "string", "minLength": 1 }, "structured_source": { "type": "string", "nullable": true }, "sync_message": { "type": "string" }, "sync_source": { "type": "string" }, "type": { "type": "string", "enum": [ "create" ] } }, "required": [ "type", "id", "name", "path", "description", "namespaces", "is_public", "enabled", "created_by", "created_at" ], "type": "object" }, { "properties": { "content": { "type": "string" }, "description": { "type": "string" }, "enabled": { "type": "boolean" }, "is_public": { "type": "boolean" }, "name": { "type": "string" }, "namespaces": { "type": "array", "items": { "type": "string" } }, "path": { "type": "string", "minLength": 1 }, "structured_source": { "type": "string", "nullable": true }, "sync_message": { "type": "string" }, "sync_source": { "type": "string" }, "type": { "type": "string", "enum": [ "update" ] } }, "required": [ "type" ], "type": "object" }, { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sync_message": { "type": "string" }, "sync_source": { "type": "string" }, "type": { "type": "string", "enum": [ "delete" ] } }, "required": [ "type", "id", "name" ], "type": "object" } ] }, "cloudforce-one_CompilerWarning": { "type": "object", "properties": { "code": { "type": "string" }, "column": { "type": "integer" }, "footers": { "type": "array", "items": { "properties": { "level": { "type": "string" }, "text": { "type": "string" } }, "required": [ "level", "text" ], "type": "object" }, "default": [] }, "labels": { "type": "array", "items": { "properties": { "code_origin": { "type": "string", "nullable": true }, "column": { "type": "integer" }, "level": { "type": "string" }, "line": { "type": "integer" }, "span": { "type": "object", "properties": { "end": { "type": "integer" }, "start": { "type": "integer" } }, "required": [ "start", "end" ] }, "text": { "type": "string" } }, "required": [ "level", "code_origin", "line", "column", "span", "text" ], "type": "object" }, "default": [] }, "line": { "type": "integer" }, "text": { "type": "string" }, "title": { "type": "string" } }, "required": [ "code", "title", "text" ] }, "cloudforce-one_CreateRule": { "type": "object", "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one_RuleAction" } }, "commit_message": { "description": "Human-readable justification for this change. Required for internal-account submissions; optional for customer accounts and automated sync.", "type": "string", "example": "Add worker rule to catch bpb-panel variants.", "maxLength": 1000 }, "content": { "example": "rule example { condition: true }", "minLength": 1, "type": "string" }, "description": { "description": "Human-readable description of the rule. Auto-extracted from YARA meta if present.", "type": "string", "example": "Detects malicious proxy workers", "maxLength": 1000 }, "enabled": { "description": "Whether this rule is active for dice consumers.", "type": "boolean", "example": true, "default": true }, "is_public": { "description": "Whether this rule is visible to other internal accounts.", "type": "boolean", "example": false, "default": false, "x-auditable": true }, "meta": { "description": "Adds YARA meta entries to the rule's meta block and stores them in rule_meta alongside content metadata. Use valid YARA identifiers for keys; exclude 'name', 'enabled', and 'description'. You may repeat keys.", "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one_MetaInputEntry" }, "maxItems": 50 }, "name": { "type": "string", "example": "block-malicious-workers", "maxLength": 255, "minLength": 1, "x-auditable": true }, "namespaces": { "description": "Optional WfP deployment tags (customer rules only). Internal rules leave empty.", "type": "array", "items": { "maxLength": 255, "minLength": 1, "type": "string" }, "example": [], "default": [], "x-auditable": true }, "path": { "type": "string", "example": "yara/workers", "minLength": 1, "x-auditable": true } }, "required": [ "name", "path", "content" ] }, "cloudforce-one_DeleteAllResponse": { "type": "object", "properties": { "deleted": { "type": "number", "example": 10 } }, "required": [ "deleted" ] }, "cloudforce-one_DeleteRuleBody": { "type": "object", "properties": { "commit_message": { "description": "Human-readable justification for the deletion. Required for internal-account submissions; optional for customer accounts and automated sync.", "type": "string", "example": "Rule superseded by yara/workers/tighter-panel.yar.", "maxLength": 1000 } } }, "cloudforce-one_EditApprovalResponse": { "type": "object", "properties": { "approval": { "allOf": [ { "$ref": "#/components/schemas/cloudforce-one_PendingApproval" }, { "properties": { "current_rule": { "anyOf": [ { "$ref": "#/components/schemas/cloudforce-one_RulePreview" } ], "nullable": true } }, "type": "object" } ] } }, "required": [ "approval" ] }, "cloudforce-one_EmailRuleArrayCondition": { "type": "object", "properties": { "conditions": { "type": "array", "items": { "properties": { "operator": { "type": "string", "enum": [ "==", "!=", ">", ">=", "<", "<=", "contains", "matches" ] }, "subfield": { "type": "string", "maxLength": 128, "minLength": 1 }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "subfield", "operator", "value" ], "type": "object" }, "maxItems": 20, "minItems": 1 }, "field": { "type": "string", "maxLength": 256, "minLength": 1 }, "quantifier": { "type": "string", "default": "any", "enum": [ "any", "all" ] }, "type": { "type": "string", "enum": [ "array" ] } }, "required": [ "type", "field", "conditions" ] }, "cloudforce-one_EmailRuleCondition": { "discriminator": { "mapping": { "array": "#/components/schemas/cloudforce-one_EmailRuleArrayCondition", "group": "#/components/schemas/cloudforce-one_EmailRuleConditionGroup", "header": "#/components/schemas/cloudforce-one_EmailRuleHeaderCondition", "scalar": "#/components/schemas/cloudforce-one_EmailRuleScalarCondition" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/cloudforce-one_EmailRuleScalarCondition" }, { "$ref": "#/components/schemas/cloudforce-one_EmailRuleArrayCondition" }, { "$ref": "#/components/schemas/cloudforce-one_EmailRuleHeaderCondition" }, { "$ref": "#/components/schemas/cloudforce-one_EmailRuleConditionGroup" } ] }, "cloudforce-one_EmailRuleConditionGroup": { "description": "Nested condition groups support up to 10 levels of depth.", "type": "object", "properties": { "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one_EmailRuleCondition" }, "maxItems": 50, "minItems": 1 }, "operator": { "type": "string", "enum": [ "and", "or" ] }, "type": { "type": "string", "enum": [ "group" ] } }, "required": [ "type", "operator", "conditions" ] }, "cloudforce-one_EmailRuleHeaderCondition": { "type": "object", "properties": { "header_name": { "type": "string", "maxLength": 256, "minLength": 1 }, "match_type": { "type": "string", "enum": [ "any", "all", "first", "last", "count" ] }, "operator": { "type": "string", "enum": [ "==", "!=", ">", ">=", "<", "<=", "contains", "matches" ] }, "type": { "type": "string", "enum": [ "header" ] }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "type", "header_name", "match_type", "operator", "value" ] }, "cloudforce-one_EmailRuleScalarCondition": { "type": "object", "properties": { "field": { "type": "string", "maxLength": 256, "minLength": 1 }, "operator": { "type": "string", "enum": [ "==", "!=", ">", ">=", "<", "<=", "contains", "matches" ] }, "type": { "type": "string", "enum": [ "scalar" ] }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "type", "field", "operator", "value" ] }, "cloudforce-one_EmailRuleValidationResponse": { "type": "object", "properties": { "compiled_yara": { "type": "string" }, "error": { "type": "string" }, "valid": { "type": "boolean" } }, "required": [ "valid" ] }, "cloudforce-one_EmailRulesListResponse": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one_RulePreview" } }, "total": { "type": "number", "example": 100 } }, "required": [ "rules", "total" ] }, "cloudforce-one_ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "example": "Not found" } }, "required": [ "error" ] }, "cloudforce-one_ExemptionUpdateEntry": { "type": "object", "properties": { "new_pattern": { "type": "string", "example": "^test-.*$", "minLength": 1 }, "old_pattern": { "type": "string", "example": "^test-.*$", "minLength": 1 } }, "required": [ "old_pattern", "new_pattern" ] }, "cloudforce-one_MetaInputEntry": { "description": "A YARA meta entry. The server resolves its value type. The 'detection' key accepts MALICIOUS, SUSPICIOUS, SPAM, or SPOOF.", "type": "object", "properties": { "key": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "value": { "anyOf": [ { "maxLength": 10000, "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "key", "value" ] }, "cloudforce-one_PartialAccountExemptions": { "type": "object", "properties": { "namespace": { "type": "array", "items": { "example": "^test-.*$", "minLength": 1, "type": "string" } }, "tag_match": { "type": "array", "items": { "example": "^test-.*$", "minLength": 1, "type": "string" } }, "worker_name": { "type": "array", "items": { "example": "^test-.*$", "minLength": 1, "type": "string" } } }, "additionalProperties": false }, "cloudforce-one_PendingApproval": { "type": "object", "properties": { "audit_log_id": { "type": "number", "example": 1 }, "can_review": { "description": "Whether the authenticated user may approve or reject this pending change.", "type": "boolean", "example": true }, "cancelled_at": { "description": "Time at which the requester cancelled the approval.", "type": "number", "example": 1679529600000, "nullable": true, "x-auditable": true }, "cancelled_by": { "description": "Requester who cancelled the pending approval.", "type": "string", "example": "requester@example.com", "nullable": true, "x-auditable": true }, "change_description": { "type": "string", "example": "Updated rule content" }, "change_type": { "type": "string", "example": "create", "enum": [ "create", "update", "delete", "unresolved" ] }, "commit_message": { "description": "The requester supplies this human-readable justification with the change. Internal-account mutations require it; customer accounts and sync-originated changes may omit it.", "type": "string", "example": "Tighten regex to reduce false positives on legit CI workers.", "nullable": true }, "id": { "type": "number", "example": 12345, "x-auditable": true }, "proposed_changes": { "$ref": "#/components/schemas/cloudforce-one_ApprovalProposedChanges" }, "rejection_reason": { "description": "The reviewer may supply a reason when rejecting the change.", "type": "string", "example": "Narrow the hostname match to avoid false positives.", "nullable": true, "x-auditable": true }, "requested_at": { "type": "number", "example": 1679529600000, "x-auditable": true }, "requested_by": { "type": "string", "example": "user@example.com", "x-auditable": true }, "reviewed_at": { "type": "number", "example": 1679529600000, "nullable": true, "x-auditable": true }, "reviewed_by": { "type": "string", "example": "approver@example.com", "nullable": true, "x-auditable": true }, "reviewer_scope": { "description": "Review policy: general Nomos approvers for default; general approvers or Phishguard for email.", "type": "string", "example": "email", "enum": [ "default", "email", "unresolved" ] }, "revision_number": { "description": "Revision number within this approval request chain.", "type": "integer", "example": 2, "exclusiveMinimum": true, "minimum": 0 }, "rule_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "x-auditable": true }, "rule_name": { "type": "string", "example": "suspicious_email.yar" }, "source_account_id": { "description": "Customer account that owns this approval when returned by the aggregated email queue.", "type": "integer", "example": 12345678, "exclusiveMinimum": true, "minimum": 0 }, "status": { "type": "string", "example": "pending", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "superseded_by_approval_id": { "description": "Newer approval revision that replaced this approval.", "type": "number", "example": 12346, "nullable": true }, "supersedes_approval_id": { "description": "This approval replaces the referenced approval revision.", "type": "number", "example": 12344, "nullable": true } }, "required": [ "id", "rule_id", "rule_name", "audit_log_id", "requested_by", "requested_at", "change_description", "change_type", "proposed_changes", "status", "reviewed_by", "reviewed_at", "rejection_reason", "cancelled_by", "cancelled_at", "supersedes_approval_id", "superseded_by_approval_id", "revision_number", "commit_message", "reviewer_scope", "can_review" ] }, "cloudforce-one_PendingRuleChange": { "description": "Proposed update or deletion awaiting approval. The other rule fields describe the currently applied version.", "type": "object", "properties": { "approval_id": { "type": "number", "example": 12345 }, "requested_at": { "type": "number", "example": 1679529600000 }, "requested_by": { "type": "string", "example": "user@example.com" }, "type": { "type": "string", "example": "update", "enum": [ "update", "delete" ] } }, "nullable": true, "required": [ "approval_id", "type", "requested_at", "requested_by" ] }, "cloudforce-one_ResubmitApprovalRequest": { "type": "object", "properties": { "commit_message": { "type": "string", "maxLength": 1000, "minLength": 1 }, "content": { "minLength": 1, "type": "string" }, "description": { "type": "string", "maxLength": 1000 }, "enabled": { "type": "boolean" }, "name": { "type": "string", "maxLength": 255, "minLength": 1 }, "namespaces": { "type": "array", "items": { "type": "string" } } } }, "cloudforce-one_ResubmitApprovalResponse": { "type": "object", "properties": { "approval_id": { "type": "number" }, "message": { "type": "string" }, "requires_approval": { "type": "boolean", "enum": [ true ] }, "revision_number": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "supersedes_approval_id": { "type": "number" } }, "required": [ "message", "approval_id", "supersedes_approval_id", "revision_number", "requires_approval" ] }, "cloudforce-one_Rule": { "type": "object", "properties": { "content": { "example": "rule example { condition: true }", "type": "string" }, "created_at": { "type": "number", "example": 1679529600000, "x-auditable": true }, "created_by": { "type": "string", "example": "user@example.com", "x-auditable": true }, "description": { "type": "string", "example": "Detects malicious proxy workers" }, "enabled": { "description": "Whether this rule is active for dice consumers.", "type": "boolean", "example": true }, "id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "x-auditable": true }, "is_public": { "description": "Whether this rule is visible to other internal accounts.", "type": "boolean", "example": false, "x-auditable": true }, "meta": { "description": "Structured meta entries for the rule (parsed from content plus any request-supplied meta). Returned in source order.", "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one_RuleMetaEntry" } }, "name": { "type": "string", "example": "block-malicious-workers", "x-auditable": true }, "namespaces": { "type": "array", "items": { "type": "string" }, "example": [ "yara/workers" ], "x-auditable": true }, "path": { "type": "string", "example": "yara/workers", "x-auditable": true }, "pending_approval_id": { "description": "ID of an open approval workflow targeting this rule, or null if none is pending.", "type": "number", "nullable": true }, "pending_change": { "$ref": "#/components/schemas/cloudforce-one_PendingRuleChange" }, "structured_source": { "description": "Original JSON payload for rules created via the structured rules API. Null for hand-written rules.", "type": "string", "nullable": true }, "updated_at": { "type": "number", "example": 1679529600000, "x-auditable": true }, "updated_by": { "type": "string", "example": "user@example.com", "x-auditable": true } }, "required": [ "id", "name", "path", "description", "namespaces", "content", "is_public", "enabled", "created_at", "updated_at", "created_by", "updated_by", "pending_approval_id", "pending_change" ] }, "cloudforce-one_RuleAction": { "type": "object", "properties": { "action_config": { "description": "Action-specific configuration parameters.", "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "items": { "type": "string" }, "type": "array" }, { "additionalProperties": { "type": "string" }, "type": "object" } ] } }, "action_type": { "type": "string", "example": "alert_gchat", "enum": [ "alert_gchat", "webhook", "logging", "email", "pipeline", "remediation", "throttle", "delete" ] }, "enabled": { "type": "boolean", "default": true } }, "required": [ "action_type", "action_config" ] }, "cloudforce-one_RuleApprovalDetailResponse": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "audit_log_id": { "type": "number", "example": 1 }, "can_review": { "description": "Whether the authenticated user may approve or reject this pending change.", "type": "boolean", "example": true }, "cancelled_at": { "description": "Time at which the requester cancelled the approval.", "type": "number", "example": 1679529600000, "nullable": true, "x-auditable": true }, "cancelled_by": { "description": "Requester who cancelled the pending approval.", "type": "string", "example": "requester@example.com", "nullable": true, "x-auditable": true }, "change_description": { "type": "string", "example": "Updated rule content" }, "change_type": { "type": "string", "example": "create", "enum": [ "create", "update", "delete", "unresolved" ] }, "commit_message": { "description": "The requester supplies this human-readable justification with the change. Internal-account mutations require it; customer accounts and sync-originated changes may omit it.", "type": "string", "example": "Tighten regex to reduce false positives on legit CI workers.", "nullable": true }, "compiler_warnings": { "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one_CompilerWarning" } }, "current_rule": { "anyOf": [ { "$ref": "#/components/schemas/cloudforce-one_RulePreview" } ], "nullable": true }, "id": { "type": "number", "example": 12345, "x-auditable": true }, "proposed_changes": { "$ref": "#/components/schemas/cloudforce-one_ApprovalProposedChanges" }, "rejection_reason": { "description": "The reviewer may supply a reason when rejecting the change.", "type": "string", "example": "Narrow the hostname match to avoid false positives.", "nullable": true, "x-auditable": true }, "requested_at": { "type": "number", "example": 1679529600000, "x-auditable": true }, "requested_by": { "type": "string", "example": "user@example.com", "x-auditable": true }, "reviewed_at": { "type": "number", "example": 1679529600000, "nullable": true, "x-auditable": true }, "reviewer_scope": { "description": "Review policy: general Nomos approvers for default; general approvers or Phishguard for email.", "type": "string", "example": "email", "enum": [ "default", "email", "unresolved" ] }, "revision_number": { "description": "Revision number within this approval request chain.", "type": "integer", "example": 2, "exclusiveMinimum": true, "minimum": 0 }, "rule_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "x-auditable": true }, "rule_name": { "type": "string", "example": "suspicious_email.yar" }, "status": { "type": "string", "example": "pending", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "superseded_by_approval_id": { "description": "Newer approval revision that replaced this approval.", "type": "number", "example": 12346, "nullable": true }, "supersedes_approval_id": { "description": "This approval replaces the referenced approval revision.", "type": "number", "example": 12344, "nullable": true } }, "required": [ "id", "rule_id", "rule_name", "audit_log_id", "requested_by", "requested_at", "change_description", "change_type", "proposed_changes", "status", "reviewed_at", "rejection_reason", "cancelled_by", "cancelled_at", "supersedes_approval_id", "superseded_by_approval_id", "revision_number", "commit_message", "reviewer_scope", "can_review", "current_rule" ] } }, "required": [ "approval" ] }, "cloudforce-one_RuleApprovalsListResponse": { "type": "object", "properties": { "approvals": { "type": "array", "items": { "properties": { "audit_log_id": { "type": "number", "example": 1 }, "can_review": { "description": "Whether the authenticated user may approve or reject this pending change.", "type": "boolean", "example": true }, "cancelled_at": { "description": "Time at which the requester cancelled the approval.", "type": "number", "example": 1679529600000, "nullable": true, "x-auditable": true }, "cancelled_by": { "description": "Requester who cancelled the pending approval.", "type": "string", "example": "requester@example.com", "nullable": true, "x-auditable": true }, "change_description": { "type": "string", "example": "Updated rule content" }, "change_type": { "type": "string", "example": "create", "enum": [ "create", "update", "delete", "unresolved" ] }, "commit_message": { "description": "The requester supplies this human-readable justification with the change. Internal-account mutations require it; customer accounts and sync-originated changes may omit it.", "type": "string", "example": "Tighten regex to reduce false positives on legit CI workers.", "nullable": true }, "id": { "type": "number", "example": 12345, "x-auditable": true }, "proposed_changes": { "$ref": "#/components/schemas/cloudforce-one_ApprovalProposedChanges" }, "rejection_reason": { "description": "The reviewer may supply a reason when rejecting the change.", "type": "string", "example": "Narrow the hostname match to avoid false positives.", "nullable": true, "x-auditable": true }, "requested_at": { "type": "number", "example": 1679529600000, "x-auditable": true }, "requested_by": { "type": "string", "example": "user@example.com", "x-auditable": true }, "reviewed_at": { "type": "number", "example": 1679529600000, "nullable": true, "x-auditable": true }, "reviewer_scope": { "description": "Review policy: general Nomos approvers for default; general approvers or Phishguard for email.", "type": "string", "example": "email", "enum": [ "default", "email", "unresolved" ] }, "revision_number": { "description": "Revision number within this approval request chain.", "type": "integer", "example": 2, "exclusiveMinimum": true, "minimum": 0 }, "rule_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "x-auditable": true }, "rule_name": { "type": "string", "example": "suspicious_email.yar" }, "status": { "type": "string", "example": "pending", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "superseded_by_approval_id": { "description": "Newer approval revision that replaced this approval.", "type": "number", "example": 12346, "nullable": true }, "supersedes_approval_id": { "description": "This approval replaces the referenced approval revision.", "type": "number", "example": 12344, "nullable": true } }, "required": [ "id", "rule_id", "rule_name", "audit_log_id", "requested_by", "requested_at", "change_description", "change_type", "proposed_changes", "status", "reviewed_at", "rejection_reason", "cancelled_by", "cancelled_at", "supersedes_approval_id", "superseded_by_approval_id", "revision_number", "commit_message", "reviewer_scope", "can_review" ], "type": "object" } }, "total": { "type": "number", "example": 10 } }, "required": [ "approvals", "total" ] }, "cloudforce-one_RuleMetaEntry": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "bool", "int" ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "number" } ] } }, "required": [ "key", "value", "type" ] }, "cloudforce-one_RulePreview": { "type": "object", "properties": { "content": { "example": "rule example { condition: true }", "type": "string" }, "created_at": { "type": "number", "example": 1679529600000, "x-auditable": true }, "created_by": { "type": "string", "example": "user@example.com", "x-auditable": true }, "description": { "type": "string", "example": "Detects malicious proxy workers" }, "enabled": { "description": "Whether this rule is active for dice consumers.", "type": "boolean", "example": true }, "id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "x-auditable": true }, "is_public": { "description": "Whether this rule is visible to other internal accounts.", "type": "boolean", "example": false, "x-auditable": true }, "meta": { "description": "Structured meta entries for the rule (parsed from content plus any request-supplied meta). Returned in source order.", "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one_RuleMetaEntry" } }, "name": { "type": "string", "example": "block-malicious-workers", "x-auditable": true }, "namespaces": { "type": "array", "items": { "type": "string" }, "example": [ "yara/workers" ], "x-auditable": true }, "path": { "type": "string", "example": "yara/workers", "x-auditable": true }, "pending_approval_id": { "description": "ID of an open approval workflow targeting this rule, or null if none is pending.", "type": "number", "nullable": true }, "pending_change": { "$ref": "#/components/schemas/cloudforce-one_PendingRuleChange" }, "structured_source": { "description": "Original JSON payload for rules created via the structured rules API. Null for hand-written rules.", "type": "string", "nullable": true }, "updated_at": { "type": "number", "example": 1679529600000, "x-auditable": true }, "updated_by": { "type": "string", "example": "user@example.com", "x-auditable": true } }, "required": [ "id", "name", "path", "description", "namespaces", "is_public", "enabled", "created_at", "updated_at", "created_by", "updated_by", "pending_approval_id", "pending_change" ] }, "cloudforce-one_RuleSearchResult": { "allOf": [ { "$ref": "#/components/schemas/cloudforce-one_RulePreview" }, { "properties": { "score": { "description": "Relevance score in [0,1]. Present only when AI Search powers the query.", "type": "number", "example": 0.87, "maximum": 1, "minimum": 0 }, "scoring_details": { "description": "AI Search hybrid retrieval returns this per-component scoring breakdown.", "type": "object", "properties": { "fusion_method": { "type": "string" }, "keyword_rank": { "type": "number" }, "keyword_score": { "type": "number" }, "reranking_score": { "type": "number" }, "vector_rank": { "type": "number" }, "vector_score": { "type": "number" } } } }, "type": "object" } ] }, "cloudforce-one_RulesPreviewListResponse": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one_RulePreview" } }, "total": { "type": "number", "example": 100 } }, "required": [ "rules", "total" ] }, "cloudforce-one_RulesSearchResponse": { "type": "object", "properties": { "fallback": { "description": "True when AI Search was unavailable and the response is from a fallback path.", "type": "boolean", "example": false }, "interpreted": { "description": "Parsed natural-language interpretation of the query, when available.", "type": "object", "properties": { "filters": { "description": "Filters applied during retrieval (account ACL plus user-supplied facets).", "type": "object", "additionalProperties": { "nullable": true, "type": "object" } }, "retrieval_type": { "type": "string" } }, "required": [ "retrieval_type" ] }, "mode": { "description": "Retrieval strategy actually used to produce results.", "type": "string", "example": "hybrid" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one_RuleSearchResult" } }, "total": { "type": "integer", "example": 12, "minimum": 0 } }, "required": [ "results", "total", "mode" ] }, "cloudforce-one_StatsResponse": { "type": "object", "properties": { "pending_approvals": { "type": "number", "example": 5 }, "rules_by_namespace": { "type": "object", "example": { "yara/dns_record": 12, "yara/workers": 30 }, "additionalProperties": { "type": "number" } }, "total_rules": { "type": "number", "example": 42 } }, "required": [ "total_rules", "rules_by_namespace", "pending_approvals" ] }, "cloudforce-one_SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] }, "cloudforce-one_TreeNode": { "type": "object", "properties": { "children": { "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one_TreeNode" } }, "count": { "type": "number", "example": 15 }, "name": { "type": "string", "example": "workers" }, "path": { "type": "string", "example": "yara/workers" } }, "required": [ "name", "path", "count", "children" ] }, "cloudforce-one_TreeResponse": { "type": "object", "properties": { "tree": { "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one_TreeNode" } } }, "required": [ "tree" ] }, "cloudforce-one_UpdateAccountExemptionsBody": { "type": "object", "properties": { "namespace": { "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one_ExemptionUpdateEntry" } }, "tag_match": { "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one_ExemptionUpdateEntry" } }, "worker_name": { "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one_ExemptionUpdateEntry" } } }, "additionalProperties": false }, "cloudforce-one_UpdateRule": { "type": "object", "properties": { "commit_message": { "description": "Human-readable justification for this change. Required for internal-account submissions; optional for customer accounts and automated sync.", "type": "string", "example": "Reduce false positives on legit CI workers.", "maxLength": 1000 }, "content": { "example": "rule example { condition: true }", "minLength": 1, "type": "string" }, "description": { "description": "Human-readable description of the rule. Auto-extracted from YARA meta if present.", "type": "string", "example": "Detects malicious proxy workers", "maxLength": 1000 }, "enabled": { "description": "Whether this rule is active for dice consumers.", "type": "boolean", "example": true }, "is_public": { "description": "Whether this rule is visible to other internal accounts.", "type": "boolean", "example": false, "x-auditable": true }, "meta": { "description": "Adds YARA meta entries to the rule's meta block and stores them in rule_meta alongside content metadata. Use valid YARA identifiers for keys; exclude 'name', 'enabled', and 'description'. You may repeat keys.", "type": "array", "items": { "$ref": "#/components/schemas/cloudforce-one_MetaInputEntry" }, "maxItems": 50 }, "name": { "type": "string", "example": "block-malicious-workers", "maxLength": 255, "minLength": 1, "x-auditable": true }, "namespaces": { "type": "array", "items": { "maxLength": 255, "minLength": 1, "type": "string" }, "example": [ "yara/workers" ], "x-auditable": true }, "path": { "description": "Path change goes through approval workflow.", "type": "string", "example": "yara/workers", "minLength": 1, "x-auditable": true } } }, "cloudforce-one_ValidationResponse": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid YARA syntax" }, "valid": { "type": "boolean", "example": true } }, "required": [ "valid" ] }, "cps_api_response_common_failure": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/cps_api_response_message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/cps_api_response_message" } }, "result": { "description": "Empty result on failure.", "type": "array", "items": { "type": "object" }, "example": [] }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors" ] }, "cps_api_response_message": { "type": "object", "properties": { "code": { "description": "Error or message code.", "type": "integer", "minimum": 1000 }, "message": { "description": "Human-readable message.", "type": "string" } }, "required": [ "code", "message" ] }, "cps_communication_preferences": { "description": "The user's communication preferences.", "type": "object", "properties": { "created_on": { "description": "Timestamp of the most recently created preference.", "type": "string", "format": "date-time", "example": "2024-06-01T14:20:00Z" }, "email": { "description": "Email verification status for the user.", "type": "object", "properties": { "hard_bounce": { "description": "True when delivery attempts to this email address fail permanently.", "type": "boolean", "example": false }, "verified": { "description": "True when the user verifies their email address.", "type": "boolean", "example": true } } }, "language-locale": { "description": "The user's preferred language locale for communications.", "type": "string", "example": "en-US", "enum": [ "en-US", "es-ES", "de-DE", "fr-FR", "it-IT", "ja-JP", "ko-KR", "pt-BR", "zh-CN", "zh-TW" ] }, "preferences": { "description": "Preference keys mapped to subscription states. Keys use human-readable slugs (e.g. \"product_news\", \"marketing\").", "type": "object", "example": { "marketing": { "created_on": "2024-01-15T10:30:00Z", "subscribed": false, "updated_on": "2024-08-12T09:45:00Z" }, "product_news": { "created_on": "2024-01-15T10:30:00Z", "subscribed": true, "updated_on": "2024-06-01T14:20:00Z" } }, "additionalProperties": { "$ref": "#/components/schemas/cps_customer_preference" } }, "updated_on": { "description": "Timestamp of the most recently updated preference.", "type": "string", "format": "date-time", "example": "2024-08-12T09:45:00Z" } }, "required": [ "email", "preferences", "language-locale", "created_on", "updated_on" ] }, "cps_communication_preferences_response": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/cps_api_response_message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/cps_api_response_message" } }, "result": { "$ref": "#/components/schemas/cps_communication_preferences" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages", "result" ] }, "cps_customer_preference": { "description": "A single communication preference subscription state.", "type": "object", "properties": { "created_on": { "description": "When this preference first appeared.", "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" }, "subscribed": { "description": "Whether the user subscribes to this communication type.", "type": "boolean", "example": true }, "updated_on": { "description": "When this preference last changed.", "type": "string", "format": "date-time", "example": "2024-06-01T14:20:00Z" } }, "required": [ "subscribed" ] }, "cps_update_communication_preferences_request": { "description": "Request body for updating communication preferences. An email field in the payload is ignored; email verification state is managed separately, so the field is excluded from this schema.", "type": "object", "properties": { "language-locale": { "description": "The user's preferred language locale for communications. If omitted, the language locale does not change.", "type": "string", "example": "en-US", "enum": [ "en-US", "es-ES", "de-DE", "fr-FR", "it-IT", "ja-JP", "ko-KR", "pt-BR", "zh-CN", "zh-TW" ] }, "preferences": { "description": "Preference keys mapped to subscription states to update. Only the preferences in this map change; others remain unchanged.", "type": "object", "example": { "marketing": { "subscribed": false }, "product_news": { "subscribed": true } }, "additionalProperties": { "properties": { "subscribed": { "description": "Whether to subscribe or unsubscribe from this communication type.", "type": "boolean" } }, "required": [ "subscribed" ], "type": "object" } } } }, "csam-config-service_api_response_common_failure": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/csam-config-service_api_response_message" }, "example": [ { "code": 7003, "message": "No route for the URI" } ] }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/csam-config-service_api_response_message" } }, "result": { "type": "object", "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false } }, "required": [ "success", "errors", "messages" ] }, "csam-config-service_api_response_message": { "type": "object", "properties": { "code": { "type": "integer", "example": 1000 }, "message": { "type": "string", "example": "success" } }, "required": [ "code", "message" ] }, "csam-config-service_api_response_single": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/csam-config-service_api_response_message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/csam-config-service_api_response_message" } }, "result": { "type": "object" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages" ] }, "csam-config-service_csam_scanner_setting": { "description": "CSAM Scanner configuration for a zone.", "type": "object", "properties": { "editable": { "description": "Whether the feature state can be changed. When false, the zone\nor account may be locked by Trust & Safety.\n", "type": "boolean", "example": true }, "id": { "description": "The feature identifier.", "type": "string", "example": "csam_scanner", "enum": [ "csam_scanner" ] }, "modified_on": { "description": "When the setting was last modified. Currently always null as the\nserver does not populate this field.\n", "type": "string", "format": "date-time", "nullable": true }, "value": { "$ref": "#/components/schemas/csam-config-service_csam_scanner_value" } } }, "csam-config-service_csam_scanner_single_response": { "allOf": [ { "$ref": "#/components/schemas/csam-config-service_api_response_single" }, { "properties": { "result": { "$ref": "#/components/schemas/csam-config-service_csam_scanner_setting" } }, "type": "object" } ] }, "csam-config-service_csam_scanner_third_party_update_request": { "description": "Request body for updating CSAM Scanner configuration.\n", "type": "object", "properties": { "id": { "description": "The feature identifier.", "type": "string", "example": "csam_scanner", "enum": [ "csam_scanner" ] }, "value": { "$ref": "#/components/schemas/csam-config-service_csam_scanner_third_party_update_value" } } }, "csam-config-service_csam_scanner_third_party_update_value": { "description": "Writable CSAM Scanner feature configuration values.\n", "type": "object", "properties": { "email": { "description": "Notification email address for CSAM scan results. When changed,\nemail verification is triggered automatically.\n", "type": "string", "example": "user@example.com", "maxLength": 254 }, "enabled": { "description": "Whether CSAM scanning is enabled for this zone.", "type": "boolean", "example": true }, "resend_email": { "description": "Set to true to trigger re-sending the email verification.\nWrite-only; never appears in responses (omitted when false).\n", "type": "boolean", "example": true }, "sources": { "description": "Map of scanning sources and their enabled state.", "type": "object", "example": { "source1": true }, "additionalProperties": { "type": "boolean" } } } }, "csam-config-service_csam_scanner_value": { "description": "The CSAM Scanner feature configuration values. Contains the\nnotification email and scanning enablement settings.\n", "type": "object", "properties": { "email": { "description": "Notification email address for CSAM scan results. Masked in\nresponses unless explicitly unmasked via admin endpoint.\n", "type": "string", "example": "**********", "maxLength": 254 }, "email_state": { "description": "Current verification state of the notification email.\n", "type": "string", "example": "valid", "enum": [ "valid", "pending", "unverified" ] }, "enabled": { "description": "Whether CSAM scanning is enabled for this zone.", "type": "boolean", "example": true }, "sources": { "description": "Map of scanning sources and their enabled state.", "type": "object", "example": { "source1": true }, "additionalProperties": { "type": "boolean" } }, "zone_plan": { "description": "The zone's plan level.", "type": "string", "example": "ent", "readOnly": true } } }, "csam-config-service_zone_identifier": { "description": "Identifier for the zone.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "minLength": 1 }, "custom-indicator-feeds_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/custom-indicator-feeds_messages-2" }, "messages": { "$ref": "#/components/schemas/custom-indicator-feeds_messages-2" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "custom-indicator-feeds_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/custom-indicator-feeds_api-response-common" } ] }, "custom-indicator-feeds_api_response_common_failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/custom-indicator-feeds_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/custom-indicator-feeds_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "custom-indicator-feeds_create_feed": { "properties": { "description": { "$ref": "#/components/schemas/custom-indicator-feeds_description" }, "name": { "$ref": "#/components/schemas/custom-indicator-feeds_name" } }, "example": { "description": "example feed description", "name": "example_feed_1" } }, "custom-indicator-feeds_create_feed_response": { "allOf": [ { "$ref": "#/components/schemas/custom-indicator-feeds_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/custom-indicator-feeds_indicator_feed_item" } } } ] }, "custom-indicator-feeds_create_provider_request": { "properties": { "account_id": { "description": "The numeric account ID to create the provider for. Distinct from the\npath `account_id` parameter, which carries the account identifier\nstring used for routing.\n", "type": "integer", "example": 12345, "x-auditable": true }, "name": { "description": "The name of the provider", "type": "string", "example": "my_provider", "x-auditable": true } }, "required": [ "account_id", "name" ] }, "custom-indicator-feeds_create_provider_response": { "allOf": [ { "$ref": "#/components/schemas/custom-indicator-feeds_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/custom-indicator-feeds_create_provider_result" } } } ] }, "custom-indicator-feeds_create_provider_result": { "properties": { "account_id": { "description": "The numeric account ID the provider was created for. Distinct from\nthe path `account_id` parameter, which carries the account\nidentifier string used for routing.\n", "type": "integer", "example": 12345, "x-auditable": true }, "name": { "description": "The name of the provider", "type": "string", "example": "my_provider", "x-auditable": true }, "provider_id": { "description": "The unique identifier for the created provider", "type": "integer", "example": 1, "x-auditable": true } }, "required": [ "account_id", "name", "provider_id" ] }, "custom-indicator-feeds_description": { "description": "The description of the example test", "type": "string", "x-auditable": true }, "custom-indicator-feeds_enqueue_upload": { "type": "object", "properties": { "poll_url": { "description": "Account-relative polling path. Prepend `/accounts/{account_id}`\nusing the same account identifier and API host as the upload\nrequest. The path omits the account segment because the service\ndoes not have your account identifier in this context.\n", "type": "string", "example": "/intel/indicator-feeds/12/uploads/12345", "x-auditable": true }, "status": { "type": "string", "example": "Queued", "x-auditable": true }, "upload_id": { "type": "integer", "format": "int64", "x-auditable": true } }, "required": [ "upload_id", "status", "poll_url" ] }, "custom-indicator-feeds_enqueue_upload_response": { "allOf": [ { "$ref": "#/components/schemas/custom-indicator-feeds_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/custom-indicator-feeds_enqueue_upload" } } } ] }, "custom-indicator-feeds_feed_id": { "description": "Indicator feed ID", "type": "integer", "example": 12, "x-auditable": true }, "custom-indicator-feeds_id": { "description": "The unique identifier for the indicator feed", "type": "integer", "x-auditable": true }, "custom-indicator-feeds_identifier": { "description": "Identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "custom-indicator-feeds_indicator_feed_item": { "properties": { "created_on": { "description": "The date and time when the data entry was created", "type": "string", "format": "date-time", "x-auditable": true }, "description": { "$ref": "#/components/schemas/custom-indicator-feeds_description" }, "id": { "$ref": "#/components/schemas/custom-indicator-feeds_id" }, "is_attributable": { "$ref": "#/components/schemas/custom-indicator-feeds_is_attributable" }, "is_downloadable": { "$ref": "#/components/schemas/custom-indicator-feeds_is_downloadable" }, "is_public": { "$ref": "#/components/schemas/custom-indicator-feeds_is_public" }, "modified_on": { "description": "The date and time when the data entry was last modified", "type": "string", "format": "date-time", "x-auditable": true }, "name": { "$ref": "#/components/schemas/custom-indicator-feeds_name" } }, "example": { "created_on": "2023-05-12T12:21:56.777653Z", "description": "example feed description", "id": 1, "is_attributable": false, "is_downloadable": false, "is_public": false, "modified_on": "2023-06-18T03:13:34.123321Z", "name": "example_feed_1" } }, "custom-indicator-feeds_indicator_feed_metadata": { "properties": { "created_on": { "description": "The date and time when the data entry was created", "type": "string", "format": "date-time", "x-auditable": true }, "description": { "$ref": "#/components/schemas/custom-indicator-feeds_description" }, "id": { "$ref": "#/components/schemas/custom-indicator-feeds_id" }, "is_attributable": { "$ref": "#/components/schemas/custom-indicator-feeds_is_attributable" }, "is_downloadable": { "$ref": "#/components/schemas/custom-indicator-feeds_is_downloadable" }, "is_public": { "$ref": "#/components/schemas/custom-indicator-feeds_is_public" }, "last_upload_summary": { "$ref": "#/components/schemas/custom-indicator-feeds_last_upload_summary" }, "latest_upload_error": { "description": "Human-readable error message describing why the latest upload\nfailed. Populated only when `latest_upload_status` is `Error`.\nReturns one of a small fixed set of category-level messages\n(invalid domain / IP / URL entries, malformed row or header,\ninvalid valid_until timestamp, etc.) or the generic\n`Upload failed` for unknown or infrastructure-level errors.\nNever echoes raw error text from the underlying loader.\nIntel accounts receive the verbatim loader/API error text\n(including specific offending values) instead of these\ncategory-level messages.\n", "type": "string", "example": "Feed contains one or more invalid domain entries. Check your feed for wildcards or other values that are not valid DNS names.", "x-auditable": true }, "latest_upload_status": { "description": "Status of the latest snapshot uploaded", "type": "string", "enum": [ "Mirroring", "Unifying", "Loading", "Provisioning", "Complete", "Error" ], "x-auditable": true }, "modified_on": { "description": "The date and time when the data entry was last modified", "type": "string", "format": "date-time", "x-auditable": true }, "name": { "$ref": "#/components/schemas/custom-indicator-feeds_name" }, "provider_id": { "$ref": "#/components/schemas/custom-indicator-feeds_provider_id" }, "provider_name": { "$ref": "#/components/schemas/custom-indicator-feeds_provider_name" } }, "example": { "created_on": "2023-05-12T12:21:56.777653Z", "description": "example feed description", "id": 1, "is_attributable": false, "is_downloadable": false, "is_public": false, "last_upload_summary": { "persisted": { "domains_added": 2, "domains_removed": 1, "ips_added": 0, "ips_removed": 0, "urls_added": 0, "urls_removed": 0 }, "skipped": { "allowlisted_domains": 1, "expired_indicators": 0, "invalid_indicators": 0 }, "uploaded": { "domains": 3, "ips": 0, "urls": 0 } }, "latest_upload_status": "Complete", "modified_on": "2023-06-18T03:13:34.123321Z", "name": "example_feed_1" } }, "custom-indicator-feeds_indicator_feed_metadata_response": { "allOf": [ { "$ref": "#/components/schemas/custom-indicator-feeds_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/custom-indicator-feeds_indicator_feed_metadata" } } } ] }, "custom-indicator-feeds_indicator_feed_response": { "allOf": [ { "$ref": "#/components/schemas/custom-indicator-feeds_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/custom-indicator-feeds_indicator_feed_item" }, "example": [ { "created_on": "2023-05-12T12:21:56.777653Z", "description": "user specified description 1", "id": 1, "modified_on": "2023-06-18T03:13:34.123321Z", "name": "user_specified_name_1" }, { "created_on": "2023-05-21T21:43:52.867525Z", "description": "User specified description 2", "id": 2, "modified_on": "2023-06-28T18:46:18.764425Z", "name": "user_specified_name_2" } ] } } } ] }, "custom-indicator-feeds_indicator_feed_response_single": { "allOf": [ { "$ref": "#/components/schemas/custom-indicator-feeds_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/custom-indicator-feeds_indicator_feed_item" } } } ] }, "custom-indicator-feeds_is_attributable": { "description": "Whether the indicator feed can be attributed to a provider", "type": "boolean", "x-auditable": true }, "custom-indicator-feeds_is_downloadable": { "description": "Whether the indicator feed can be downloaded", "type": "boolean", "x-auditable": true }, "custom-indicator-feeds_is_public": { "description": "Whether the indicator feed is exposed to customers", "type": "boolean", "x-auditable": true }, "custom-indicator-feeds_last_upload_summary": { "description": "Summary of indicator counts from the last successful upload to this\nfeed. Populated by the custom-threat-feeds loader at the end of each\nsuccessful load. Absent (omitted) when no upload has completed\nsuccessfully or the upload errored before the summary write.\nSurfaces silent-failure paths so operators can see when their\nindicators were dropped (popularity allowlist, expired valid_until,\netc.) without reading loader logs.\n", "type": "object", "properties": { "persisted": { "description": "Net delta applied to feed indicators by this upload. Snapshot\nuploads emit both *_added and *_removed; delta-add emits only\n*_added; delta-remove emits only *_removed.\n", "type": "object", "properties": { "domains_added": { "type": "integer", "x-auditable": true }, "domains_removed": { "type": "integer", "x-auditable": true }, "ips_added": { "type": "integer", "x-auditable": true }, "ips_removed": { "type": "integer", "x-auditable": true }, "urls_added": { "type": "integer", "x-auditable": true }, "urls_removed": { "type": "integer", "x-auditable": true } } }, "skipped": { "description": "Counts of indicators that were uploaded but did not reach\nQuickSilver, broken down by reason.\n", "type": "object", "properties": { "allowlisted_domains": { "description": "Domains filtered by the global popularity allowlist at QS\nprovisioning time. Popular domains (bing.com, naver.com,\netc.) are protected from custom-threat-feed enforcement.\n", "type": "integer", "x-auditable": true }, "expired_indicators": { "description": "Indicators in the upload whose valid_until is already in\nthe past. These are not added to QS; the expiration cron\nhandles cleanup.\n", "type": "integer", "x-auditable": true }, "invalid_indicators": { "description": "Reserved for future use. Currently always 0 — the unifier\naborts the entire upload on a single bad indicator.\n", "type": "integer", "x-auditable": true } } }, "uploaded": { "description": "Indicator counts from the unified file the loader received", "type": "object", "properties": { "domains": { "description": "Number of domain indicators in the upload", "type": "integer", "x-auditable": true }, "ips": { "description": "Number of IP indicators in the upload", "type": "integer", "x-auditable": true }, "urls": { "description": "Number of URL indicators in the upload", "type": "integer", "x-auditable": true } } } }, "x-auditable": true }, "custom-indicator-feeds_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "custom-indicator-feeds_messages-2": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "custom-indicator-feeds_name": { "description": "The name of the indicator feed", "type": "string", "x-auditable": true }, "custom-indicator-feeds_permission_list_item": { "properties": { "description": { "$ref": "#/components/schemas/custom-indicator-feeds_description" }, "id": { "$ref": "#/components/schemas/custom-indicator-feeds_id" }, "is_attributable": { "$ref": "#/components/schemas/custom-indicator-feeds_is_attributable" }, "is_downloadable": { "$ref": "#/components/schemas/custom-indicator-feeds_is_downloadable" }, "is_public": { "$ref": "#/components/schemas/custom-indicator-feeds_is_public" }, "name": { "$ref": "#/components/schemas/custom-indicator-feeds_name" } } }, "custom-indicator-feeds_permission_list_item_response": { "allOf": [ { "$ref": "#/components/schemas/custom-indicator-feeds_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/custom-indicator-feeds_permission_list_item" }, "example": [ { "description": "An important indicator list", "id": 1, "is_attributable": false, "is_downloadable": false, "is_public": false, "name": "indicator_list_1" }, { "description": "An even more important indicator list", "id": 2, "is_attributable": true, "is_downloadable": false, "is_public": true, "name": "indicator_list_2" } ] } } } ] }, "custom-indicator-feeds_permissions_request": { "properties": { "account_tag": { "description": "The Cloudflare account tag of the account to change permissions on", "type": "string", "example": "823f45f16fd2f7e21e1e054aga4d2859", "x-auditable": true }, "feed_id": { "description": "The ID of the feed to add/remove permissions on", "type": "integer", "example": 1, "x-auditable": true } } }, "custom-indicator-feeds_permissions_response": { "allOf": [ { "$ref": "#/components/schemas/custom-indicator-feeds_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/custom-indicator-feeds_permissions_update" } } } ] }, "custom-indicator-feeds_permissions_update": { "properties": { "success": { "description": "Whether the update succeeded or not", "type": "boolean", "x-auditable": true } } }, "custom-indicator-feeds_provider_id": { "description": "The unique identifier for the provider", "type": "integer", "example": 1, "x-auditable": true }, "custom-indicator-feeds_provider_name": { "description": "The provider of the indicator feed", "type": "string", "x-auditable": true }, "custom-indicator-feeds_update_feed": { "properties": { "file_id": { "description": "Feed id", "type": "integer", "example": 1, "x-auditable": true }, "filename": { "description": "Name of the file unified in our system", "type": "string", "example": "snapshot_file.unified", "x-auditable": true }, "poll_url": { "description": "Account-relative polling path. Prepend `/accounts/{account_id}`\nusing the same account identifier and API host as the upload\nrequest. The path omits the account segment because the service\ndoes not have your account identifier in this context.\n", "type": "string", "example": "/intel/indicator-feeds/12/uploads/12345", "x-auditable": true }, "status": { "description": "Current status of the upload at the moment the request returned.\nThis is NOT a terminal state: the file is unified inline, but the\ndurable loader has only accepted it, so the upload is still\n`Unifying`. Poll `poll_url` until the status reaches a terminal\nvalue (`Unified` or `Error`).\n", "type": "string", "example": "Unifying", "x-auditable": true }, "upload_id": { "description": "Identifier of the upload row, for polling this upload to a\nterminal state via `poll_url`.\n", "type": "integer", "format": "int64", "example": 12345, "x-auditable": true } } }, "custom-indicator-feeds_update_feed_response": { "allOf": [ { "$ref": "#/components/schemas/custom-indicator-feeds_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/custom-indicator-feeds_update_feed" } } } ] }, "custom-indicator-feeds_update_public_field_request": { "properties": { "description": { "description": "The new description of the feed", "type": "string", "example": "This is an example description", "x-auditable": true }, "is_attributable": { "description": "The new is_attributable value of the feed", "type": "boolean", "example": true, "x-auditable": true }, "is_downloadable": { "description": "The new is_downloadable value of the feed", "type": "boolean", "example": true, "x-auditable": true }, "is_public": { "description": "The new is_public value of the feed", "type": "boolean", "example": true, "x-auditable": true }, "name": { "description": "The new name of the feed", "type": "string", "example": "indicator_list", "x-auditable": true } } }, "custom-indicator-feeds_update_public_field_response": { "allOf": [ { "$ref": "#/components/schemas/custom-indicator-feeds_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/custom-indicator-feeds_indicator_feed_item" } } } ] }, "custom-indicator-feeds_upload_status": { "type": "object", "properties": { "attempts": { "type": "integer", "minimum": 0, "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "x-auditable": true }, "error": { "description": "Sanitized terminal error; omitted for non-error states.", "type": "string", "x-auditable": true }, "feed_id": { "$ref": "#/components/schemas/custom-indicator-feeds_feed_id" }, "filename": { "type": "string", "x-auditable": true }, "poll_after_seconds": { "description": "Recommended delay before the next poll; 0 means terminal.", "type": "integer", "maximum": 30, "minimum": 0, "x-auditable": true }, "stage": { "description": "Sanitized durable loader stage, when available.", "type": "string", "enum": [ "queued", "loading", "provisioning", "retrying", "complete", "error" ], "x-auditable": true }, "status": { "description": "`Unifying` while work is queued or active, optionally with attempt\nprogress; `Unified` or `Error` when terminal.\n", "type": "string", "example": "Unifying (attempt 2/3)", "x-auditable": true }, "updated_at": { "type": "string", "format": "date-time", "x-auditable": true }, "upload_id": { "type": "integer", "format": "int64", "x-auditable": true } }, "required": [ "upload_id", "feed_id", "filename", "status", "attempts", "poll_after_seconds" ] }, "custom-indicator-feeds_upload_status_response": { "allOf": [ { "$ref": "#/components/schemas/custom-indicator-feeds_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/custom-indicator-feeds_upload_status" } } } ] }, "custom-pages_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/custom-pages_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "custom-pages_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/custom-pages_messages" }, "messages": { "$ref": "#/components/schemas/custom-pages_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "custom-pages_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/custom-pages_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/custom-pages_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "custom-pages_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/custom-pages_api-response-common" } ] }, "custom-pages_asset_description": { "description": "A short description of the custom asset.", "type": "string", "example": "Custom 500 error page" }, "custom-pages_asset_name": { "description": "The unique name of the custom asset. Can only contain letters (A-Z, a-z), numbers (0-9), and underscores (_).", "type": "string", "example": "my_custom_error_page", "minLength": 1, "pattern": "^[A-Za-z0-9_]+$", "x-auditable": true }, "custom-pages_asset_url": { "description": "The URL where the asset content is fetched from.", "type": "string", "format": "uri", "example": "https://example.com/error.html" }, "custom-pages_custom_asset": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/custom-pages_asset_description" }, "last_updated": { "$ref": "#/components/schemas/custom-pages_timestamp" }, "name": { "$ref": "#/components/schemas/custom-pages_asset_name" }, "size_bytes": { "description": "The size of the asset content in bytes.", "type": "integer", "example": 1024, "readOnly": true }, "url": { "$ref": "#/components/schemas/custom-pages_asset_url" } } }, "custom-pages_custom_asset_result": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/custom-pages_custom_asset" } } } ] }, "custom-pages_custom_asset_result_list": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/custom-pages_custom_asset" } } } } ] }, "custom-pages_custom_page": { "type": "object", "properties": { "created_on": { "$ref": "#/components/schemas/custom-pages_timestamp" }, "description": { "type": "string", "example": "Basic Challenge", "x-auditable": true }, "id": { "type": "string", "example": "basic_challenge", "x-auditable": true }, "modified_on": { "$ref": "#/components/schemas/custom-pages_timestamp" }, "preview_target": { "type": "string", "example": "block:basic-sec-captcha", "x-auditable": true }, "required_tokens": { "type": "array", "items": { "type": "string" }, "example": [ "::CAPTCHA_BOX::" ], "x-auditable": true }, "state": { "$ref": "#/components/schemas/custom-pages_state" }, "url": { "$ref": "#/components/schemas/custom-pages_url" } } }, "custom-pages_custom_page_result": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/custom-pages_custom_page" } } } ] }, "custom-pages_custom_page_result_list": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/custom-pages_custom_page" } } } } ] }, "custom-pages_error_page_type": { "description": "Error Page Types", "type": "string", "example": "ratelimit_block", "enum": [ "1000_errors", "500_errors", "basic_challenge", "country_challenge", "ip_block", "managed_challenge", "ratelimit_block", "under_attack", "waf_block", "waf_challenge" ], "x-auditable": true }, "custom-pages_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "custom-pages_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "custom-pages_preview_request": { "type": "object", "properties": { "act": { "description": "The preview action type. Required for request parsing but not used in token generation. Typically set to \"preview\".", "type": "string", "example": "preview" }, "target": { "description": "The target custom page type to preview (e.g. \"block:waf\"). Encoded as the \"endpoint\" claim in the resulting JWT.", "type": "string", "example": "block:waf" }, "url": { "description": "The URL of the custom page content to preview. Encoded as the \"zone\" claim in the resulting JWT.", "type": "string", "format": "uri", "example": "https://example.com/error.html" } }, "required": [ "act", "target", "url" ] }, "custom-pages_preview_token": { "type": "object", "properties": { "cep_jwt": { "description": "A signed JWT token used to authenticate the preview request.", "type": "string", "example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ6b25lIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS9lcnJvci5odG1sIiwiZW5kcG9pbnQiOiJibG9jazp3YWYiLCJleHAiOjE3MTYyMzkwMjJ9.example" } }, "required": [ "cep_jwt" ] }, "custom-pages_preview_token_result": { "allOf": [ { "$ref": "#/components/schemas/custom-pages_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/custom-pages_preview_token" } } } ] }, "custom-pages_state": { "description": "The custom page state.", "type": "string", "example": "default", "enum": [ "default", "customized" ], "x-auditable": true }, "custom-pages_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "x-auditable": true }, "custom-pages_url": { "description": "The URL associated with the custom page.", "type": "string", "format": "uri", "example": "http://www.example.com", "default": "", "x-auditable": true }, "d1_account-identifier": { "description": "Account identifier tag.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "d1_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/d1_messages" }, "messages": { "$ref": "#/components/schemas/d1_messages" }, "result": { "type": "object" }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "d1_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/d1_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/d1_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "d1_batch-query": { "description": "A single query object or a batch query object", "oneOf": [ { "$ref": "#/components/schemas/d1_single-query" }, { "properties": { "batch": { "type": "array", "items": { "$ref": "#/components/schemas/d1_single-query" } } }, "required": [ "batch" ], "title": "multiple queries", "type": "object" } ] }, "d1_created-at": { "description": "Specifies the timestamp the resource was created as an ISO8601 string.", "type": "string", "format": "date-time", "example": "2022-11-15T18:25:44.442097Z", "readOnly": true, "x-auditable": true }, "d1_database-details-response": { "description": "The details of the D1 database.", "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/d1_created-at" }, "file_size": { "$ref": "#/components/schemas/d1_file-size" }, "jurisdiction": { "$ref": "#/components/schemas/d1_jurisdiction-nullable" }, "name": { "$ref": "#/components/schemas/d1_database-name" }, "num_tables": { "$ref": "#/components/schemas/d1_table-count" }, "read_replication": { "$ref": "#/components/schemas/d1_read-replication-details-for-response" }, "uuid": { "$ref": "#/components/schemas/d1_database-identifier" }, "version": { "$ref": "#/components/schemas/d1_database-version" } } }, "d1_database-identifier": { "description": "D1 database identifier (UUID).", "type": "string", "example": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "readOnly": true, "x-auditable": true }, "d1_database-name": { "description": "D1 database name.", "type": "string", "example": "my-database", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]*$", "x-auditable": true }, "d1_database-response": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/d1_created-at" }, "jurisdiction": { "$ref": "#/components/schemas/d1_jurisdiction-nullable" }, "name": { "$ref": "#/components/schemas/d1_database-name" }, "uuid": { "$ref": "#/components/schemas/d1_database-identifier" }, "version": { "$ref": "#/components/schemas/d1_database-version" } } }, "d1_database-update-partial-request-body": { "type": "object", "properties": { "read_replication": { "$ref": "#/components/schemas/d1_read-replication-details-for-request" } } }, "d1_database-update-request-body": { "type": "object", "properties": { "read_replication": { "$ref": "#/components/schemas/d1_read-replication-details-for-request" } }, "required": [ "read_replication" ] }, "d1_database-version": { "type": "string", "example": "production", "pattern": "^(alpha|beta|production)$", "x-auditable": true }, "d1_file-size": { "description": "The D1 database's size, in bytes.", "type": "number", "example": 12, "x-auditable": true }, "d1_jurisdiction": { "description": "Specify the location to restrict the D1 database to run and store data. If this option is present, the location hint is ignored.", "type": "string", "example": "eu", "enum": [ "eu", "fedramp", "us" ], "x-auditable": true }, "d1_jurisdiction-nullable": { "description": "Specify the location to restrict the D1 database to run and store data. If this option is present, the location hint is ignored.", "type": "string", "example": "eu", "enum": [ "eu", "fedramp", "us" ], "nullable": true, "x-auditable": true }, "d1_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "d1_params": { "type": "array", "items": { "type": "string" }, "example": [ "firstParam", "secondParam" ] }, "d1_primary-location-hint": { "description": "Specify the region to create the D1 primary, if available. If this option is omitted, the D1 will be created as close as possible to the current user.", "type": "string", "example": "wnam", "enum": [ "wnam", "enam", "weur", "eeur", "apac", "oc" ], "x-auditable": true }, "d1_query-meta": { "type": "object", "properties": { "changed_db": { "description": "Denotes if the database has been altered in some way, like deleting rows.", "type": "boolean", "x-auditable": true }, "changes": { "description": "Rough indication of how many rows were modified by the query, as provided by SQLite's `sqlite3_total_changes()`.", "type": "number", "x-auditable": true }, "duration": { "description": "The duration of the SQL query execution inside the database. Does not include any network communication.", "type": "number", "x-auditable": true }, "last_row_id": { "description": "The row ID of the last inserted row in a table with an `INTEGER PRIMARY KEY` as provided by SQLite. Tables created with `WITHOUT ROWID` do not populate this.", "type": "number", "x-auditable": true }, "rows_read": { "description": "Number of rows read during the SQL query execution, including indices (not all rows are necessarily returned).", "type": "number", "x-auditable": true }, "rows_written": { "description": "Number of rows written during the SQL query execution, including indices.", "type": "number", "x-auditable": true }, "served_by_colo": { "$ref": "#/components/schemas/d1_served-by-colo" }, "served_by_primary": { "description": "Denotes if the query has been handled by the database primary instance.", "type": "boolean", "x-auditable": true }, "served_by_region": { "$ref": "#/components/schemas/d1_served-by-region" }, "size_after": { "description": "Size of the database after the query committed, in bytes.", "type": "number", "x-auditable": true }, "timings": { "description": "Various durations for the query.", "type": "object", "properties": { "sql_duration_ms": { "description": "The duration of the SQL query execution inside the database. Does not include any network communication.", "type": "number", "x-auditable": true } } } } }, "d1_query-result-response": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/d1_query-meta" }, "results": { "type": "array", "items": { "type": "object" } }, "success": { "type": "boolean" } } }, "d1_raw-result-response": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/d1_query-meta" }, "results": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "items": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "object" } ] }, "type": "array" } } } }, "success": { "type": "boolean" } } }, "d1_read-replication-details-for-request": { "description": "Configuration for D1 read replication.", "type": "object", "properties": { "mode": { "description": "The read replication mode for the database. Use 'auto' to create replicas and allow D1 automatically place them around the world, or 'disabled' to not use any database replicas (it can take a few hours for all replicas to be deleted).", "type": "string", "example": "auto", "enum": [ "auto", "disabled" ], "x-auditable": true } }, "required": [ "mode" ], "x-stainless-terraform-configurability": "computed_optional" }, "d1_read-replication-details-for-response": { "description": "Configuration for D1 read replication.", "type": "object", "properties": { "mode": { "description": "The read replication mode for the database. Mode 'auto' denotes that D1 creates replicas and automatically places them around the world. Mode 'disabled' denotes that no database replicas are used.", "type": "string", "example": "auto", "enum": [ "auto", "disabled" ], "x-auditable": true } }, "required": [ "mode" ] }, "d1_served-by-colo": { "description": "The three letters airport code of the colo that handled the query.", "type": "string", "example": "LHR", "x-auditable": true }, "d1_served-by-region": { "description": "Region location hint of the database instance that handled the query.", "type": "string", "example": "EEUR", "enum": [ "WNAM", "ENAM", "WEUR", "EEUR", "APAC", "OC" ], "x-auditable": true }, "d1_single-query": { "description": "A single query with or without parameters", "type": "object", "properties": { "params": { "$ref": "#/components/schemas/d1_params" }, "sql": { "$ref": "#/components/schemas/d1_sql" } }, "required": [ "sql" ], "title": "single query" }, "d1_sql": { "description": "Your SQL query. Supports multiple statements, joined by semicolons, which will be executed as a batch.", "type": "string", "example": "SELECT * FROM myTable WHERE field = ? OR field = ?;" }, "d1_table-count": { "type": "number", "example": 12, "x-auditable": true }, "d1_time-travel-bookmark": { "description": "A bookmark representing a specific state of the database at a specific point in time.", "type": "string", "example": "00000001-00000002-00004e2f-0a83ea2fceebc654de0640c422be4653", "x-auditable": true }, "d1_time-travel-restore-response": { "description": "Response from a time travel restore operation.", "type": "object", "properties": { "bookmark": { "allOf": [ { "$ref": "#/components/schemas/d1_time-travel-bookmark" }, { "description": "The new bookmark representing the state of the database after the restore operation." } ] }, "message": { "description": "A message describing the result of the restore operation.", "type": "string", "example": "Database restored successfully", "x-auditable": true }, "previous_bookmark": { "allOf": [ { "$ref": "#/components/schemas/d1_time-travel-bookmark" }, { "description": "The bookmark representing the state of the database before the restore operation. Can be used to undo the restore if needed." } ] } } }, "d1_time-travel-timestamp": { "description": "An ISO 8601 timestamp used for time travel operations. The database will be restored to the nearest available bookmark at or before this timestamp.", "type": "string", "format": "date-time", "example": "2024-01-15T12:00:00Z", "x-auditable": true }, "digital-experience-monitoring_account_identifier": { "description": "Unique identifier linked to an account.", "type": "string", "example": "01a7362d577a6c3019a474fd6f485823", "maxLength": 32, "readOnly": true }, "digital-experience-monitoring_aggregate_stat": { "type": "object", "properties": { "avgMs": { "type": "integer", "nullable": true }, "deltaPct": { "type": "number", "format": "float", "nullable": true }, "timePeriod": { "$ref": "#/components/schemas/digital-experience-monitoring_aggregate_time_period" } }, "required": [ "timePeriod" ] }, "digital-experience-monitoring_aggregate_time_period": { "type": "object", "properties": { "units": { "type": "string", "enum": [ "hours", "days", "testRuns" ] }, "value": { "type": "integer" } }, "required": [ "value", "units" ] }, "digital-experience-monitoring_aggregate_time_slot": { "type": "object", "properties": { "avgMs": { "type": "integer" }, "timestamp": { "type": "string" } }, "required": [ "timestamp", "avgMs" ] }, "digital-experience-monitoring_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "digital-experience-monitoring_api-response-collection-common": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_api-response-common" }, { "properties": { "result": { "type": "array", "items": {}, "nullable": true } } } ] }, "digital-experience-monitoring_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/digital-experience-monitoring_messages" }, "messages": { "$ref": "#/components/schemas/digital-experience-monitoring_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "digital-experience-monitoring_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "digital-experience-monitoring_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_api-response-common" } ] }, "digital-experience-monitoring_colo": { "description": "Cloudflare colo airport code.", "type": "string", "example": "SJC" }, "digital-experience-monitoring_colos_response": { "description": "array of colos.", "type": "array", "items": { "properties": { "airportCode": { "description": "Airport code", "type": "string", "example": "SFO" }, "city": { "description": "City", "type": "string", "example": "San Francisco" }, "countryCode": { "description": "Country code", "type": "string", "example": "US" } }, "required": [ "airportCode", "countryCode", "city" ], "type": "object" } }, "digital-experience-monitoring_command_id": { "description": "Unique identifier for a command", "type": "string", "example": "5758fefe-ae7e-4538-a39b-1fef6abcb909" }, "digital-experience-monitoring_commands_devices_response": { "type": "object", "properties": { "devices": { "description": "List of eligible devices", "type": "array", "items": { "properties": { "deviceId": { "description": "Device identifier (UUID v4)", "type": "string" }, "deviceName": { "description": "Device identifier (human readable)", "type": "string" }, "eligible": { "description": "Whether the device is eligible for remote captures", "type": "boolean" }, "ineligibleReason": { "description": "If the device is not eligible, the reason why.", "type": "string" }, "personEmail": { "description": "User contact email address", "type": "string" }, "platform": { "$ref": "#/components/schemas/digital-experience-monitoring_platform" }, "registrationId": { "description": "Device registration identifier (UUID v4). On multi-user devices, this uniquely identifies a user's registration on the device.", "type": "string" }, "status": { "$ref": "#/components/schemas/digital-experience-monitoring_status" }, "timestamp": { "$ref": "#/components/schemas/digital-experience-monitoring_timestamp" }, "version": { "$ref": "#/components/schemas/digital-experience-monitoring_version" } }, "type": "object" } } } }, "digital-experience-monitoring_cpu_pct_by_app": { "type": "object", "properties": { "cpu_pct": { "description": "CPU usage percentage, on a scale of 0 to 100.", "type": "number", "format": "float", "maximum": 100, "minimum": 0, "nullable": true }, "name": { "description": "Application name.", "type": "string", "nullable": true } } }, "digital-experience-monitoring_create_rule_body": { "type": "object", "properties": { "description": { "type": "string", "x-auditable": true }, "match": { "description": "The wirefilter expression to match.", "type": "string" }, "name": { "description": "The name of the Rule.", "type": "string", "x-auditable": true } }, "required": [ "name", "match" ] }, "digital-experience-monitoring_device": { "type": "object", "properties": { "alwaysOn": { "type": "boolean", "nullable": true }, "batteryCharging": { "type": "boolean", "nullable": true }, "batteryCycles": { "type": "integer", "format": "int64", "nullable": true }, "batteryPct": { "type": "number", "format": "float", "nullable": true }, "colo": { "$ref": "#/components/schemas/digital-experience-monitoring_colo" }, "connectionType": { "type": "string", "nullable": true }, "cpuPct": { "type": "number", "format": "float", "nullable": true }, "cpuPctByApp": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_cpu_pct_by_app" }, "nullable": true }, "deviceId": { "description": "Device identifier (UUID v4)", "type": "string" }, "deviceIpv4": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_schemas-ip_info" } ], "nullable": true }, "deviceIpv6": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_schemas-ip_info" } ], "nullable": true }, "deviceName": { "description": "Device identifier (human readable).", "type": "string" }, "deviceRegistration": { "description": "Deprecated: use registrationId. Device registration identifier (UUID).", "type": "string", "deprecated": true, "nullable": true, "x-stainless-deprecation-message": "Use `registrationId` instead." }, "diskReadBps": { "type": "integer", "format": "int64", "nullable": true }, "diskUsagePct": { "type": "number", "format": "float", "nullable": true }, "diskWriteBps": { "type": "integer", "format": "int64", "nullable": true }, "dohSubdomain": { "type": "string", "nullable": true }, "estimatedLossPct": { "type": "number", "format": "float", "nullable": true }, "firewallEnabled": { "type": "boolean", "nullable": true }, "gatewayIpv4": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_schemas-ip_info" } ], "nullable": true }, "gatewayIpv6": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_schemas-ip_info" } ], "nullable": true }, "handshakeLatencyMs": { "type": "number", "format": "int64", "nullable": true }, "ispIpv4": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_schemas-ip_info" } ], "nullable": true }, "ispIpv6": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_schemas-ip_info" } ], "nullable": true }, "metal": { "type": "string", "nullable": true }, "mode": { "$ref": "#/components/schemas/digital-experience-monitoring_mode" }, "networkRcvdBps": { "type": "integer", "format": "int64", "nullable": true }, "networkSentBps": { "type": "integer", "format": "int64", "nullable": true }, "networkSsid": { "type": "string", "nullable": true }, "personEmail": { "$ref": "#/components/schemas/digital-experience-monitoring_personEmail" }, "platform": { "$ref": "#/components/schemas/digital-experience-monitoring_platform" }, "ramAvailableKb": { "type": "integer", "format": "int64", "nullable": true }, "ramUsedPct": { "type": "number", "format": "float", "nullable": true }, "ramUsedPctByApp": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_ram_used_pct_by_app" }, "nullable": true }, "registrationId": { "description": "Device registration identifier (UUID v4). On multi-user devices, this uniquely identifies a user's registration on the device.", "type": "string", "nullable": true }, "rtt": { "description": "Round-trip time statistics for the WARP tunnel.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_rtt_stats" } ], "nullable": true }, "status": { "$ref": "#/components/schemas/digital-experience-monitoring_status" }, "switchLocked": { "type": "boolean", "nullable": true }, "timestamp": { "$ref": "#/components/schemas/digital-experience-monitoring_timestamp" }, "tunnelStats": { "description": "WARP tunnel packet and byte counters.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_tunnel_stats" } ], "nullable": true }, "tunnelType": { "type": "string", "nullable": true }, "version": { "$ref": "#/components/schemas/digital-experience-monitoring_version" }, "wifiStrengthDbm": { "type": "integer", "format": "int64", "nullable": true } }, "required": [ "colo", "deviceId", "mode", "platform", "status", "timestamp", "version" ] }, "digital-experience-monitoring_device-dex-test-schemas-data": { "description": "The configuration object which contains the details for the WARP client to conduct the test.", "type": "object", "properties": { "host": { "description": "The desired endpoint to test.", "type": "string", "example": "https://dash.cloudflare.com", "x-auditable": true }, "kind": { "description": "The type of test.", "type": "string", "example": "http", "enum": [ "http", "traceroute" ], "x-auditable": true }, "method": { "description": "The HTTP request method type.", "type": "string", "example": "GET", "enum": [ "GET" ], "x-auditable": true } }, "example": { "host": "https://dash.cloudflare.com", "kind": "http", "method": "GET" }, "required": [ "kind", "host" ] }, "digital-experience-monitoring_device-dex-test-schemas-description": { "description": "Additional details about the test.", "type": "string", "example": "Checks the dash endpoint every 30 minutes" }, "digital-experience-monitoring_device-dex-test-schemas-enabled": { "description": "Determines whether or not the test is active.", "type": "boolean", "example": true }, "digital-experience-monitoring_device-dex-test-schemas-http": { "type": "object", "properties": { "created": { "description": "Date the test was created, in RFC 3339 format.", "type": "string", "format": "date-time", "example": "2023-10-11T00:00:00Z", "readOnly": true, "x-stainless-terraform-configurability": "computed" }, "data": { "$ref": "#/components/schemas/digital-experience-monitoring_device-dex-test-schemas-data" }, "description": { "$ref": "#/components/schemas/digital-experience-monitoring_device-dex-test-schemas-description" }, "enabled": { "$ref": "#/components/schemas/digital-experience-monitoring_device-dex-test-schemas-enabled" }, "interval": { "$ref": "#/components/schemas/digital-experience-monitoring_device-dex-test-schemas-interval" }, "name": { "$ref": "#/components/schemas/digital-experience-monitoring_device-dex-test-schemas-name" }, "target_policies": { "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_device-dex-test-target-policies" } ], "x-stainless-terraform-configurability": "computed_optional" }, "targeted": { "type": "boolean", "x-stainless-terraform-configurability": "computed" }, "test_id": { "$ref": "#/components/schemas/digital-experience-monitoring_schemas-test-id" }, "updated": { "description": "Date the test was last updated, in RFC 3339 format.", "type": "string", "format": "date-time", "example": "2023-10-11T00:00:00Z", "readOnly": true, "x-stainless-terraform-configurability": "computed" } }, "required": [ "name", "interval", "enabled", "data" ] }, "digital-experience-monitoring_device-dex-test-schemas-interval": { "description": "How often the test will run.", "type": "string", "example": "30m" }, "digital-experience-monitoring_device-dex-test-schemas-name": { "description": "The name of the DEX test. Must be unique.", "type": "string", "example": "HTTP dash health check" }, "digital-experience-monitoring_device-dex-test-target-policies": { "description": "DEX rules targeted by this test", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_dex_target_policy" } }, "digital-experience-monitoring_device_id": { "description": "Unique identifier for the physical device (UUID).", "type": "string", "example": "cb49c27f-7f97-49c5-b6f3-f7c01ead0fd7" }, "digital-experience-monitoring_device_isp": { "type": "object", "properties": { "ip": { "$ref": "#/components/schemas/digital-experience-monitoring_ip_info" }, "test_id": { "description": "The test that generated this result.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" }, "test_result_id": { "description": "The specific test result.", "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "time_start": { "description": "Timestamp of when the ISP was observed.", "type": "string", "format": "date-time", "example": "2024-06-01T12:00:00Z" } }, "required": [ "time_start", "test_id", "test_result_id" ] }, "digital-experience-monitoring_device_isps_response": { "type": "object", "properties": { "isps": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_device_isp" } } }, "required": [ "isps" ] }, "digital-experience-monitoring_device_state_over_time": { "description": "Time-bucketed device metrics.", "type": "object", "properties": { "battery_cycles": { "description": "Battery cycle count over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_int" } }, "battery_pct": { "description": "Battery percentage over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_float" } }, "connection_type": { "description": "Connection type over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_string" } }, "cpu_pct": { "description": "CPU usage percentage over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_float" } }, "disk_read_bps": { "description": "Disk read throughput in bytes per second over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_int" } }, "disk_usage_pct": { "description": "Disk usage percentage over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_float" } }, "disk_write_bps": { "description": "Disk write throughput in bytes per second over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_int" } }, "mode": { "description": "WARP mode over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_string" } }, "network_rcvd_bps": { "description": "Network bytes received per second over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_int" } }, "network_sent_bps": { "description": "Network bytes sent per second over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_int" } }, "network_ssid": { "description": "Network SSID over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_string" } }, "ram_available_kb": { "description": "Available RAM in kilobytes over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_int" } }, "ram_used_pct": { "description": "RAM usage percentage over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_float" } }, "rtt": { "description": "Round-trip time stats over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_rtt_stats" } }, "status": { "description": "Device status over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_string" } }, "top_cpu_applications": { "description": "Top CPU-consuming applications over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_cpu_apps" } }, "top_ram_applications": { "description": "Top RAM-consuming applications over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_ram_apps" } }, "tunnel_stats": { "description": "Tunnel stats over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_tunnel_stats" } }, "tunnel_type": { "description": "Tunnel type over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_string" } }, "unique_networks": { "description": "Unique network count over time.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_int" } }, "wifi_strength_dbm": { "description": "Wi-Fi signal strength over time in dBm.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_timeslot_int" } } } }, "digital-experience-monitoring_device_state_top_networks_summary": { "type": "object", "properties": { "count": { "description": "Number of observations.", "type": "integer" }, "name": { "description": "Network name.", "type": "string" } }, "required": [ "name", "count" ] }, "digital-experience-monitoring_device_status_over_time_result": { "type": "object", "properties": { "over_time": { "$ref": "#/components/schemas/digital-experience-monitoring_device_state_over_time" }, "top_networks": { "description": "Top networks observed for the device.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_device_state_top_networks_summary" } } }, "required": [ "top_networks", "over_time" ] }, "digital-experience-monitoring_dex-delete-response-collection": { "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "dex_tests": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_device-dex-test-schemas-http" } } } } } } ] }, "digital-experience-monitoring_dex-response_collection": { "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_api-response-collection-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_device-dex-test-schemas-http" } } } } ] }, "digital-experience-monitoring_dex-rule": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2023-07-16 15:00:00+00", "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "description": { "type": "string" }, "id": { "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" } ], "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "match": { "type": "string" }, "name": { "type": "string", "x-auditable": true }, "targeted_tests": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_dex-targeted-test" }, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "updated_at": { "type": "string", "example": "2023-07-16 15:00:00+00", "x-auditable": true, "x-stainless-terraform-configurability": "computed" } }, "required": [ "id", "name", "match", "created_at" ] }, "digital-experience-monitoring_dex-single_response": { "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/digital-experience-monitoring_device-dex-test-schemas-http" } } } ] }, "digital-experience-monitoring_dex-targeted-test": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_device-dex-test-schemas-data" } ], "x-auditable": true }, "enabled": { "type": "boolean", "x-auditable": true }, "name": { "type": "string", "x-auditable": true }, "test_id": { "type": "string", "x-auditable": true } }, "required": [ "test_id", "name", "enabled", "data" ] }, "digital-experience-monitoring_dex_target_policy": { "type": "object", "properties": { "default": { "description": "Whether the DEX rule is the account default.", "type": "boolean", "x-stainless-terraform-configurability": "computed" }, "id": { "description": "The id of the DEX rule.", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" } ] }, "name": { "description": "The name of the DEX rule.", "type": "string", "x-stainless-terraform-configurability": "computed" } }, "required": [ "id" ] }, "digital-experience-monitoring_directional_stat": { "type": "object", "properties": { "downstream": { "type": "integer", "nullable": true }, "upstream": { "type": "integer", "nullable": true } } }, "digital-experience-monitoring_execution_context": { "type": "string", "enum": [ "EXECUTION_CONTEXT_INVALID", "OUT_OF_TUNNEL", "IN_TUNNEL" ] }, "digital-experience-monitoring_fleet_status_devices_response": { "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_device" } } }, "type": "object" } ] }, "digital-experience-monitoring_fleet_status_live_response": { "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "deviceStats": { "type": "object", "properties": { "byColo": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_live_stat" }, "nullable": true }, "byMode": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_live_stat" }, "nullable": true }, "byPlatform": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_live_stat" }, "nullable": true }, "byStatus": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_live_stat" }, "nullable": true }, "byVersion": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_live_stat" }, "nullable": true }, "uniqueDevicesTotal": { "$ref": "#/components/schemas/digital-experience-monitoring_uniqueDevicesTotal" } } } } } }, "type": "object" } ] }, "digital-experience-monitoring_fleet_status_over_time_response": { "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "deviceStats": { "type": "object", "properties": { "byMode": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_schemas-aggregate_stat" } }, "byStatus": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_schemas-aggregate_stat" } }, "uniqueDevicesTotal": { "$ref": "#/components/schemas/digital-experience-monitoring_uniqueDevicesTotal" } } } } } }, "type": "object" } ] }, "digital-experience-monitoring_get_commands_quota_response": { "type": "object", "properties": { "quota": { "description": "The total number of commands that can be initiated for an account.", "type": "number" }, "quota_usage": { "description": "The number of commands that have been initiated for an account.", "type": "number" }, "reset_time": { "description": "The time when the quota resets.", "type": "string", "format": "date-time" } }, "required": [ "quota_usage", "quota", "reset_time" ] }, "digital-experience-monitoring_get_commands_response": { "type": "object", "properties": { "commands": { "type": "array", "items": { "properties": { "completed_date": { "type": "string", "format": "date-time", "nullable": true }, "created_date": { "type": "string", "format": "date-time" }, "device_id": { "type": "string" }, "filename": { "type": "string", "nullable": true }, "id": { "type": "string" }, "registration_id": { "description": "Unique identifier for the device registration", "type": "string" }, "status": { "type": "string" }, "type": { "type": "string" }, "user_email": { "type": "string" } }, "type": "object" } } } }, "digital-experience-monitoring_http_details_percentiles_response": { "type": "object", "properties": { "dnsResponseTimeMs": { "$ref": "#/components/schemas/digital-experience-monitoring_percentiles" }, "resourceFetchTimeMs": { "$ref": "#/components/schemas/digital-experience-monitoring_percentiles" }, "serverResponseTimeMs": { "$ref": "#/components/schemas/digital-experience-monitoring_percentiles" } } }, "digital-experience-monitoring_http_details_response": { "type": "object", "properties": { "host": { "description": "The url of the HTTP synthetic application test.", "type": "string", "example": "http://example.com" }, "httpStats": { "type": "object", "nullable": true, "properties": { "availabilityPct": { "$ref": "#/components/schemas/digital-experience-monitoring_test_stat_pct_over_time" }, "dnsResponseTimeMs": { "$ref": "#/components/schemas/digital-experience-monitoring_test_stat_over_time" }, "httpStatusCode": { "type": "array", "items": { "properties": { "status200": { "type": "integer" }, "status300": { "type": "integer" }, "status400": { "type": "integer" }, "status500": { "type": "integer" }, "timestamp": { "type": "string", "example": "2023-07-16 15:00:00+00" } }, "required": [ "timestamp", "status200", "status300", "status400", "status500" ], "type": "object" } }, "resourceFetchTimeMs": { "$ref": "#/components/schemas/digital-experience-monitoring_test_stat_over_time" }, "serverResponseTimeMs": { "$ref": "#/components/schemas/digital-experience-monitoring_test_stat_over_time" }, "uniqueDevicesTotal": { "description": "Count of unique devices that have run this test in the given time period.", "type": "integer", "example": 57 } }, "required": [ "uniqueDevicesTotal", "resourceFetchTimeMs", "serverResponseTimeMs", "dnsResponseTimeMs", "httpStatusCode", "availabilityPct" ] }, "httpStatsByColo": { "type": "array", "items": { "properties": { "availabilityPct": { "$ref": "#/components/schemas/digital-experience-monitoring_test_stat_pct_over_time" }, "colo": { "type": "string", "example": "DFW" }, "dnsResponseTimeMs": { "$ref": "#/components/schemas/digital-experience-monitoring_test_stat_over_time" }, "httpStatusCode": { "type": "array", "items": { "properties": { "status200": { "type": "integer" }, "status300": { "type": "integer" }, "status400": { "type": "integer" }, "status500": { "type": "integer" }, "timestamp": { "type": "string", "example": "2023-07-16 15:00:00+00" } }, "required": [ "timestamp", "status200", "status300", "status400", "status500" ], "type": "object" } }, "resourceFetchTimeMs": { "$ref": "#/components/schemas/digital-experience-monitoring_test_stat_over_time" }, "serverResponseTimeMs": { "$ref": "#/components/schemas/digital-experience-monitoring_test_stat_over_time" }, "uniqueDevicesTotal": { "description": "Count of unique devices that have run this test in the given time period.", "type": "integer", "example": 57 } }, "required": [ "colo", "uniqueDevicesTotal", "resourceFetchTimeMs", "serverResponseTimeMs", "dnsResponseTimeMs", "httpStatusCode", "availabilityPct" ], "type": "object" } }, "interval": { "description": "The interval at which the HTTP synthetic application test is set to run.", "type": "string", "example": "0h5m0s" }, "kind": { "enum": [ "http" ] }, "method": { "description": "The HTTP method to use when running the test.", "type": "string", "example": "GET" }, "name": { "description": "The name of the HTTP synthetic application test.", "type": "string", "example": "Atlassian Sign In Page" }, "target_policies": { "type": "array", "items": { "properties": { "default": { "description": "Whether the policy is the default for the account.", "type": "boolean" }, "id": { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" }, "name": { "type": "string" } }, "required": [ "id", "name", "default" ], "type": "object" }, "nullable": true }, "targeted": { "type": "boolean" } } }, "digital-experience-monitoring_ip_info": { "description": "IP address information for the ISP hop. Fields marked as PII-gated (`name`, `address`, `netmask`, and all `location` sub-fields) will be returned as the literal string `\"REDACTED\"` for callers that do not have the PII permission. `asn`, `aso`, and `version` are always returned regardless of PII access.\n", "type": "object", "properties": { "address": { "description": "IP address. Returned as `\"REDACTED\"` without PII permission.", "type": "string", "example": "203.0.113.1" }, "asn": { "description": "Autonomous System Number.", "type": "integer", "example": 13335 }, "aso": { "description": "Autonomous System Organization name.", "type": "string", "example": "CLOUDFLARENET" }, "location": { "$ref": "#/components/schemas/digital-experience-monitoring_ip_location" }, "name": { "description": "Named IP address (reverse DNS hostname when available). Returned as `\"REDACTED\"` without PII permission.", "type": "string", "example": "isp-gateway.example.com" }, "netmask": { "description": "Network mask. Returned as `\"REDACTED\"` without PII permission.", "type": "string", "example": "255.255.255.0" }, "version": { "description": "IP version (`1` for IPv4, `2` for IPv6, `0` if unknown).", "type": "integer", "example": 1 } } }, "digital-experience-monitoring_ip_location": { "description": "Geographic location information. All fields are returned as the literal string `\"REDACTED\"` for callers that do not have the PII permission.\n", "type": "object", "properties": { "city": { "description": "City name. Returned as `\"REDACTED\"` without PII permission.", "type": "string", "example": "San Francisco" }, "country_iso": { "description": "Country ISO code. Returned as `\"REDACTED\"` without PII permission.", "type": "string", "example": "US" }, "state_iso": { "description": "State/province ISO code. Returned as `\"REDACTED\"` without PII permission.", "type": "string", "example": "CA" }, "zip": { "description": "ZIP/postal code. Returned as `\"REDACTED\"` without PII permission.", "type": "string", "example": "94107" } } }, "digital-experience-monitoring_list_rules_response": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_dex-rule" } } } }, "digital-experience-monitoring_live_stat": { "type": "object", "properties": { "uniqueDevicesTotal": { "$ref": "#/components/schemas/digital-experience-monitoring_uniqueDevicesTotal" }, "value": { "type": "string" } } }, "digital-experience-monitoring_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "digital-experience-monitoring_mode": { "description": "The mode under which the WARP client is run.", "type": "string", "example": "proxy" }, "digital-experience-monitoring_page": { "description": "Page number of paginated results.", "type": "number", "example": 1, "default": 1, "minimum": 1 }, "digital-experience-monitoring_patch_rule_body": { "type": "object", "properties": { "description": { "type": "string", "x-auditable": true }, "match": { "description": "The wirefilter expression to match.", "type": "string" }, "name": { "description": "The name of the Rule.", "type": "string", "x-auditable": true } } }, "digital-experience-monitoring_per_page": { "description": "Number of results per page.", "type": "number", "example": 10, "maximum": 50, "minimum": 1 }, "digital-experience-monitoring_percentiles": { "type": "object", "properties": { "p50": { "description": "p50 observed in the time period.", "type": "number", "nullable": true }, "p90": { "description": "p90 observed in the time period.", "type": "number", "nullable": true }, "p95": { "description": "p95 observed in the time period.", "type": "number", "nullable": true }, "p99": { "description": "p99 observed in the time period.", "type": "number", "nullable": true } } }, "digital-experience-monitoring_personEmail": { "description": "User contact email address", "type": "string" }, "digital-experience-monitoring_platform": { "description": "Operating system.", "type": "string", "example": "windows" }, "digital-experience-monitoring_post_commands_response": { "type": "object", "properties": { "commands": { "description": "List of created commands", "type": "array", "items": { "properties": { "args": { "description": "Command arguments", "type": "object", "additionalProperties": { "description": "Command argument value as a string", "type": "string" } }, "device_id": { "description": "Identifier for the device associated with the command", "type": "string" }, "id": { "description": "Unique identifier for the command", "type": "string" }, "registration_id": { "description": "Unique identifier for the device registration", "type": "string" }, "status": { "description": "Current status of the command", "type": "string", "enum": [ "PENDING_EXEC", "PENDING_UPLOAD", "SUCCESS", "FAILED" ] }, "type": { "description": "Type of the command (e.g., \"pcap\", \"speed-test\", or \"warp-diag\")", "type": "string" } }, "type": "object" } } } }, "digital-experience-monitoring_ram_used_pct_by_app": { "type": "object", "properties": { "name": { "description": "Application name.", "type": "string", "nullable": true }, "ram_used_pct": { "description": "RAM usage percentage, on a scale of 0 to 100.", "type": "number", "format": "float", "maximum": 100, "minimum": 0, "nullable": true } } }, "digital-experience-monitoring_rtt_stats": { "description": "Round-trip time statistics for the WARP tunnel.", "type": "object", "properties": { "minRttUs": { "description": "Minimum round-trip time in microseconds.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_directional_stat" } ], "nullable": true }, "rttUs": { "description": "Round-trip time in microseconds.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_directional_stat" } ], "nullable": true }, "rttVarUs": { "description": "Round-trip time variance in microseconds.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_directional_stat" } ], "nullable": true } } }, "digital-experience-monitoring_schemas-aggregate_stat": { "type": "object", "properties": { "timestamp": { "$ref": "#/components/schemas/digital-experience-monitoring_timestamp" }, "uniqueDevicesTotal": { "$ref": "#/components/schemas/digital-experience-monitoring_uniqueDevicesTotal" }, "value": { "type": "string" } } }, "digital-experience-monitoring_schemas-ip_info": { "type": "object", "properties": { "address": { "type": "string", "nullable": true }, "asn": { "type": "integer", "nullable": true }, "aso": { "type": "string", "nullable": true }, "location": { "type": "object", "properties": { "city": { "type": "string", "nullable": true }, "country_iso": { "type": "string", "nullable": true }, "state_iso": { "type": "string", "nullable": true }, "zip": { "type": "string", "nullable": true } } }, "name": { "type": "string", "nullable": true }, "netmask": { "type": "string", "nullable": true }, "version": { "description": "IP version (`1` for IPv4, `2` for IPv6, `0` if unknown).", "type": "integer", "example": 1 } } }, "digital-experience-monitoring_schemas-test-id": { "description": "The unique identifier for the test.", "type": "string", "example": "372e67954025e0ba6aaa6d586b9e0b59", "maxLength": 32, "readOnly": true }, "digital-experience-monitoring_since_minutes": { "description": "Number of minutes before current time.", "type": "number", "example": 10, "default": 10, "maximum": 60, "minimum": 1 }, "digital-experience-monitoring_sort_by": { "description": "Dimension to sort results by.", "type": "string", "default": "timestamp", "enum": [ "colo", "device_id", "mode", "platform", "status", "timestamp", "version" ] }, "digital-experience-monitoring_source": { "description": "Specifies fleet status details source.", "type": "string", "example": "last_seen", "default": "last_seen", "enum": [ "last_seen", "hourly", "raw" ] }, "digital-experience-monitoring_status": { "description": "Network status.", "type": "string", "example": "connected" }, "digital-experience-monitoring_test_stat_over_time": { "type": "object", "properties": { "avg": { "description": "average observed in the time period.", "type": "integer", "nullable": true }, "max": { "description": "highest observed in the time period.", "type": "integer", "nullable": true }, "min": { "description": "lowest observed in the time period.", "type": "integer", "nullable": true }, "slots": { "type": "array", "items": { "properties": { "timestamp": { "type": "string", "example": "2023-07-16 15:00:00+00" }, "value": { "type": "integer" } }, "required": [ "timestamp", "value" ], "type": "object" } } }, "required": [ "slots" ] }, "digital-experience-monitoring_test_stat_pct_over_time": { "type": "object", "properties": { "avg": { "description": "average observed in the time period.", "type": "number", "format": "float", "nullable": true }, "max": { "description": "highest observed in the time period.", "type": "number", "format": "float", "nullable": true }, "min": { "description": "lowest observed in the time period.", "type": "number", "format": "float", "nullable": true }, "slots": { "type": "array", "items": { "properties": { "timestamp": { "type": "string", "example": "2023-07-16 15:00:00+00" }, "value": { "type": "number", "format": "float" } }, "required": [ "timestamp", "value" ], "type": "object" } } }, "required": [ "slots" ] }, "digital-experience-monitoring_tests_response": { "type": "object", "properties": { "overviewMetrics": { "type": "object", "properties": { "avgHttpAvailabilityPct": { "description": "percentage availability for all HTTP test results in response.", "type": "number", "format": "float", "nullable": true }, "avgTracerouteAvailabilityPct": { "description": "percentage availability for all traceroutes results in response.", "type": "number", "format": "float", "nullable": true }, "testsTotal": { "description": "number of tests.", "type": "integer" } }, "required": [ "testsTotal" ] }, "tests": { "description": "array of test results objects.", "type": "array", "items": { "properties": { "created": { "description": "date the test was created.", "type": "string" }, "description": { "description": "the test description defined during configuration", "type": "string" }, "enabled": { "description": "if true, then the test will run on targeted devices. Else, the test will not run.", "type": "boolean" }, "host": { "type": "string" }, "httpResults": { "type": "object", "nullable": true, "properties": { "resourceFetchTime": { "$ref": "#/components/schemas/digital-experience-monitoring_timing_aggregates" } }, "required": [ "resourceFetchTime" ] }, "httpResultsByColo": { "type": "array", "items": { "properties": { "colo": { "description": "Cloudflare colo", "type": "string", "example": "SJC" }, "resourceFetchTime": { "$ref": "#/components/schemas/digital-experience-monitoring_timing_aggregates" } }, "required": [ "colo", "resourceFetchTime" ], "type": "object" } }, "id": { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" }, "interval": { "description": "The interval at which the synthetic application test is set to run.", "type": "string" }, "kind": { "description": "test type, http or traceroute", "type": "string", "enum": [ "http", "traceroute" ] }, "method": { "description": "for HTTP, the method to use when running the test", "type": "string" }, "name": { "description": "name given to this test", "type": "string" }, "target_policies": { "type": "array", "items": { "properties": { "default": { "description": "Whether the policy is the default for the account", "type": "boolean" }, "id": { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" }, "name": { "type": "string" } }, "required": [ "id", "name", "default" ], "type": "object" }, "nullable": true }, "targeted": { "type": "boolean" }, "tracerouteResults": { "type": "object", "nullable": true, "properties": { "roundTripTime": { "$ref": "#/components/schemas/digital-experience-monitoring_timing_aggregates" } }, "required": [ "roundTripTime" ] }, "tracerouteResultsByColo": { "type": "array", "items": { "properties": { "colo": { "description": "Cloudflare colo", "type": "string", "example": "SJC" }, "roundTripTime": { "$ref": "#/components/schemas/digital-experience-monitoring_timing_aggregates" } }, "required": [ "colo", "roundTripTime" ], "type": "object" } }, "updated": { "type": "string" } }, "required": [ "id", "name", "kind", "interval", "enabled", "description", "updated", "created", "host" ], "type": "object" } } }, "required": [ "overviewMetrics", "tests" ] }, "digital-experience-monitoring_time_now": { "description": "Current time. Timestamp can be provided in ISO 8601 datetime format or milliseconds since epoch.", "type": "string", "example": "2023-10-11T00:00:00Z" }, "digital-experience-monitoring_timeslot_cpu_apps": { "type": "object", "properties": { "timestamp": { "description": "Timestamp of the time slot.", "type": "string", "example": "2023-07-16 15:00:00+00" }, "value": { "description": "Top CPU-consuming applications for the time slot.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_cpu_pct_by_app" } } }, "required": [ "timestamp", "value" ] }, "digital-experience-monitoring_timeslot_float": { "type": "object", "properties": { "timestamp": { "description": "Timestamp of the time slot.", "type": "string", "example": "2023-07-16 15:00:00+00" }, "value": { "description": "Float metric value for the time slot.", "type": "number", "format": "float" } }, "required": [ "timestamp", "value" ] }, "digital-experience-monitoring_timeslot_int": { "type": "object", "properties": { "timestamp": { "description": "Timestamp of the time slot.", "type": "string", "example": "2023-07-16 15:00:00+00" }, "value": { "description": "Integer metric value for the time slot.", "type": "integer" } }, "required": [ "timestamp", "value" ] }, "digital-experience-monitoring_timeslot_ram_apps": { "type": "object", "properties": { "timestamp": { "description": "Timestamp of the time slot.", "type": "string", "example": "2023-07-16 15:00:00+00" }, "value": { "description": "Top RAM-consuming applications for the time slot.", "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_ram_used_pct_by_app" } } }, "required": [ "timestamp", "value" ] }, "digital-experience-monitoring_timeslot_rtt_stats": { "type": "object", "properties": { "timestamp": { "description": "Timestamp of the time slot.", "type": "string", "example": "2023-07-16 15:00:00+00" }, "value": { "description": "Round-trip time statistics for the time slot.", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_rtt_stats" } ] } }, "required": [ "timestamp", "value" ] }, "digital-experience-monitoring_timeslot_string": { "type": "object", "properties": { "timestamp": { "description": "Timestamp of the time slot.", "type": "string", "example": "2023-07-16 15:00:00+00" }, "value": { "description": "String metric value for the time slot.", "type": "string" } }, "required": [ "timestamp", "value" ] }, "digital-experience-monitoring_timeslot_tunnel_stats": { "type": "object", "properties": { "timestamp": { "description": "Timestamp of the time slot.", "type": "string", "example": "2023-07-16 15:00:00+00" }, "value": { "description": "WARP tunnel packet and byte counters measured within the stats window for the time slot.", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_tunnel_stats" } ] } }, "required": [ "timestamp", "value" ] }, "digital-experience-monitoring_timestamp": { "type": "string", "example": "2023-10-11 00:00:00+00" }, "digital-experience-monitoring_timestamp_datetime": { "description": "Timestamp in ISO 8601 datetime format.", "type": "string", "format": "date-time", "example": "2023-10-11T00:00:00Z" }, "digital-experience-monitoring_timing_aggregates": { "type": "object", "properties": { "avgMs": { "type": "integer", "nullable": true }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_aggregate_stat" } }, "overTime": { "type": "object", "nullable": true, "properties": { "timePeriod": { "$ref": "#/components/schemas/digital-experience-monitoring_aggregate_time_period" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/digital-experience-monitoring_aggregate_time_slot" } } }, "required": [ "values", "timePeriod" ] } }, "required": [ "history" ] }, "digital-experience-monitoring_traceroute_details_percentiles_response": { "type": "object", "properties": { "hopsCount": { "$ref": "#/components/schemas/digital-experience-monitoring_percentiles" }, "packetLossPct": { "$ref": "#/components/schemas/digital-experience-monitoring_percentiles" }, "roundTripTimeMs": { "$ref": "#/components/schemas/digital-experience-monitoring_percentiles" } } }, "digital-experience-monitoring_traceroute_details_response": { "type": "object", "properties": { "host": { "description": "The host of the Traceroute synthetic application test.", "type": "string", "example": "1.1.1.1" }, "interval": { "description": "The interval at which the Traceroute synthetic application test is set to run.", "type": "string", "example": "0h5m0s" }, "kind": { "enum": [ "traceroute" ] }, "name": { "description": "The name of the Traceroute synthetic application test.", "type": "string", "example": "Atlassian Sign In Page" }, "target_policies": { "type": "array", "items": { "properties": { "default": { "description": "Whether the policy is the default for the account.", "type": "boolean" }, "id": { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" }, "name": { "type": "string" } }, "required": [ "id", "name", "default" ], "type": "object" }, "nullable": true }, "targeted": { "type": "boolean" }, "tracerouteStats": { "type": "object", "nullable": true, "properties": { "availabilityPct": { "$ref": "#/components/schemas/digital-experience-monitoring_test_stat_pct_over_time" }, "hopsCount": { "$ref": "#/components/schemas/digital-experience-monitoring_test_stat_over_time" }, "packetLossPct": { "$ref": "#/components/schemas/digital-experience-monitoring_test_stat_pct_over_time" }, "roundTripTimeMs": { "$ref": "#/components/schemas/digital-experience-monitoring_test_stat_over_time" }, "uniqueDevicesTotal": { "description": "Count of unique devices that have run this test in the given time period.", "type": "integer", "example": 57 } }, "required": [ "uniqueDevicesTotal", "roundTripTimeMs", "hopsCount", "packetLossPct", "availabilityPct" ] }, "tracerouteStatsByColo": { "type": "array", "items": { "properties": { "availabilityPct": { "$ref": "#/components/schemas/digital-experience-monitoring_test_stat_pct_over_time" }, "colo": { "type": "string", "example": "DFW" }, "hopsCount": { "$ref": "#/components/schemas/digital-experience-monitoring_test_stat_over_time" }, "packetLossPct": { "$ref": "#/components/schemas/digital-experience-monitoring_test_stat_pct_over_time" }, "roundTripTimeMs": { "$ref": "#/components/schemas/digital-experience-monitoring_test_stat_over_time" }, "uniqueDevicesTotal": { "description": "Count of unique devices that have run this test in the given time period.", "type": "integer", "example": 57 } }, "required": [ "colo", "uniqueDevicesTotal", "roundTripTimeMs", "hopsCount", "packetLossPct", "availabilityPct" ], "type": "object" } } }, "required": [ "kind", "name", "host", "interval" ] }, "digital-experience-monitoring_traceroute_test_network_path_response": { "type": "object", "properties": { "deviceName": { "description": "Name of the device that ran the test.", "type": "string" }, "id": { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" }, "interval": { "description": "The interval at which the Traceroute synthetic application test is set to run.", "type": "string", "example": "0h5m0s" }, "kind": { "enum": [ "traceroute" ] }, "name": { "type": "string" }, "networkPath": { "type": "object", "nullable": true, "properties": { "sampling": { "description": "Specifies the sampling applied, if any, to the slots response. When sampled, results shown represent the first test run to the start of each sampling interval.", "type": "object", "nullable": true, "properties": { "unit": { "enum": [ "hours" ] }, "value": { "type": "integer" } }, "required": [ "value", "unit" ] }, "slots": { "type": "array", "items": { "properties": { "clientToAppRttMs": { "description": "Round trip time in ms of the client to app mile", "type": "integer", "nullable": true }, "clientToCfEgressRttMs": { "description": "Round trip time in ms of the client to Cloudflare egress mile", "type": "integer", "nullable": true }, "clientToCfIngressRttMs": { "description": "Round trip time in ms of the client to Cloudflare ingress mile", "type": "integer", "nullable": true }, "clientToIspRttMs": { "description": "Round trip time in ms of the client to ISP mile", "type": "integer", "nullable": true }, "id": { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" }, "timestamp": { "type": "string", "example": "2023-07-16 15:00:00+00" } }, "required": [ "id", "timestamp", "clientToAppRttMs", "clientToCfIngressRttMs", "clientToCfEgressRttMs" ], "type": "object" } } }, "required": [ "slots" ] }, "url": { "description": "The host of the Traceroute synthetic application test.", "type": "string", "example": "1.1.1.1" } }, "required": [ "id" ] }, "digital-experience-monitoring_traceroute_test_result_network_path_response": { "type": "object", "properties": { "colo": { "$ref": "#/components/schemas/digital-experience-monitoring_colo" }, "deviceName": { "description": "Name of the device associated with this network path response.", "type": "string" }, "execution_context": { "description": "Whether the test was run inside or outside of the WARP tunnel.", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_execution_context" } ] }, "hops": { "description": "An array of the hops taken by the device to reach the end destination.", "type": "array", "items": { "properties": { "asn": { "type": "integer", "nullable": true }, "aso": { "type": "string", "nullable": true }, "ipAddress": { "type": "string", "nullable": true }, "location": { "type": "object", "nullable": true, "properties": { "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zip": { "type": "string", "nullable": true } } }, "mile": { "type": "string", "enum": [ "client-to-app", "client-to-cf-egress", "client-to-cf-ingress", "client-to-isp" ], "nullable": true }, "name": { "type": "string", "nullable": true }, "packetLossPct": { "type": "number", "format": "float", "nullable": true }, "rttMs": { "type": "integer", "nullable": true }, "ttl": { "type": "integer" } }, "required": [ "ttl" ], "type": "object" } }, "resultId": { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" }, "testId": { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" }, "testName": { "description": "Name of the traceroute test.", "type": "string" }, "time_start": { "description": "Timestamp indicating when the traceroute test execution began.", "type": "string", "example": "2023-07-16 15:00:00+00" }, "tunnel_type": { "type": "string", "nullable": true } }, "required": [ "resultId", "hops" ] }, "digital-experience-monitoring_tunnel_stats": { "description": "WARP tunnel packet and byte counters.", "type": "object", "properties": { "bytesLost": { "description": "Number of bytes lost, split by direction.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_directional_stat" } ], "nullable": true }, "bytesReceived": { "description": "Number of bytes received, split by direction.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_directional_stat" } ], "nullable": true }, "bytesRetransmitted": { "description": "Number of bytes retransmitted, split by direction.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_directional_stat" } ], "nullable": true }, "bytesSent": { "description": "Number of bytes sent, split by direction.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_directional_stat" } ], "nullable": true }, "packetsLost": { "description": "Number of packets lost, split by direction.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_directional_stat" } ], "nullable": true }, "packetsReceived": { "description": "Number of packets received, split by direction.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_directional_stat" } ], "nullable": true }, "packetsRetransmitted": { "description": "Number of packets retransmitted, split by direction.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_directional_stat" } ], "nullable": true }, "packetsSent": { "description": "Number of packets sent, split by direction.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_directional_stat" } ], "nullable": true }, "statsWindowMs": { "description": "The measurement window duration in milliseconds.", "type": "integer", "nullable": true } } }, "digital-experience-monitoring_uniqueDevicesTotal": { "description": "Number of unique devices", "type": "number" }, "digital-experience-monitoring_unique_devices_response": { "type": "object", "properties": { "uniqueDevicesTotal": { "description": "total number of unique devices", "type": "integer" } }, "required": [ "uniqueDevicesTotal" ] }, "digital-experience-monitoring_uuid": { "description": "API Resource UUID tag.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36 }, "digital-experience-monitoring_version": { "description": "WARP client version.", "type": "string", "example": "1.0.0" }, "digital-experience-monitoring_warp_config_change_event": { "type": "object", "properties": { "device_id": { "description": "The device ID.", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" } ] }, "device_registration": { "description": "Deprecated: use registration_id. The device registration ID.", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" } ], "deprecated": true, "x-stainless-deprecation-message": "Use `registration_id` instead." }, "from": { "description": "The details for the WARP configuration that was switched from.", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_warp_config_details" } ] }, "hostname": { "description": "The hostname of the machine the event is from.", "type": "string" }, "registration_id": { "description": "The device registration ID.", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" } ] }, "serial_number": { "description": "The serial number of the machine the event is from.", "type": "string" }, "timestamp": { "description": "The event time.", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_timestamp_datetime" } ] }, "to": { "description": "The details for the WARP configuration that was switched to.", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_warp_config_details" } ] }, "user_email": { "description": "Email tied to the device.", "type": "string" } } }, "digital-experience-monitoring_warp_config_details": { "type": "object", "properties": { "account_name": { "description": "The account name.", "type": "string" }, "account_tag": { "description": "The public account identifier.", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" } ] }, "config_name": { "description": "The name of the WARP configuration.", "type": "string" } } }, "digital-experience-monitoring_warp_events_response": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_warp_toggle_change_event" }, { "$ref": "#/components/schemas/digital-experience-monitoring_warp_config_change_event" } ] } }, "digital-experience-monitoring_warp_toggle_change_event": { "type": "object", "properties": { "account_name": { "description": "The account name.", "type": "string" }, "account_tag": { "description": "The public account identifier.", "type": "string" }, "device_id": { "description": "The device ID.", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" } ] }, "device_registration": { "description": "Deprecated: use registration_id. The device registration ID.", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" } ], "deprecated": true, "x-stainless-deprecation-message": "Use `registration_id` instead." }, "hostname": { "description": "The hostname of the machine the event is from.", "type": "string" }, "registration_id": { "description": "The device registration ID.", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_uuid" } ] }, "serial_number": { "description": "The serial number of the machine the event is from.", "type": "string" }, "timestamp": { "description": "The event time.", "allOf": [ { "$ref": "#/components/schemas/digital-experience-monitoring_timestamp_datetime" } ] }, "toggle": { "description": "The state of the WARP toggle.", "type": "string", "enum": [ "on", "off" ] }, "user_email": { "description": "Email tied to the device.", "type": "string" } } }, "dlp_AddinAccountMapping": { "type": "object", "properties": { "addin_identifier_token": { "type": "string", "format": "uuid" }, "auth_requirements": { "$ref": "#/components/schemas/dlp_AddinAuth" } }, "required": [ "auth_requirements", "addin_identifier_token" ] }, "dlp_AddinAuth": { "oneOf": [ { "properties": { "allowed_microsoft_organizations": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "Org" ] } }, "required": [ "allowed_microsoft_organizations", "type" ], "type": "object" }, { "properties": { "type": { "type": "string", "enum": [ "NoAuth" ] } }, "required": [ "type" ], "type": "object" } ] }, "dlp_Behavior": { "type": "object", "properties": { "description": { "type": "string" }, "enabled": { "type": "boolean" }, "name": { "type": "string" }, "risk_level": { "$ref": "#/components/schemas/dlp_RiskLevel" } }, "required": [ "name", "description", "risk_level", "enabled" ] }, "dlp_Behaviors": { "type": "object", "properties": { "behaviors": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/dlp_Behavior" } } }, "required": [ "behaviors" ] }, "dlp_Confidence": { "type": "string", "enum": [ "low", "medium", "high", "very_high" ] }, "dlp_ContextAwareness": { "description": "Scan the context of predefined entries to only return matches surrounded by keywords.", "type": "object", "properties": { "enabled": { "description": "If true, scan the context of predefined entries to only return matches surrounded by keywords.", "type": "boolean" }, "skip": { "$ref": "#/components/schemas/dlp_SkipConfig" } }, "deprecated": true, "required": [ "enabled", "skip" ] }, "dlp_CreateEmailRule": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/dlp_EmailRuleAction" }, "conditions": { "description": "Triggered if all conditions match.", "type": "array", "items": { "$ref": "#/components/schemas/dlp_EmailRuleCondition" } }, "description": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "name", "enabled", "conditions", "action" ] }, "dlp_CreateIntegrationBody": { "type": "object", "properties": { "integration_type": { "$ref": "#/components/schemas/dlp_RiskScoreIntegrationType" }, "reference_id": { "description": "A reference id that can be supplied by the client. Currently this should be set to the Access-Okta IDP ID (a UUIDv4).\nhttps://developers.cloudflare.com/api/operations/access-identity-providers-get-an-access-identity-provider", "type": "string", "nullable": true }, "tenant_url": { "description": "The base url of the tenant, e.g. \"https://tenant.okta.com\".", "type": "string", "format": "uri" } }, "required": [ "integration_type", "tenant_url" ] }, "dlp_CustomEntry": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string", "nullable": true }, "enabled": { "type": "boolean", "deprecated": true }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "pattern": { "$ref": "#/components/schemas/dlp_Pattern" }, "profile_id": { "type": "string", "format": "uuid", "deprecated": true, "nullable": true }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "created_at", "updated_at", "pattern", "enabled" ] }, "dlp_CustomEntryUpdate": { "allOf": [ { "$ref": "#/components/schemas/dlp_CustomEntryUpdateType" }, { "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "type": "object" } ] }, "dlp_CustomEntryUpdateType": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "name": { "type": "string" }, "pattern": { "$ref": "#/components/schemas/dlp_Pattern" } }, "required": [ "name", "pattern" ] }, "dlp_CustomProfile": { "type": "object", "properties": { "ai_context_enabled": { "type": "boolean", "default": false }, "allowed_match_count": { "description": "Related DLP policies will trigger when the match count exceeds the number set.", "type": "integer", "format": "int32", "example": 5, "default": 0, "maximum": 1000, "minimum": 0 }, "confidence_threshold": { "default": "low", "allOf": [ { "$ref": "#/components/schemas/dlp_Confidence" } ] }, "context_awareness": { "$ref": "#/components/schemas/dlp_ContextAwareness" }, "created_at": { "description": "When the profile was created.", "type": "string", "format": "date-time" }, "data_classes": { "description": "Data classes associated with this profile.", "type": "array", "items": { "format": "uuid", "type": "string" } }, "data_tags": { "description": "Data tags associated with this profile.", "type": "array", "items": { "format": "uuid", "type": "string" } }, "description": { "description": "The description of the profile.", "type": "string", "nullable": true }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_Entry" }, "deprecated": true, "x-stainless-skip": [ "terraform" ] }, "id": { "description": "The id of the profile (uuid).", "type": "string", "format": "uuid" }, "name": { "description": "The name of the profile.", "type": "string", "x-auditable": true }, "ocr_enabled": { "type": "boolean", "default": false }, "sensitivity_levels": { "description": "Sensitivity levels associated with this profile.", "type": "array", "items": { "$ref": "#/components/schemas/dlp_SensitivityLevelRef" } }, "shared_entries": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_Entry" }, "x-stainless-terraform-configurability": "computed" }, "updated_at": { "description": "When the profile was lasted updated.", "type": "string", "format": "date-time" } }, "required": [ "id", "name", "created_at", "updated_at", "allowed_match_count", "ocr_enabled" ] }, "dlp_CustomProfileArray": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_CustomProfile" } }, "dlp_CustomProfileUpdate": { "type": "object", "properties": { "ai_context_enabled": { "type": "boolean", "default": false }, "allowed_match_count": { "type": "integer", "format": "int32", "nullable": true }, "confidence_threshold": { "type": "string", "default": "low", "nullable": true }, "context_awareness": { "$ref": "#/components/schemas/dlp_ContextAwareness" }, "data_classes": { "description": "Data class IDs to associate with the profile. If omitted, existing associations are unchanged.", "type": "array", "items": { "format": "uuid", "type": "string" }, "nullable": true }, "data_tags": { "description": "Data tag IDs to associate with the profile. If omitted, existing associations are unchanged.", "type": "array", "items": { "format": "uuid", "type": "string" }, "nullable": true }, "description": { "description": "The description of the profile.", "type": "string", "nullable": true }, "entries": { "description": "Custom entries from this profile.\nIf this field is omitted, entries owned by this profile will not be changed.", "type": "array", "items": { "$ref": "#/components/schemas/dlp_ProfileEntryUpdate" }, "deprecated": true, "nullable": true }, "name": { "type": "string" }, "ocr_enabled": { "type": "boolean", "default": false }, "sensitivity_levels": { "description": "Sensitivity levels to associate with the profile. If omitted, existing associations are unchanged.", "type": "array", "items": { "$ref": "#/components/schemas/dlp_SensitivityLevelRef" }, "nullable": true }, "shared_entries": { "description": "Other entries, e.g. predefined or integration.", "type": "array", "items": { "$ref": "#/components/schemas/dlp_SharedEntryUpdate" } } }, "required": [ "name" ] }, "dlp_CustomPromptTopic": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string", "nullable": true }, "enabled": { "type": "boolean", "deprecated": true }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "profile_id": { "type": "string", "format": "uuid", "deprecated": true, "nullable": true }, "topic": { "type": "string", "maxLength": 50, "minLength": 2 }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "created_at", "updated_at", "enabled", "topic" ] }, "dlp_CustomPromptTopicEntry": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "description": "The optional description of the custom prompt topic entry.", "type": "string", "nullable": true }, "enabled": { "type": "boolean", "deprecated": true }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "created_at", "updated_at", "enabled" ] }, "dlp_CustomPromptTopicUpdate": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "name": { "type": "string" }, "topic": { "type": "string", "maxLength": 50, "minLength": 2 } }, "required": [ "name", "enabled", "topic" ] }, "dlp_DataClass": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "data_tags": { "type": "array", "items": { "format": "uuid", "type": "string" } }, "description": { "type": "string", "nullable": true }, "expression": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sensitivity_levels": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_SensitivityLevelRef" } }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "expression", "sensitivity_levels", "data_tags", "created_at", "updated_at" ] }, "dlp_DataClassArray": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_DataClass" } }, "dlp_DataClassUpdate": { "type": "object", "properties": { "data_tags": { "type": "array", "items": { "format": "uuid", "type": "string" }, "nullable": true }, "description": { "type": "string", "nullable": true }, "expression": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "sensitivity_levels": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_SensitivityLevelRef" }, "nullable": true } } }, "dlp_DataTag": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "created_at", "updated_at" ] }, "dlp_DataTagArray": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_DataTag" } }, "dlp_DataTagCategory": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_DataTag" } }, "template_id": { "type": "string", "format": "uuid", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "created_at", "updated_at", "tags" ] }, "dlp_DataTagCategoryArray": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_DataTagCategory" } }, "dlp_DataTagCategoryTagUpdate": { "allOf": [ { "$ref": "#/components/schemas/dlp_DataTagUpdate" }, { "properties": { "id": { "description": "If `None` (omitted), a new tag will be created. Otherwise, an existing tag will be\nupdated.", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } ] }, "dlp_DataTagCategoryTemplate": { "type": "object", "properties": { "description": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_DataTagTemplate" } } }, "required": [ "id", "name", "description", "tags" ] }, "dlp_DataTagCategoryTemplateArray": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_DataTagCategoryTemplate" } }, "dlp_DataTagCategoryUpdate": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "tags": { "description": "The desired final state of tags.\n- `None` (omitted): no tag changes.\n- `Some([])`: delete all tags.\n- `Some([...])`: desired final set + order.", "type": "array", "items": { "$ref": "#/components/schemas/dlp_DataTagCategoryTagUpdate" }, "nullable": true, "x-stainless-skip": [ "terraform" ] } } }, "dlp_DataTagTemplate": { "type": "object", "properties": { "description": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "description" ] }, "dlp_DataTagUpdate": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } } }, "dlp_Dataset": { "type": "object", "properties": { "case_sensitive": { "type": "boolean" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_DatasetColumn" } }, "created_at": { "type": "string", "format": "date-time" }, "description": { "description": "The description of the dataset.", "type": "string", "nullable": true }, "encoding_version": { "type": "integer", "format": "int32", "minimum": 0 }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "num_cells": { "type": "integer", "format": "int64" }, "secret": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/dlp_DatasetUploadStatus" }, "updated_at": { "description": "Stores when the dataset was last updated.\n\nThis includes name or description changes as well as uploads.", "type": "string", "format": "date-time" }, "uploads": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_DatasetUpload" } } }, "required": [ "name", "id", "status", "num_cells", "created_at", "updated_at", "uploads", "secret", "encoding_version", "columns" ] }, "dlp_DatasetArray": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_Dataset" } }, "dlp_DatasetColumn": { "type": "object", "properties": { "entry_id": { "type": "string", "format": "uuid" }, "header_name": { "type": "string" }, "num_cells": { "type": "integer", "format": "int64" }, "upload_status": { "$ref": "#/components/schemas/dlp_DatasetUploadStatus" } }, "required": [ "entry_id", "upload_status", "header_name", "num_cells" ] }, "dlp_DatasetColumnArray": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_DatasetColumn" } }, "dlp_DatasetCreation": { "type": "object", "properties": { "dataset": { "$ref": "#/components/schemas/dlp_Dataset" }, "encoding_version": { "description": "Encoding version to use for dataset.", "type": "integer", "format": "int32", "minimum": 0 }, "max_cells": { "type": "integer", "format": "int64", "minimum": 0 }, "secret": { "description": "The secret to use for Exact Data Match datasets.\n\nThis is not present in Custom Wordlists.", "type": "string", "format": "password" }, "version": { "description": "The version to use when uploading the dataset.", "type": "integer", "format": "int64" } }, "required": [ "version", "max_cells", "dataset", "encoding_version" ] }, "dlp_DatasetNewVersion": { "type": "object", "properties": { "case_sensitive": { "type": "boolean" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_DatasetColumn" } }, "encoding_version": { "type": "integer", "format": "int32", "minimum": 0 }, "max_cells": { "type": "integer", "format": "int64", "minimum": 0 }, "secret": { "type": "string", "format": "password" }, "version": { "type": "integer", "format": "int64" } }, "required": [ "version", "max_cells", "encoding_version" ] }, "dlp_DatasetUpdate": { "type": "object", "properties": { "case_sensitive": { "description": "Determines if the words should be matched in a case-sensitive manner.\n\nOnly required for custom word lists.", "type": "boolean" }, "description": { "description": "The description of the dataset.", "type": "string", "nullable": true }, "name": { "description": "The name of the dataset, must be unique.", "type": "string", "nullable": true } } }, "dlp_DatasetUpload": { "type": "object", "properties": { "num_cells": { "type": "integer", "format": "int64" }, "status": { "$ref": "#/components/schemas/dlp_DatasetUploadStatus" }, "version": { "type": "integer", "format": "int64" } }, "required": [ "version", "status", "num_cells" ] }, "dlp_DatasetUploadStatus": { "type": "string", "enum": [ "empty", "uploading", "pending", "processing", "failed", "complete" ] }, "dlp_DlpSettings": { "description": "DLP account-level settings response.", "type": "object", "properties": { "ai_context_analysis": { "description": "Whether AI context analysis is enabled at the account level.", "type": "boolean" }, "ocr": { "description": "Whether OCR is enabled at the account level.", "type": "boolean" }, "payload_logging": { "$ref": "#/components/schemas/dlp_PayloadLogSetting" } }, "required": [ "payload_logging", "ai_context_analysis", "ocr" ] }, "dlp_DlpSettingsUpdate": { "description": "Request model for updating DLP account-level settings.\nAll fields are optional. Missing fields behave differently for PUT vs PATCH:\n- PUT: missing fields reset to initial (unconfigured) values.\n- PATCH: missing fields keep existing values.", "type": "object", "properties": { "ai_context_analysis": { "description": "Whether AI context analysis is enabled at the account level.", "type": "boolean", "default": false, "nullable": true, "x-stainless-terraform-configurability": "computed_optional" }, "ocr": { "description": "Whether OCR is enabled at the account level.", "type": "boolean", "default": false, "nullable": true, "x-stainless-terraform-configurability": "computed_optional" }, "payload_logging": { "allOf": [ { "$ref": "#/components/schemas/dlp_PayloadLogSettingUpdate" } ], "x-stainless-terraform-configurability": "computed_optional" } } }, "dlp_DocumentFingerprint": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string", "default": "" }, "entry_id": { "type": "string", "format": "uuid" }, "file_name": { "type": "string", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "match_percent": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/dlp_DatasetUploadStatus" }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int64", "nullable": true } }, "required": [ "id", "entry_id", "name", "description", "match_percent", "status", "created_at", "updated_at" ] }, "dlp_DocumentFingerprintArray": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_DocumentFingerprint" } }, "dlp_DocumentFingerprintEntry": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "description": "The optional description of the document fingerprint entry.", "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "created_at", "updated_at", "enabled" ] }, "dlp_DocumentFingerprintUpload": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "entry_id": { "type": "string", "format": "uuid" }, "file_name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "match_percent": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/dlp_DatasetUploadStatus" }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int64" } }, "required": [ "id", "entry_id", "name", "description", "match_percent", "version", "file_name", "status", "created_at", "updated_at" ] }, "dlp_EmailRule": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/dlp_EmailRuleAction" }, "conditions": { "description": "Triggered if all conditions match.", "type": "array", "items": { "$ref": "#/components/schemas/dlp_EmailRuleCondition" } }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "name": { "type": "string" }, "priority": { "type": "integer", "format": "int32", "minimum": 0 }, "rule_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "rule_id", "name", "priority", "enabled", "conditions", "action", "created_at", "updated_at" ] }, "dlp_EmailRuleAction": { "oneOf": [ { "properties": { "action": { "type": "string", "enum": [ "Block" ] }, "message": { "type": "string", "nullable": true } }, "required": [ "action" ], "type": "object" } ] }, "dlp_EmailRuleArray": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_EmailRule" } }, "dlp_EmailRuleCondition": { "type": "object", "properties": { "operator": { "$ref": "#/components/schemas/dlp_EmailRuleOperator" }, "selector": { "$ref": "#/components/schemas/dlp_EmailRuleSelector" }, "value": { "$ref": "#/components/schemas/dlp_EmailRuleValue" } }, "required": [ "selector", "operator", "value" ] }, "dlp_EmailRuleOperator": { "type": "string", "enum": [ "InList", "NotInList", "MatchRegex", "NotMatchRegex" ] }, "dlp_EmailRuleSelector": { "type": "string", "enum": [ "Recipients", "Sender", "DLPProfiles" ] }, "dlp_EmailRuleValue": { "oneOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "string" } ] }, "dlp_Empty": { "type": "object", "nullable": true }, "dlp_Entry": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/dlp_CustomEntry" }, { "properties": { "type": { "type": "string", "enum": [ "custom" ] } }, "required": [ "type" ], "type": "object" } ], "title": "Custom Entry" }, { "allOf": [ { "$ref": "#/components/schemas/dlp_CustomPromptTopicEntry" }, { "properties": { "type": { "type": "string", "enum": [ "custom_prompt_topic" ] } }, "required": [ "type" ], "type": "object" } ], "title": "Custom Prompt Topic Entry" }, { "allOf": [ { "$ref": "#/components/schemas/dlp_PredefinedEntry" }, { "properties": { "type": { "type": "string", "enum": [ "predefined" ] } }, "required": [ "type" ], "type": "object" } ], "title": "Predefined Entry" }, { "allOf": [ { "$ref": "#/components/schemas/dlp_IntegrationEntry" }, { "properties": { "type": { "type": "string", "enum": [ "integration" ] } }, "required": [ "type" ], "type": "object" } ], "title": "Integration Entry" }, { "allOf": [ { "$ref": "#/components/schemas/dlp_ExactDataEntry" }, { "properties": { "type": { "type": "string", "enum": [ "exact_data" ] } }, "required": [ "type" ], "type": "object" } ], "title": "Exact Data Entry" }, { "allOf": [ { "$ref": "#/components/schemas/dlp_DocumentFingerprintEntry" }, { "properties": { "type": { "type": "string", "enum": [ "document_fingerprint" ] } }, "required": [ "type" ], "type": "object" } ], "title": "Document Fingerprint Entry" }, { "allOf": [ { "$ref": "#/components/schemas/dlp_WordListEntry" }, { "properties": { "type": { "type": "string", "enum": [ "word_list" ] } }, "required": [ "type" ], "type": "object" } ], "title": "Word List Entry" } ] }, "dlp_EntryConfidence": { "type": "object", "properties": { "ai_context_available": { "description": "Indicates whether this entry has AI remote service validation.", "type": "boolean" }, "available": { "description": "Indicates whether this entry has any form of validation that is not an AI remote service.", "type": "boolean" } }, "required": [ "available", "ai_context_available" ] }, "dlp_EntryOfNewProfile": { "oneOf": [ { "$ref": "#/components/schemas/dlp_NewCustomEntry" }, { "$ref": "#/components/schemas/dlp_NewWordListEntry" } ] }, "dlp_EntryProfile": { "description": "Computed entry field for a profile that an entry is shared into.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "dlp_EntryUpdate": { "allOf": [ { "$ref": "#/components/schemas/dlp_EntryUpdateType" }, { "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "type": "object" } ] }, "dlp_EntryUpdateType": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/dlp_CustomEntryUpdateType" }, { "properties": { "type": { "type": "string", "enum": [ "custom" ] } }, "required": [ "type" ], "type": "object" } ] }, { "properties": { "type": { "type": "string", "enum": [ "predefined" ] } }, "required": [ "type" ], "type": "object" }, { "properties": { "type": { "type": "string", "enum": [ "integration" ] } }, "required": [ "type" ], "type": "object" } ] }, "dlp_EntryWithSharedProfiles": { "allOf": [ { "$ref": "#/components/schemas/dlp_EntryWithUploadStatus" }, { "properties": { "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_EntryProfile" }, "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "profiles" ], "type": "object" } ] }, "dlp_EntryWithUploadStatus": { "allOf": [ { "$ref": "#/components/schemas/dlp_Entry" }, { "properties": { "upload_status": { "allOf": [ { "$ref": "#/components/schemas/dlp_DatasetUploadStatus" } ], "x-stainless-terraform-configurability": "computed_optional" } }, "type": "object" } ] }, "dlp_ExactDataEntry": { "type": "object", "properties": { "case_sensitive": { "description": "Only applies to custom word lists.\nDetermines if the words should be matched in a case-sensitive manner\nCannot be set to false if secret is true", "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "description": "The optional description of the exact data entry.", "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "secret": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "created_at", "updated_at", "enabled", "secret", "case_sensitive" ] }, "dlp_IntegrationEntry": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "profile_id": { "type": "string", "format": "uuid", "nullable": true, "x-stainless-terraform-configurability": "computed_optional" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "created_at", "updated_at", "enabled" ] }, "dlp_IntegrationProfile": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "description": "The description of the profile.", "type": "string", "nullable": true }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_Entry" }, "deprecated": true }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "shared_entries": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_Entry" }, "x-stainless-terraform-configurability": "computed" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "entries", "shared_entries", "created_at", "updated_at" ] }, "dlp_Limits": { "type": "object", "properties": { "max_custom_regex_entries": { "description": "Maximum number of custom regex entries allowed for the account.", "type": "integer", "format": "int64", "minimum": 0 }, "max_dataset_cells": { "description": "Maximum number of dataset cells allowed for the account, across all EDM and CWL datasets.", "type": "integer", "format": "int64", "minimum": 0 }, "max_document_fingerprints": { "description": "Maximum number of document fingerprints allowed for the account.", "type": "integer", "format": "int64", "minimum": 0 }, "used_custom_regex_entries": { "description": "Number of custom regex entries currently configured for the account.", "type": "integer", "format": "int64", "minimum": 0 }, "used_dataset_cells": { "description": "Number of dataset cells currently configured for the account, across all EDM and CWL datasets. Document fingerprints do not count towards this limit.", "type": "integer", "format": "int64", "minimum": 0 }, "used_document_fingerprints": { "description": "Number of document fingerprints currently configured for the account.", "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "max_custom_regex_entries", "used_custom_regex_entries", "max_dataset_cells", "used_dataset_cells", "max_document_fingerprints", "used_document_fingerprints" ] }, "dlp_NewCustomEntry": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "name": { "type": "string" }, "pattern": { "$ref": "#/components/schemas/dlp_Pattern" } }, "required": [ "name", "pattern", "enabled" ] }, "dlp_NewCustomEntryWithId": { "allOf": [ { "$ref": "#/components/schemas/dlp_NewCustomEntry" }, { "properties": { "entry_id": { "type": "string", "format": "uuid" } }, "required": [ "entry_id" ], "type": "object" } ] }, "dlp_NewCustomProfile": { "type": "object", "properties": { "ai_context_enabled": { "type": "boolean", "default": false }, "allowed_match_count": { "description": "Related DLP policies will trigger when the match count exceeds the number set.", "type": "integer", "format": "int32", "example": 5, "default": 0, "maximum": 1000, "minimum": 0 }, "confidence_threshold": { "type": "string", "default": "low", "nullable": true }, "context_awareness": { "$ref": "#/components/schemas/dlp_ContextAwareness" }, "data_classes": { "description": "Data class IDs to associate with the profile.", "type": "array", "items": { "format": "uuid", "type": "string" } }, "data_tags": { "description": "Data tag IDs to associate with the profile.", "type": "array", "items": { "format": "uuid", "type": "string" } }, "description": { "description": "The description of the profile.", "type": "string", "nullable": true }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_EntryOfNewProfile" }, "x-stainless-skip": [ "terraform" ] }, "name": { "type": "string" }, "ocr_enabled": { "type": "boolean", "default": false }, "sensitivity_levels": { "description": "Sensitivity levels to associate with the profile.", "type": "array", "items": { "$ref": "#/components/schemas/dlp_SensitivityLevelRef" } }, "shared_entries": { "description": "Entries from other profiles (e.g. pre-defined Cloudflare profiles, or your Microsoft Information Protection profiles).", "type": "array", "items": { "$ref": "#/components/schemas/dlp_NewSharedEntry" } } }, "required": [ "name" ] }, "dlp_NewCustomPromptTopic": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "name": { "type": "string" }, "profile_id": { "type": "string", "format": "uuid" }, "topic": { "type": "string", "maxLength": 50, "minLength": 2 } }, "required": [ "name", "enabled", "topic" ] }, "dlp_NewDataClass": { "type": "object", "properties": { "data_tags": { "type": "array", "items": { "format": "uuid", "type": "string" } }, "description": { "type": "string", "nullable": true }, "expression": { "type": "string" }, "name": { "type": "string" }, "sensitivity_levels": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_SensitivityLevelRef" } } }, "required": [ "name", "expression", "sensitivity_levels", "data_tags" ] }, "dlp_NewDataTag": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "name": { "type": "string" } }, "required": [ "name" ] }, "dlp_NewDataTagCategory": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "name": { "type": "string" }, "tags": { "description": "Tags to create with the category. Mutually exclusive with `template_id`.", "type": "array", "items": { "$ref": "#/components/schemas/dlp_NewDataTag" }, "x-stainless-skip": [ "terraform" ] }, "template_id": { "type": "string", "format": "uuid", "nullable": true, "x-stainless-skip": [ "terraform" ] } }, "required": [ "name" ] }, "dlp_NewDataset": { "type": "object", "properties": { "case_sensitive": { "description": "Only applies to custom word lists.\nDetermines if the words should be matched in a case-sensitive manner\nCannot be set to false if `secret` is true or undefined", "type": "boolean" }, "description": { "description": "The description of the dataset.", "type": "string", "nullable": true }, "encoding_version": { "description": "Dataset encoding version\n\nNon-secret custom word lists with no header are always version 1.\nSecret EDM lists with no header are version 1.\nMulticolumn CSV with headers are version 2.\nOmitting this field provides the default value 0, which is interpreted\nthe same as 1.", "type": "integer", "format": "int32", "minimum": 0 }, "name": { "type": "string" }, "secret": { "description": "Generate a secret dataset.\n\nIf true, the response will include a secret to use with the EDM encoder.\nIf false, the response has no secret and the dataset is uploaded in plaintext.", "type": "boolean" } }, "required": [ "name" ] }, "dlp_NewDatasetColumn": { "allOf": [ { "oneOf": [ { "properties": { "entry_id": { "type": "string", "format": "uuid" } }, "required": [ "entry_id" ], "title": "Existing Column", "type": "object" }, { "properties": { "entry_name": { "type": "string" } }, "required": [ "entry_name" ], "title": "New Column", "type": "object" } ] }, { "properties": { "header_name": { "type": "string" }, "num_cells": { "type": "integer", "format": "int64", "minimum": 0 } }, "required": [ "header_name", "num_cells" ], "type": "object" } ] }, "dlp_NewDocumentFingerprint": { "type": "object", "properties": { "description": { "type": "string", "default": "" }, "match_percent": { "type": "integer", "format": "int32" }, "name": { "type": "string" } }, "required": [ "name", "match_percent" ] }, "dlp_NewEntry": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "name": { "type": "string" }, "pattern": { "$ref": "#/components/schemas/dlp_Pattern" }, "profile_id": { "type": "string", "format": "uuid" } }, "required": [ "name", "pattern", "enabled" ] }, "dlp_NewPredefinedEntry": { "description": "Used to create a new predefined or integration entry.\n\nPredefined or integration entries can not be updated via the API so\nthese fields will update the entry's settings.", "type": "object", "properties": { "enabled": { "type": "boolean" }, "entry_id": { "type": "string", "format": "uuid" }, "profile_id": { "description": "This field is not used as the owning profile.\nFor predefined entries it is already set to a predefined profile.", "type": "string", "format": "uuid", "nullable": true } }, "required": [ "enabled", "entry_id" ] }, "dlp_NewPredefinedProfile": { "allOf": [ { "$ref": "#/components/schemas/dlp_PredefinedProfileUpdate" }, { "properties": { "profile_id": { "type": "string", "format": "uuid" } }, "required": [ "profile_id" ], "type": "object" } ] }, "dlp_NewSensitivityGroup": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "levels": { "description": "Levels to create with the group. Mutually exclusive with `template_id`.", "type": "array", "items": { "$ref": "#/components/schemas/dlp_NewSensitivityLevel" }, "x-stainless-skip": [ "terraform" ] }, "name": { "type": "string" }, "template_id": { "type": "string", "format": "uuid", "nullable": true, "x-stainless-skip": [ "terraform" ] } }, "required": [ "name" ] }, "dlp_NewSensitivityLevel": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "name": { "type": "string" } }, "required": [ "name" ] }, "dlp_NewSharedEntry": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "entry_id": { "type": "string", "format": "uuid" } }, "required": [ "entry_id", "enabled" ] }, "dlp_NewWordListEntry": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "name": { "type": "string" }, "words": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "words", "enabled" ] }, "dlp_Pattern": { "type": "object", "properties": { "regex": { "type": "string" }, "validation": { "allOf": [ { "$ref": "#/components/schemas/dlp_Validation" } ] } }, "required": [ "regex" ] }, "dlp_PayloadLogMaskingLevel": { "description": "Masking level for payload logs.\n\n- `full`: The entire payload is masked.\n- `partial`: Only partial payload content is masked.\n- `clear`: No masking is applied to the payload content.\n- `default`: DLP uses its default masking behavior.", "type": "string", "enum": [ "full", "partial", "clear", "default" ] }, "dlp_PayloadLogSetting": { "type": "object", "properties": { "masking_level": { "allOf": [ { "$ref": "#/components/schemas/dlp_PayloadLogMaskingLevel" } ] }, "public_key": { "description": "Base64-encoded public key for encrypting payload logs. Null when payload logging is disabled.", "type": "string", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "updated_at" ] }, "dlp_PayloadLogSettingUpdate": { "description": "Request model for payload log settings within the DLP settings endpoint.\nUnlike the legacy endpoint, null and missing are treated identically here\n(both mean \"not provided\" for PATCH, \"reset to default\" for PUT).", "type": "object", "properties": { "masking_level": { "default": "default", "allOf": [ { "$ref": "#/components/schemas/dlp_PayloadLogMaskingLevel" } ] }, "public_key": { "description": "Base64-encoded public key for encrypting payload logs.\n\n- Set to a non-empty base64 string to enable payload logging with the given key.\n- Set to an empty string to disable payload logging.\n- Omit or set to null to leave unchanged (PATCH) or reset to disabled (PUT).", "type": "string", "nullable": true } } }, "dlp_PayloadLogSettingUpdateLegacy": { "description": "Request model for the legacy payload log settings endpoint.", "type": "object", "properties": { "masking_level": { "allOf": [ { "$ref": "#/components/schemas/dlp_PayloadLogMaskingLevel" } ] }, "public_key": { "description": "Base64-encoded public key for encrypting payload logs.\n\n- Set to null or empty string to disable payload logging.\n- Set to a non-empty base64 string to enable payload logging with the given key.\n\nFor customers with configurable payload masking feature rolled out:\n- If the field is missing, the existing setting will be kept. Note that this is different from setting to null or empty string.\n\nFor all other customers:\n- If the field is missing, the existing setting will be cleared.", "type": "string", "nullable": true } } }, "dlp_PredefinedEntry": { "type": "object", "properties": { "confidence": { "$ref": "#/components/schemas/dlp_EntryConfidence" }, "deprecated": { "description": "Whether this entry is deprecated for new use. This is computed from the static catalog and\nemitted only when true.", "type": "boolean", "default": false, "x-stainless-terraform-configurability": "computed" }, "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "profile_id": { "type": "string", "format": "uuid", "deprecated": true, "nullable": true }, "variant": { "allOf": [ { "$ref": "#/components/schemas/dlp_PredefinedEntryVariant" } ] } }, "required": [ "id", "name", "enabled", "confidence" ] }, "dlp_PredefinedEntryUpdate": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "dlp_PredefinedEntryVariant": { "oneOf": [ { "description": "A Predefined AI prompt classification topic entry.", "properties": { "description": { "description": "A customer-facing explanation of what this predefined AI prompt topic represents.", "type": "string", "nullable": true }, "topic_type": { "$ref": "#/components/schemas/dlp_PromptTopicType" }, "type": { "type": "string", "enum": [ "PromptTopic" ] } }, "required": [ "topic_type", "type" ], "type": "object" }, { "description": "A general predefined entry.", "properties": { "description": { "description": "A customer-facing explanation of what this predefined entry represents.", "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "General" ] } }, "required": [ "type" ], "type": "object" } ] }, "dlp_PredefinedProfile": { "type": "object", "properties": { "ai_context_enabled": { "type": "boolean", "default": false }, "allowed_match_count": { "type": "integer", "format": "int32" }, "confidence_threshold": { "default": "low", "allOf": [ { "$ref": "#/components/schemas/dlp_Confidence" } ] }, "context_awareness": { "$ref": "#/components/schemas/dlp_ContextAwareness" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_Entry" }, "deprecated": true }, "id": { "description": "The id of the predefined profile (uuid).", "type": "string", "format": "uuid" }, "name": { "description": "The name of the predefined profile.", "type": "string" }, "ocr_enabled": { "type": "boolean", "default": false }, "open_access": { "description": "Whether this profile can be accessed by anyone.", "type": "boolean" } }, "required": [ "id", "name", "entries", "allowed_match_count" ] }, "dlp_PredefinedProfileConfig": { "type": "object", "properties": { "ai_context_enabled": { "type": "boolean", "default": false }, "allowed_match_count": { "type": "integer", "format": "int32" }, "confidence_threshold": { "type": "string", "default": "low", "nullable": true }, "enabled_entries": { "description": "Entries to enable for this predefined profile. Any entries not provided will be disabled.", "type": "array", "items": { "format": "uuid", "type": "string" } }, "entries": { "description": "This field has been deprecated for `enabled_entries`.", "type": "array", "items": { "$ref": "#/components/schemas/dlp_Entry" }, "deprecated": true }, "id": { "description": "The id of the predefined profile (uuid).", "type": "string", "format": "uuid" }, "name": { "description": "The name of the predefined profile.", "type": "string" }, "ocr_enabled": { "type": "boolean", "default": false }, "open_access": { "description": "Whether this profile can be accessed by anyone.", "type": "boolean" } }, "required": [ "id", "name", "entries", "enabled_entries", "allowed_match_count", "confidence_threshold" ] }, "dlp_PredefinedProfileConfigUpdate": { "type": "object", "properties": { "ai_context_enabled": { "type": "boolean", "default": false }, "allowed_match_count": { "type": "integer", "format": "int32", "example": 5, "default": 0, "maximum": 1000, "minimum": 0, "nullable": true }, "confidence_threshold": { "type": "string", "default": "low", "nullable": true }, "enabled_entries": { "type": "array", "items": { "format": "uuid", "type": "string" }, "nullable": true }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_PredefinedProfileEntryUpdate" }, "deprecated": true, "x-stainless-terraform-configurability": "computed_optional" }, "ocr_enabled": { "type": "boolean", "default": false } } }, "dlp_PredefinedProfileEntryUpdate": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "id", "enabled" ] }, "dlp_PredefinedProfileUpdate": { "type": "object", "properties": { "ai_context_enabled": { "type": "boolean", "default": false }, "allowed_match_count": { "type": "integer", "format": "int32", "example": 5, "default": 0, "maximum": 1000, "minimum": 0, "nullable": true }, "confidence_threshold": { "type": "string", "default": "low", "nullable": true }, "context_awareness": { "$ref": "#/components/schemas/dlp_ContextAwareness" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_PredefinedProfileEntryUpdate" }, "deprecated": true }, "ocr_enabled": { "type": "boolean", "default": false } } }, "dlp_Profile": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/dlp_CustomProfile" }, { "properties": { "type": { "type": "string", "enum": [ "custom" ] } }, "required": [ "type" ], "type": "object" } ], "title": "Custom Profile" }, { "allOf": [ { "$ref": "#/components/schemas/dlp_PredefinedProfile" }, { "properties": { "type": { "type": "string", "enum": [ "predefined" ] } }, "required": [ "type" ], "type": "object" } ], "title": "Predefined Profile" }, { "allOf": [ { "$ref": "#/components/schemas/dlp_IntegrationProfile" }, { "properties": { "type": { "type": "string", "enum": [ "integration" ] } }, "required": [ "type" ], "type": "object" } ], "title": "Integration Profile" } ] }, "dlp_ProfileArray": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_Profile" } }, "dlp_ProfileEntryUpdate": { "oneOf": [ { "$ref": "#/components/schemas/dlp_NewCustomEntryWithId" }, { "$ref": "#/components/schemas/dlp_NewCustomEntry" } ] }, "dlp_PromptTopicType": { "type": "string", "enum": [ "Intent", "Content" ] }, "dlp_RegexValidationQuery": { "type": "object", "properties": { "max_match_bytes": { "description": "Maximum number of bytes that the regular expression can match.\n\nIf this is `null` then there is no limit on the length. Patterns can use\n`*` and `+`. Otherwise repeats should use a range `{m,n}` to restrict\npatterns to the length. If this field is missing, then a default length\nlimit is used.\n\nNote that the length is specified in bytes. Since regular expressions\nuse UTF-8 the pattern `.` can match up to 4 bytes. Hence `.{1,256}`\nhas a maximum length of 1024 bytes.", "type": "integer", "format": "int32", "minimum": 0, "nullable": true }, "regex": { "type": "string" } }, "required": [ "regex" ] }, "dlp_RegexValidationResult": { "type": "object", "properties": { "valid": { "type": "boolean" } }, "required": [ "valid" ] }, "dlp_RiskEvent": { "type": "object", "properties": { "event_details": {}, "id": { "type": "string" }, "name": { "type": "string" }, "risk_level": { "$ref": "#/components/schemas/dlp_RiskLevel" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "id", "risk_level", "name", "timestamp" ] }, "dlp_RiskEvents": { "type": "object", "properties": { "email": { "type": "string" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_RiskEvent" } }, "last_reset_time": { "type": "string", "format": "date-time", "nullable": true }, "name": { "type": "string" }, "risk_level": { "allOf": [ { "$ref": "#/components/schemas/dlp_RiskLevel" } ] } }, "required": [ "name", "email", "events" ] }, "dlp_RiskLevel": { "type": "string", "enum": [ "low", "medium", "high" ] }, "dlp_RiskScoreIntegration": { "type": "object", "properties": { "account_tag": { "description": "The Cloudflare account tag.", "type": "string" }, "active": { "description": "Whether this integration is enabled and should export changes in risk score.", "type": "boolean" }, "created_at": { "description": "When the integration was created in RFC3339 format.", "type": "string", "format": "date-time" }, "id": { "description": "The id of the integration, a UUIDv4.", "type": "string", "format": "uuid" }, "integration_type": { "$ref": "#/components/schemas/dlp_RiskScoreIntegrationType" }, "reference_id": { "description": "A reference ID defined by the client.\nShould be set to the Access-Okta IDP integration ID.\nUseful when the risk-score integration needs to be associated with a secondary asset and recalled using that ID.", "type": "string" }, "tenant_url": { "description": "The base URL for the tenant. E.g. \"https://tenant.okta.com\".", "type": "string" }, "well_known_url": { "description": "The URL for the Shared Signals Framework configuration, e.g. \"/.well-known/sse-configuration/{integration_uuid}/\". https://openid.net/specs/openid-sse-framework-1_0.html#rfc.section.6.2.1.", "type": "string" } }, "required": [ "id", "account_tag", "integration_type", "reference_id", "tenant_url", "well_known_url", "active", "created_at" ] }, "dlp_RiskScoreIntegrationArray": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_RiskScoreIntegration" } }, "dlp_RiskScoreIntegrationType": { "type": "string", "enum": [ "Okta" ] }, "dlp_RiskSummary": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_UserRiskInfo" } } }, "required": [ "users" ] }, "dlp_SensitivityGroup": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "levels": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_SensitivityLevel" } }, "name": { "type": "string" }, "template_id": { "type": "string", "format": "uuid", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "created_at", "updated_at", "levels" ] }, "dlp_SensitivityGroupArray": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_SensitivityGroup" } }, "dlp_SensitivityGroupLevelUpdate": { "allOf": [ { "$ref": "#/components/schemas/dlp_SensitivityLevelUpdate" }, { "properties": { "id": { "description": "If `None` (omitted), a new level will be created. Otherwise, an existing level will\nbe updated.", "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } ] }, "dlp_SensitivityGroupTemplate": { "type": "object", "properties": { "description": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "levels": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_SensitivityLevelTemplate" } }, "name": { "type": "string" } }, "required": [ "id", "name", "description", "levels" ] }, "dlp_SensitivityGroupTemplateArray": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_SensitivityGroupTemplate" } }, "dlp_SensitivityGroupUpdate": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "levels": { "description": "The desired final state of levels.\n- `None` (omitted): no level changes.\n- `Some([])`: delete all levels.\n- `Some([...])`: desired final set + order.", "type": "array", "items": { "$ref": "#/components/schemas/dlp_SensitivityGroupLevelUpdate" }, "nullable": true, "x-stainless-skip": [ "terraform" ] }, "name": { "type": "string", "nullable": true } } }, "dlp_SensitivityLevel": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string", "nullable": true }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "created_at", "updated_at" ] }, "dlp_SensitivityLevelArray": { "type": "array", "items": { "$ref": "#/components/schemas/dlp_SensitivityLevel" } }, "dlp_SensitivityLevelOrder": { "description": "The ordered list of level IDs for a sensitivity group.\nUsed to get and set the ordering of levels independently of level attributes.", "type": "object", "properties": { "level_ids": { "type": "array", "items": { "format": "uuid", "type": "string" } } }, "required": [ "level_ids" ] }, "dlp_SensitivityLevelRef": { "description": "A reference pairing a sensitivity group with a specific level within that group.", "type": "object", "properties": { "group_id": { "type": "string", "format": "uuid" }, "level_id": { "type": "string", "format": "uuid" } }, "required": [ "group_id", "level_id" ] }, "dlp_SensitivityLevelTemplate": { "type": "object", "properties": { "description": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "description" ] }, "dlp_SensitivityLevelUpdate": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true } } }, "dlp_SharedEntryUpdate": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "entry_id": { "type": "string", "format": "uuid" } }, "required": [ "entry_id", "enabled" ] }, "dlp_SkipConfig": { "description": "Content types to exclude from context analysis and return all matches.", "type": "object", "properties": { "files": { "description": "If the content type is a file, skip context analysis and return all matches.", "type": "boolean" } }, "required": [ "files" ] }, "dlp_UpdateAddinAccountMapping": { "type": "object", "properties": { "auth_requirements": { "$ref": "#/components/schemas/dlp_AddinAuth" } }, "required": [ "auth_requirements" ] }, "dlp_UpdateBehavior": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "risk_level": { "$ref": "#/components/schemas/dlp_RiskLevel" } }, "required": [ "risk_level", "enabled" ] }, "dlp_UpdateBehaviors": { "type": "object", "properties": { "behaviors": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/dlp_UpdateBehavior" } } }, "required": [ "behaviors" ] }, "dlp_UpdateDocumentFingerprint": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "match_percent": { "type": "integer", "format": "int32", "nullable": true }, "name": { "type": "string", "nullable": true } } }, "dlp_UpdateEmailRulePriorities": { "description": "Used to update multiple email rule priorities as an atomic action,\nto support patterns such as swapping the priorities of two email rules.", "type": "object", "properties": { "new_priorities": { "type": "object", "additionalProperties": { "format": "int32", "minimum": 0, "type": "integer" } } }, "required": [ "new_priorities" ] }, "dlp_UpdateIntegrationBody": { "type": "object", "properties": { "active": { "description": "Whether this integration is enabled. If disabled, no risk changes will be exported to the third-party.", "type": "boolean" }, "reference_id": { "description": "A reference id that can be supplied by the client. Currently this should be set to the Access-Okta IDP ID (a UUIDv4).\nhttps://developers.cloudflare.com/api/operations/access-identity-providers-get-an-access-identity-provider", "type": "string", "nullable": true }, "tenant_url": { "description": "The base url of the tenant, e.g. \"https://tenant.okta.com\".", "type": "string", "format": "uri" } }, "required": [ "tenant_url", "active" ] }, "dlp_UserRiskInfo": { "type": "object", "properties": { "email": { "type": "string" }, "event_count": { "type": "integer", "minimum": 0 }, "last_event": { "type": "string", "format": "date-time" }, "max_risk_level": { "$ref": "#/components/schemas/dlp_RiskLevel" }, "name": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" } }, "required": [ "user_id", "name", "email", "max_risk_level", "event_count", "last_event" ] }, "dlp_Validation": { "type": "string", "deprecated": true, "enum": [ "luhn" ] }, "dlp_WordListEntry": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "profile_id": { "type": "string", "format": "uuid", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" }, "word_list": {} }, "required": [ "id", "name", "created_at", "updated_at", "word_list", "enabled" ] }, "dlp_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dlp_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "dlp_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/dlp_messages" }, "messages": { "$ref": "#/components/schemas/dlp_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "dlp_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/dlp_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/dlp_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "dlp_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dlp_api-response-common" } ] }, "dlp_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "dls_CreatePrefixBindingInput": { "type": "object", "properties": { "cidr": { "description": "IP prefix in CIDR notation to bind.", "type": "string", "example": "10.0.1.0/24" }, "prefix_id": { "description": "The ID of the parent IP prefix that contains the CIDR.", "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "maxLength": 64 }, "region_key": { "description": "Region key from managed regions (e.g., \"us\", \"eu\").", "type": "string", "example": "eu", "maxLength": 128, "minLength": 1, "pattern": "^[a-z0-9_-]+$" } }, "required": [ "prefix_id", "cidr", "region_key" ] }, "dls_FetchPublicRegionResponse": { "allOf": [ { "$ref": "#/components/schemas/dls_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/dls_RegionPublic" } }, "required": [ "result" ] } ] }, "dls_PrefixBinding": { "type": "object", "properties": { "cidr": { "description": "The CIDR that is bound.", "type": "string" }, "id": { "description": "The ID of the binding.", "type": "string" }, "prefix_id": { "description": "The ID of the parent prefix.", "type": "string" }, "region_key": { "description": "The region key used for the binding.", "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[a-z0-9_-]+$" } }, "required": [ "id", "prefix_id", "cidr", "region_key" ] }, "dls_PrefixBindingPaginatedListResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/dls_coded_message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/dls_coded_message" } }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/dls_PrefixBinding" } }, "result_info": { "type": "object", "properties": { "count": { "description": "Number of items in the current page.", "type": "integer" }, "cursor": { "description": "Opaque cursor for the next page. Empty string when there are no more results.", "type": "string" }, "per_page": { "description": "Maximum number of items per page.", "type": "integer" } }, "required": [ "count", "cursor", "per_page" ] }, "success": { "type": "boolean" } }, "required": [ "success", "errors", "messages", "result", "result_info" ] }, "dls_PrefixBindingResponse": { "allOf": [ { "$ref": "#/components/schemas/dls_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/dls_PrefixBinding" } }, "required": [ "result" ] } ] }, "dls_RegionPublic": { "type": "object", "properties": { "created_on": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "modified_on": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "region_key": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[a-z0-9_-]+$" }, "version": { "type": "integer" }, "version_created_on": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "region_key", "created_on", "modified_on", "version", "version_created_on" ] }, "dls_RegionPublicPaginatedListResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/dls_coded_message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/dls_coded_message" } }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/dls_RegionPublic" } }, "result_info": { "type": "object", "properties": { "count": { "description": "Number of items in the current page.", "type": "integer" }, "cursor": { "description": "Opaque cursor for the next page. Empty string when there are no more results.", "type": "string" }, "per_page": { "description": "Maximum number of items per page.", "type": "integer" } }, "required": [ "count", "cursor", "per_page" ] }, "success": { "type": "boolean" } }, "required": [ "success", "errors", "messages", "result", "result_info" ] }, "dls_UpdatePrefixBindingInput": { "type": "object", "properties": { "region_key": { "description": "New region key to assign (e.g., \"us\", \"eu\", \"cfcanary\").", "type": "string", "example": "eu", "maxLength": 128, "minLength": 1, "pattern": "^[a-z0-9_-]+$" } }, "required": [ "region_key" ] }, "dls_account_identifier": { "description": "Identifier of a Cloudflare account.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "minLength": 32, "pattern": "^[0-9a-f]{32}$", "x-auditable": true }, "dls_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dls_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "dls_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/dls_messages" }, "messages": { "$ref": "#/components/schemas/dls_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "dls_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/dls_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/dls_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "dls_bad_response": { "allOf": [ { "$ref": "#/components/schemas/dls_response" }, { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/dls_coded_message" }, "minLength": 1 }, "result": { "$ref": "#/components/schemas/dls_none" } }, "required": [ "errors" ] } ] }, "dls_coded_message": { "type": "object", "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "dls_good_response": { "allOf": [ { "$ref": "#/components/schemas/dls_response" }, { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/dls_coded_message" }, "maxLength": 0 } } } ] }, "dls_hostname": { "description": "DNS hostname to be regionalized, must be a subdomain of the zone. Wildcards are supported for one level, e.g `*.example.com`", "type": "string", "example": "foo.example.com", "x-auditable": true }, "dls_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "dls_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "dls_none": { "type": "object", "nullable": true }, "dls_region_key": { "description": "Identifying key for the region", "type": "string", "example": "ca", "x-auditable": true }, "dls_regional_hostname_response": { "type": "object", "properties": { "created_on": { "allOf": [ { "$ref": "#/components/schemas/dls_timestamp" }, { "description": "When the regional hostname was created" }, { "example": "2014-01-01T05:20:00.12345Z" } ] }, "hostname": { "$ref": "#/components/schemas/dls_hostname" }, "region_key": { "$ref": "#/components/schemas/dls_region_key" }, "routing": { "$ref": "#/components/schemas/dls_routing" } }, "required": [ "hostname", "region_key", "routing", "created_on" ] }, "dls_response": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/dls_coded_message" } }, "success": { "type": "boolean" } }, "required": [ "success", "messages" ] }, "dls_routing": { "description": "Configure which routing method to use for the regional hostname", "type": "string", "example": "dns", "default": "dns", "x-auditable": true }, "dls_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "x-auditable": true }, "dns-analytics_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/dns-analytics_messages" }, "messages": { "$ref": "#/components/schemas/dns-analytics_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "dns-analytics_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/dns-analytics_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/dns-analytics_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "dns-analytics_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-analytics_api-response-common" } ] }, "dns-analytics_data": { "description": "Array with one row per combination of dimension values.", "type": "array", "items": { "properties": { "dimensions": { "description": "Array of dimension values, representing the combination of dimension values corresponding to this row.", "type": "array", "items": { "description": "Dimension value.", "example": "NODATA", "type": "string" } } }, "required": [ "dimensions" ], "type": "object" } }, "dns-analytics_dimensions": { "description": "A comma-separated list of dimensions to group results by.", "type": "string", "example": "queryType" }, "dns-analytics_filters": { "description": "Segmentation filter in 'attribute operator value' format.", "type": "string", "example": "responseCode==NOERROR,queryType==A" }, "dns-analytics_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "dns-analytics_limit": { "description": "Limit number of returned metrics.", "type": "integer", "example": 100, "default": 100000 }, "dns-analytics_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "dns-analytics_metrics": { "description": "A comma-separated list of metrics to query.", "type": "string", "example": "queryCount,uncachedCount" }, "dns-analytics_query": { "type": "object", "properties": { "dimensions": { "description": "Array of dimension names.", "type": "array", "items": { "description": "Dimension name.", "example": "responseCode", "type": "string" }, "example": [ "responseCode", "queryName" ] }, "filters": { "$ref": "#/components/schemas/dns-analytics_filters" }, "limit": { "$ref": "#/components/schemas/dns-analytics_limit" }, "metrics": { "description": "Array of metric names.", "type": "array", "items": { "description": "Metric name.", "example": "queries", "type": "string" }, "example": [ "queryCount", "responseTimeAvg" ] }, "since": { "$ref": "#/components/schemas/dns-analytics_since" }, "sort": { "description": "Array of dimensions to sort by, where each dimension may be prefixed by - (descending) or + (ascending).", "type": "array", "items": { "description": "Dimension name (may be prefixed by - (descending) or + (ascending).", "example": "+responseCode", "type": "string" }, "example": [ "+responseCode", "-queryName" ] }, "until": { "$ref": "#/components/schemas/dns-analytics_until" } }, "required": [ "dimensions", "metrics", "since", "until", "limit" ] }, "dns-analytics_report": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-analytics_result" }, { "properties": { "data": { "type": "array", "items": { "properties": { "metrics": { "description": "Array with one item per requested metric. Each item is a single value.", "type": "array", "items": { "description": "Nominal metric value.", "type": "number" } } }, "required": [ "metrics" ], "type": "object" } } }, "required": [ "data" ], "type": "object" } ] }, "dns-analytics_report_bytime": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-analytics_result" }, { "properties": { "data": { "type": "array", "items": { "properties": { "metrics": { "description": "Array with one item per requested metric. Each item is an array of values, broken down by time interval.", "type": "array", "items": { "description": "Nominal metric values, broken down by time interval.", "items": { "description": "Nominal metric value.", "type": "number" }, "type": "array" } } }, "required": [ "metrics" ], "type": "object" } }, "query": { "properties": { "time_delta": { "$ref": "#/components/schemas/dns-analytics_time_delta" } }, "required": [ "time_delta" ], "type": "object" }, "time_intervals": { "description": "Array of time intervals in the response data. Each interval is represented as an array containing two values: the start time, and the end time.\n", "type": "array", "items": { "description": "Array with exactly two items, representing the start and end time (respectively) of this time interval.", "items": { "description": "Time value.", "example": "2023-11-11T12:00:00Z", "format": "date-time", "type": "string" }, "type": "array" } } }, "required": [ "time_intervals", "query", "data" ], "type": "object" } ] }, "dns-analytics_result": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/dns-analytics_data" }, "data_lag": { "description": "Number of seconds between current time and last processed event, in another words how many seconds of data could be missing.", "type": "number", "example": 60, "minimum": 0 }, "max": { "description": "Maximum results for each metric (object mapping metric names to values). Currently always an empty object.", "type": "object" }, "min": { "description": "Minimum results for each metric (object mapping metric names to values). Currently always an empty object.", "type": "object" }, "query": { "$ref": "#/components/schemas/dns-analytics_query" }, "rows": { "description": "Total number of rows in the result.", "type": "number", "example": 100, "minimum": 0 }, "totals": { "description": "Total results for metrics across all data (object mapping metric names to values).", "type": "object" } }, "required": [ "rows", "totals", "min", "max", "data_lag", "query", "data" ] }, "dns-analytics_since": { "description": "Start date and time of requesting data period in ISO 8601 format.", "type": "string", "format": "date-time", "example": "2023-11-11T12:00:00Z" }, "dns-analytics_sort": { "description": "A comma-separated list of dimensions to sort by, where each dimension may be prefixed by - (descending) or + (ascending).", "type": "string", "example": "+responseCode,-queryName" }, "dns-analytics_time_delta": { "description": "Unit of time to group data by.", "type": "string", "example": "hour", "enum": [ "all", "auto", "year", "quarter", "month", "week", "day", "hour", "dekaminute", "minute" ] }, "dns-analytics_until": { "description": "End date and time of requesting data period in ISO 8601 format.", "type": "string", "format": "date-time", "example": "2023-11-11T13:00:00Z" }, "dns-custom-nameservers_CustomNS": { "description": "A single account custom nameserver.", "type": "object", "properties": { "dns_records": { "description": "A and AAAA records associated with the nameserver.", "type": "array", "items": { "properties": { "type": { "description": "DNS record type.", "type": "string", "example": "A", "enum": [ "A", "AAAA" ], "x-auditable": true }, "value": { "description": "DNS record contents (an IPv4 or IPv6 address).", "type": "string", "example": "1.1.1.1", "x-auditable": true } }, "type": "object" }, "x-stainless-collection-type": "set" }, "ns_name": { "$ref": "#/components/schemas/dns-custom-nameservers_ns_name" }, "ns_set": { "$ref": "#/components/schemas/dns-custom-nameservers_ns_set" }, "status": { "description": "Verification status of the nameserver.", "type": "string", "example": "verified", "enum": [ "moved", "pending", "verified" ], "deprecated": true, "x-auditable": true }, "zone_tag": { "$ref": "#/components/schemas/dns-custom-nameservers_identifier-2" } }, "required": [ "dns_records", "ns_name", "status", "zone_tag" ], "title": "Custom NS" }, "dns-custom-nameservers_CustomNS-2": { "description": "A single tenant custom nameserver.", "type": "object", "properties": { "dns_records": { "description": "A and AAAA records associated with the nameserver.", "type": "array", "items": { "properties": { "type": { "description": "DNS record type.", "type": "string", "example": "A", "enum": [ "A", "AAAA" ], "x-auditable": true }, "value": { "description": "DNS record contents (an IPv4 or IPv6 address).", "type": "string", "example": "1.1.1.1", "x-auditable": true } }, "type": "object" }, "x-stainless-collection-type": "set" }, "ns_name": { "$ref": "#/components/schemas/dns-custom-nameservers_ns_name" }, "ns_set": { "$ref": "#/components/schemas/dns-custom-nameservers_ns_set" }, "status": { "description": "Verification status of the nameserver.", "type": "string", "example": "verified", "enum": [ "moved", "pending", "verified" ], "deprecated": true, "x-auditable": true }, "zone_tag": { "$ref": "#/components/schemas/dns-custom-nameservers_identifier-2" } }, "required": [ "dns_records", "ns_name", "status", "zone_tag" ], "title": "Custom NS" }, "dns-custom-nameservers_CustomNSInput": { "type": "object", "properties": { "ns_name": { "$ref": "#/components/schemas/dns-custom-nameservers_ns_name" }, "ns_set": { "$ref": "#/components/schemas/dns-custom-nameservers_ns_set" } }, "required": [ "ns_name" ], "title": "Custom NS Input" }, "dns-custom-nameservers_acns_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/dns-custom-nameservers_CustomNS" } } }, "type": "object" } ] }, "dns-custom-nameservers_acns_response_single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dns-custom-nameservers_CustomNS" } }, "type": "object" } ] }, "dns-custom-nameservers_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "dns-custom-nameservers_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/dns-custom-nameservers_messages" }, "messages": { "$ref": "#/components/schemas/dns-custom-nameservers_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "dns-custom-nameservers_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "dns-custom-nameservers_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_api-response-common" } ] }, "dns-custom-nameservers_empty_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "description": "Unused", "type": "string", "x-auditable": true }, "maxItems": 0 } }, "type": "object" } ] }, "dns-custom-nameservers_empty_response-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "description": "Unused", "type": "string", "x-auditable": true }, "maxItems": 0 } }, "type": "object" } ] }, "dns-custom-nameservers_empty_response-3": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "description": "Unused.", "type": "string", "x-auditable": true }, "maxItems": 0 } }, "type": "object" } ] }, "dns-custom-nameservers_get_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_api-response-collection" }, { "$ref": "#/components/schemas/dns-custom-nameservers_zone_metadata" } ] }, "dns-custom-nameservers_identifier": { "description": "Account identifier tag.", "type": "string", "example": "372e67954025e0ba6aaa6d586b9e0b59", "maxLength": 32, "readOnly": true, "x-auditable": true }, "dns-custom-nameservers_identifier-2": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "dns-custom-nameservers_identifier-3": { "description": "Tenant identifier tag.", "type": "string", "example": "699d98642c564d2e855e9661899b7252", "maxLength": 32, "x-auditable": true }, "dns-custom-nameservers_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "dns-custom-nameservers_ns_name": { "description": "The FQDN of the name server.", "type": "string", "format": "hostname", "example": "ns1.example.com", "x-auditable": true }, "dns-custom-nameservers_ns_set": { "description": "The number of the set that this name server belongs to.", "type": "number", "example": 1, "default": 1, "maximum": 5, "minimum": 1, "x-auditable": true }, "dns-custom-nameservers_tcns_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/dns-custom-nameservers_CustomNS-2" } } }, "type": "object" } ] }, "dns-custom-nameservers_tcns_response_single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-custom-nameservers_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dns-custom-nameservers_CustomNS-2" } }, "type": "object" } ] }, "dns-custom-nameservers_zone_metadata": { "type": "object", "properties": { "enabled": { "description": "Whether zone uses account-level custom nameservers.", "type": "boolean", "example": true, "x-auditable": true }, "ns_set": { "description": "The number of the name server set to assign to the zone.", "type": "number", "example": 1, "default": 1, "maximum": 5, "minimum": 1, "x-auditable": true } } }, "dns-firewall_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-firewall_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "dns-firewall_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/dns-firewall_messages" }, "messages": { "$ref": "#/components/schemas/dns-firewall_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "dns-firewall_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/dns-firewall_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/dns-firewall_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "dns-firewall_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-firewall_api-response-common" } ] }, "dns-firewall_attack_mitigation": { "description": "Attack mitigation settings", "type": "object", "properties": { "enabled": { "description": "When enabled, automatically mitigate random-prefix attacks to protect upstream DNS servers", "type": "boolean", "example": true, "x-auditable": true }, "only_when_upstream_unhealthy": { "description": "Only mitigate attacks when upstream servers seem unhealthy", "type": "boolean", "example": false, "default": true, "x-auditable": true } }, "nullable": true }, "dns-firewall_deprecate_any_requests": { "description": "Whether to refuse to answer queries for the ANY type", "type": "boolean", "example": true, "x-auditable": true }, "dns-firewall_dns-firewall-cluster": { "type": "object", "properties": { "attack_mitigation": { "$ref": "#/components/schemas/dns-firewall_attack_mitigation" }, "deprecate_any_requests": { "$ref": "#/components/schemas/dns-firewall_deprecate_any_requests" }, "ecs_fallback": { "$ref": "#/components/schemas/dns-firewall_ecs_fallback" }, "maximum_cache_ttl": { "$ref": "#/components/schemas/dns-firewall_maximum_cache_ttl" }, "minimum_cache_ttl": { "$ref": "#/components/schemas/dns-firewall_minimum_cache_ttl" }, "name": { "$ref": "#/components/schemas/dns-firewall_name" }, "negative_cache_ttl": { "$ref": "#/components/schemas/dns-firewall_negative_cache_ttl" }, "ratelimit": { "$ref": "#/components/schemas/dns-firewall_ratelimit" }, "retries": { "$ref": "#/components/schemas/dns-firewall_retries" }, "upstream_ips": { "$ref": "#/components/schemas/dns-firewall_upstream_ips" } } }, "dns-firewall_dns-firewall-cluster-patch": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-firewall_dns-firewall-cluster" } ] }, "dns-firewall_dns-firewall-cluster-post": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-firewall_dns-firewall-cluster" }, { "properties": { "dns_firewall_ip_count": { "$ref": "#/components/schemas/dns-firewall_dns_firewall_ip_count" } }, "type": "object" } ], "required": [ "name", "upstream_ips" ] }, "dns-firewall_dns-firewall-cluster-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-firewall_dns-firewall-cluster" }, { "properties": { "dns_firewall_ips": { "$ref": "#/components/schemas/dns-firewall_dns_firewall_ips" }, "id": { "$ref": "#/components/schemas/dns-firewall_identifier" }, "modified_on": { "$ref": "#/components/schemas/dns-firewall_modified_on" } }, "required": [ "id", "dns_firewall_ips", "modified_on" ], "type": "object" } ], "required": [ "name", "upstream_ips", "minimum_cache_ttl", "maximum_cache_ttl", "negative_cache_ttl", "deprecate_any_requests", "ecs_fallback", "ratelimit", "retries" ] }, "dns-firewall_dns-firewall-reverse-dns": { "type": "object", "properties": { "ptr": { "description": "Map of cluster IP addresses to PTR record contents", "type": "object", "additionalProperties": { "description": "PTR record content", "type": "string" } } } }, "dns-firewall_dns-firewall-reverse-dns-patch": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-firewall_dns-firewall-reverse-dns" } ] }, "dns-firewall_dns-firewall-reverse-dns-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-firewall_dns-firewall-reverse-dns" } ], "required": [ "ptr" ] }, "dns-firewall_dns_firewall_ip_count": { "description": "Number of IPv4 addresses to assign to the DNS Firewall cluster. Only used during cluster creation and cannot be changed later.", "type": "integer", "example": 2, "default": 2, "maximum": 10, "minimum": 1 }, "dns-firewall_dns_firewall_ips": { "type": "array", "items": { "anyOf": [ { "description": "Cloudflare-assigned DNS IPv4 address", "example": "203.0.113.1", "format": "ipv4", "type": "string", "x-auditable": true }, { "description": "Cloudflare-assigned DNS IPv6 address", "example": "2001:DB8:ab::CF", "format": "ipv6", "type": "string", "x-auditable": true } ], "type": "string" }, "example": [ "203.0.113.1", "203.0.113.254", "2001:DB8:AB::CF", "2001:DB8:CD::CF" ], "x-stainless-collection-type": "set" }, "dns-firewall_dns_firewall_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-firewall_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/dns-firewall_dns-firewall-cluster-response" } } }, "type": "object" } ] }, "dns-firewall_dns_firewall_reverse_dns_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-firewall_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dns-firewall_dns-firewall-reverse-dns-response" } }, "type": "object" } ] }, "dns-firewall_dns_firewall_single_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-firewall_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dns-firewall_dns-firewall-cluster-response" } }, "type": "object" } ] }, "dns-firewall_ecs_fallback": { "description": "Whether to forward client IP (resolver) subnet if no EDNS Client Subnet is sent", "type": "boolean", "example": false, "x-auditable": true }, "dns-firewall_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "dns-firewall_maximum_cache_ttl": { "description": "By default, Cloudflare attempts to cache responses for as long as\nindicated by the TTL received from upstream nameservers. This setting\nsets an upper bound on this duration. For caching purposes, higher TTLs\nwill be decreased to the maximum value defined by this setting.\n\nThis setting does not affect the TTL value in the DNS response\nCloudflare returns to clients. Cloudflare will always forward the TTL\nvalue received from upstream nameservers.\n", "type": "number", "example": 900, "default": 900, "maximum": 36000, "minimum": 30, "x-auditable": true }, "dns-firewall_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "dns-firewall_minimum_cache_ttl": { "description": "By default, Cloudflare attempts to cache responses for as long as\nindicated by the TTL received from upstream nameservers. This setting\nsets a lower bound on this duration. For caching purposes, lower TTLs\nwill be increased to the minimum value defined by this setting.\n\nThis setting does not affect the TTL value in the DNS response\nCloudflare returns to clients. Cloudflare will always forward the TTL\nvalue received from upstream nameservers.\n\nNote that, even with this setting, there is no guarantee that a\nresponse will be cached for at least the specified duration. Cached\nresponses may be removed earlier for capacity or other operational\nreasons.\n", "type": "number", "example": 60, "default": 60, "maximum": 36000, "minimum": 30, "x-auditable": true }, "dns-firewall_modified_on": { "description": "Last modification of DNS Firewall cluster", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "x-auditable": true }, "dns-firewall_name": { "description": "DNS Firewall cluster name", "type": "string", "example": "My Awesome DNS Firewall cluster", "maxLength": 160, "minLength": 1, "x-auditable": true }, "dns-firewall_negative_cache_ttl": { "description": "This setting controls how long DNS Firewall should cache negative\nresponses (e.g., NXDOMAIN) from the upstream servers.\n\nThis setting does not affect the TTL value in the DNS response\nCloudflare returns to clients. Cloudflare will always forward the TTL\nvalue received from upstream nameservers.\n", "type": "number", "example": 900, "maximum": 36000, "minimum": 30, "nullable": true, "x-auditable": true }, "dns-firewall_ratelimit": { "description": "Maximum number of DNS queries per second that will be forwarded to your upstream nameservers. The limit is enforced per server, where each server receives a fraction of the configured value. The actual aggregate rate for a data center may vary depending on how many servers are present. Responses served from cache do not count toward this limit. Set to null to disable rate limiting.", "type": "number", "example": 600, "maximum": 1000000000, "minimum": 100, "nullable": true, "x-auditable": true }, "dns-firewall_retries": { "description": "Number of retries for fetching DNS responses from upstream nameservers (not counting the initial attempt)", "type": "number", "example": 2, "default": 2, "maximum": 2, "minimum": 0, "x-auditable": true }, "dns-firewall_upstream_ips": { "type": "array", "items": { "anyOf": [ { "description": "Upstream DNS Server IPv4 address", "example": "192.0.2.1", "format": "ipv4", "type": "string", "x-auditable": true }, { "description": "Upstream DNS Server IPv6 address", "example": "2001:DB8:100::CF", "format": "ipv6", "type": "string", "x-auditable": true } ], "type": "string" }, "example": [ "192.0.2.1", "198.51.100.1", "2001:DB8:100::CF" ], "minLength": 1, "x-stainless-collection-type": "set" }, "dns-records_AAAARecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "A valid IPv6 address.", "example": "2400:cb00:2049::1", "format": "ipv6", "type": "string", "x-auditable": true }, "private_routing": { "description": "Enables private network routing to the origin.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "type": { "description": "Record type.", "type": "string", "example": "AAAA", "enum": [ "AAAA" ], "x-auditable": true } }, "type": "object" } ], "title": "AAAA Record" }, "dns-records_ARecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "A valid IPv4 address.", "example": "198.51.100.4", "format": "ipv4", "type": "string", "x-auditable": true }, "private_routing": { "description": "Enables private network routing to the origin.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "type": { "description": "Record type.", "type": "string", "example": "A", "enum": [ "A" ], "x-auditable": true } }, "type": "object" } ], "title": "A Record" }, "dns-records_CAARecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "Formatted CAA content. See 'data' to set CAA properties.", "readOnly": true, "type": "string", "x-auditable": true }, "data": { "description": "Components of a CAA record.", "type": "object", "properties": { "flags": { "description": "Flags for the CAA record.", "type": "number", "example": 1, "maximum": 255, "minimum": 0, "x-auditable": true }, "tag": { "description": "Name of the property controlled by this record (e.g.: issue, issuewild, iodef).", "type": "string", "example": "issue", "x-auditable": true }, "value": { "description": "Value of the record. This field's semantics depend on the chosen tag.", "type": "string", "x-auditable": true } } }, "type": { "description": "Record type.", "type": "string", "example": "CAA", "enum": [ "CAA" ], "x-auditable": true } }, "type": "object" } ], "title": "CAA Record" }, "dns-records_CERTRecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "Formatted CERT content. See 'data' to set CERT properties.", "readOnly": true, "type": "string", "x-auditable": true }, "data": { "description": "Components of a CERT record.", "type": "object", "properties": { "algorithm": { "description": "Algorithm.", "type": "number", "example": 8, "maximum": 255, "minimum": 0, "x-auditable": true }, "certificate": { "description": "Certificate.", "type": "string", "x-auditable": true }, "key_tag": { "description": "Key Tag.", "type": "number", "example": 1, "maximum": 65535, "minimum": 0, "x-auditable": true }, "type": { "description": "Type.", "type": "number", "example": 9, "maximum": 65535, "minimum": 0, "x-auditable": true } } }, "type": { "description": "Record type.", "type": "string", "example": "CERT", "enum": [ "CERT" ], "x-auditable": true } }, "type": "object" } ], "title": "CERT Record" }, "dns-records_CNAMERecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "A valid hostname. Must not match the record's name.", "type": "string", "x-auditable": true }, "settings": { "type": "object", "properties": { "flatten_cname": { "description": "If enabled, causes the CNAME record to be resolved externally and the resulting address records (e.g., A and AAAA) to be returned instead of the CNAME record itself. This setting is unavailable for proxied records, since they are always flattened.", "type": "boolean", "example": true, "default": false, "x-auditable": true } } }, "type": { "description": "Record type.", "type": "string", "example": "CNAME", "enum": [ "CNAME" ], "x-auditable": true } }, "type": "object" } ], "title": "CNAME Record" }, "dns-records_DNSKEYRecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "Formatted DNSKEY content. See 'data' to set DNSKEY properties.", "readOnly": true, "type": "string", "x-auditable": true }, "data": { "description": "Components of a DNSKEY record.", "type": "object", "properties": { "algorithm": { "description": "Algorithm.", "type": "number", "example": 5, "maximum": 255, "minimum": 0, "x-auditable": true }, "flags": { "description": "Flags.", "type": "number", "example": 1, "maximum": 65535, "minimum": 0, "x-auditable": true }, "protocol": { "description": "Protocol.", "type": "number", "example": 3, "maximum": 255, "minimum": 0, "x-auditable": true }, "public_key": { "description": "Public Key.", "type": "string", "x-auditable": true } } }, "type": { "description": "Record type.", "type": "string", "example": "DNSKEY", "enum": [ "DNSKEY" ], "x-auditable": true } }, "type": "object" } ], "title": "DNSKEY Record" }, "dns-records_DSRecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "Formatted DS content. See 'data' to set DS properties.", "readOnly": true, "type": "string", "x-auditable": true }, "data": { "description": "Components of a DS record.", "type": "object", "properties": { "algorithm": { "description": "Algorithm.", "type": "number", "example": 3, "maximum": 255, "minimum": 0, "x-auditable": true }, "digest": { "description": "Digest.", "type": "string", "x-auditable": true }, "digest_type": { "description": "Digest Type.", "type": "number", "example": 1, "maximum": 255, "minimum": 0, "x-auditable": true }, "key_tag": { "description": "Key Tag.", "type": "number", "example": 1, "maximum": 65535, "minimum": 0, "x-auditable": true } } }, "type": { "description": "Record type.", "type": "string", "example": "DS", "enum": [ "DS" ], "x-auditable": true } }, "type": "object" } ], "title": "DS Record" }, "dns-records_HTTPSRecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "Formatted HTTPS content. See 'data' to set HTTPS properties.", "readOnly": true, "type": "string", "x-auditable": true }, "data": { "description": "Components of a HTTPS record.", "type": "object", "properties": { "priority": { "description": "Priority.", "type": "number", "example": 1, "maximum": 65535, "minimum": 0, "x-auditable": true }, "target": { "description": "Target.", "type": "string", "example": ".", "x-auditable": true }, "value": { "description": "Value.", "type": "string", "example": "alpn=\"h3,h2\" ipv4hint=\"127.0.0.1\" ipv6hint=\"::1\"", "x-auditable": true } } }, "type": { "description": "Record type.", "type": "string", "example": "HTTPS", "enum": [ "HTTPS" ], "x-auditable": true } }, "type": "object" } ], "title": "HTTPS Record" }, "dns-records_LOCRecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "Formatted LOC content. See 'data' to set LOC properties.", "example": "IN LOC 37 46 46 N 122 23 35 W 0m 100m 0m 0m", "readOnly": true, "type": "string", "x-auditable": true }, "data": { "description": "Components of a LOC record.", "type": "object", "properties": { "altitude": { "description": "Altitude of location in meters.", "type": "number", "example": 0, "maximum": 42849672.95, "minimum": -100000, "x-auditable": true }, "lat_degrees": { "description": "Degrees of latitude.", "type": "number", "example": 37, "maximum": 90, "minimum": 0, "x-auditable": true }, "lat_direction": { "description": "Latitude direction.", "type": "string", "example": "N", "enum": [ "N", "S" ], "x-auditable": true }, "lat_minutes": { "description": "Minutes of latitude.", "type": "number", "example": 46, "maximum": 59, "minimum": 0, "x-auditable": true }, "lat_seconds": { "description": "Seconds of latitude.", "type": "number", "example": 46, "maximum": 59.999, "minimum": 0, "x-auditable": true }, "long_degrees": { "description": "Degrees of longitude.", "type": "number", "example": 122, "maximum": 180, "minimum": 0, "x-auditable": true }, "long_direction": { "description": "Longitude direction.", "type": "string", "example": "W", "enum": [ "E", "W" ], "x-auditable": true }, "long_minutes": { "description": "Minutes of longitude.", "type": "number", "example": 23, "maximum": 59, "minimum": 0, "x-auditable": true }, "long_seconds": { "description": "Seconds of longitude.", "type": "number", "example": 35, "maximum": 59.999, "minimum": 0, "x-auditable": true }, "precision_horz": { "description": "Horizontal precision of location.", "type": "number", "example": 0, "maximum": 90000000, "minimum": 0, "x-auditable": true }, "precision_vert": { "description": "Vertical precision of location.", "type": "number", "example": 0, "maximum": 90000000, "minimum": 0, "x-auditable": true }, "size": { "description": "Size of location in meters.", "type": "number", "example": 100, "maximum": 90000000, "minimum": 0, "x-auditable": true } } }, "type": { "description": "Record type.", "type": "string", "example": "LOC", "enum": [ "LOC" ], "x-auditable": true } }, "type": "object" } ], "title": "LOC Record" }, "dns-records_MXRecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "A valid mail server hostname.", "example": "mx.example.com", "format": "hostname", "type": "string", "x-auditable": true }, "priority": { "$ref": "#/components/schemas/dns-records_priority" }, "type": { "description": "Record type.", "type": "string", "example": "MX", "enum": [ "MX" ], "x-auditable": true } }, "type": "object" } ], "title": "MX Record" }, "dns-records_NAPTRRecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "Formatted NAPTR content. See 'data' to set NAPTR properties.", "readOnly": true, "type": "string", "x-auditable": true }, "data": { "description": "Components of a NAPTR record.", "type": "object", "properties": { "flags": { "description": "Flags.", "type": "string", "x-auditable": true }, "order": { "description": "Order.", "type": "number", "example": 100, "maximum": 65535, "minimum": 0, "x-auditable": true }, "preference": { "description": "Preference.", "type": "number", "example": 10, "maximum": 65535, "minimum": 0, "x-auditable": true }, "regex": { "description": "Regex.", "type": "string", "x-auditable": true }, "replacement": { "description": "Replacement.", "type": "string", "x-auditable": true }, "service": { "description": "Service.", "type": "string", "x-auditable": true } } }, "type": { "description": "Record type.", "type": "string", "example": "NAPTR", "enum": [ "NAPTR" ], "x-auditable": true } }, "type": "object" } ], "title": "NAPTR Record" }, "dns-records_NSRecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "A valid name server host name.", "example": "ns1.example.com", "type": "string", "x-auditable": true }, "type": { "description": "Record type.", "type": "string", "example": "NS", "enum": [ "NS" ], "x-auditable": true } }, "type": "object" } ], "title": "NS Record" }, "dns-records_OPENPGPKEYRecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "A single Base64-encoded OpenPGP Transferable Public Key (RFC 4880 Section 11.1)", "type": "string", "x-auditable": true }, "type": { "description": "Record type.", "type": "string", "example": "OPENPGPKEY", "enum": [ "OPENPGPKEY" ], "x-auditable": true } }, "type": "object" } ], "title": "OPENPGPKEY Record" }, "dns-records_PTRRecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "Domain name pointing to the address.", "example": "example.com", "type": "string", "x-auditable": true }, "type": { "description": "Record type.", "type": "string", "example": "PTR", "enum": [ "PTR" ], "x-auditable": true } }, "type": "object" } ], "title": "PTR Record" }, "dns-records_SMIMEARecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "Formatted SMIMEA content. See 'data' to set SMIMEA properties.", "readOnly": true, "type": "string", "x-auditable": true }, "data": { "description": "Components of a SMIMEA record.", "type": "object", "properties": { "certificate": { "description": "Certificate.", "type": "string", "x-auditable": true }, "matching_type": { "description": "Matching Type.", "type": "number", "example": 0, "maximum": 255, "minimum": 0, "x-auditable": true }, "selector": { "description": "Selector.", "type": "number", "example": 0, "maximum": 255, "minimum": 0, "x-auditable": true }, "usage": { "description": "Usage.", "type": "number", "example": 3, "maximum": 255, "minimum": 0, "x-auditable": true } } }, "type": { "description": "Record type.", "type": "string", "example": "SMIMEA", "enum": [ "SMIMEA" ], "x-auditable": true } }, "type": "object" } ], "title": "SMIMEA Record" }, "dns-records_SRVRecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "Priority, weight, port, and SRV target. See 'data' for setting the individual component values.", "example": "10 IN SRV 5 8806 example.com.", "readOnly": true, "type": "string", "x-auditable": true }, "data": { "description": "Components of a SRV record.", "type": "object", "properties": { "port": { "description": "The port of the service.", "type": "number", "example": 8806, "maximum": 65535, "minimum": 0, "x-auditable": true }, "priority": { "$ref": "#/components/schemas/dns-records_priority" }, "target": { "description": "A valid hostname.", "type": "string", "format": "hostname", "example": "example.com", "x-auditable": true }, "weight": { "description": "The record weight.", "type": "number", "example": 5, "maximum": 65535, "minimum": 0, "x-auditable": true } } }, "type": { "description": "Record type.", "type": "string", "example": "SRV", "enum": [ "SRV" ], "x-auditable": true } }, "type": "object" } ], "title": "SRV Record" }, "dns-records_SSHFPRecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "Formatted SSHFP content. See 'data' to set SSHFP properties.", "readOnly": true, "type": "string", "x-auditable": true }, "data": { "description": "Components of a SSHFP record.", "type": "object", "properties": { "algorithm": { "description": "Algorithm.", "type": "number", "example": 2, "maximum": 255, "minimum": 0, "x-auditable": true }, "fingerprint": { "description": "Fingerprint.", "type": "string", "x-auditable": true }, "type": { "description": "Type.", "type": "number", "example": 1, "maximum": 255, "minimum": 0, "x-auditable": true } } }, "type": { "description": "Record type.", "type": "string", "example": "SSHFP", "enum": [ "SSHFP" ], "x-auditable": true } }, "type": "object" } ], "title": "SSHFP Record" }, "dns-records_SVCBRecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "Formatted SVCB content. See 'data' to set SVCB properties.", "readOnly": true, "type": "string", "x-auditable": true }, "data": { "description": "Components of a SVCB record.", "type": "object", "properties": { "priority": { "description": "Priority.", "type": "number", "example": 1, "maximum": 65535, "minimum": 0, "x-auditable": true }, "target": { "description": "Target.", "type": "string", "example": ".", "x-auditable": true }, "value": { "description": "Value.", "type": "string", "example": "alpn=\"h3,h2\" ipv4hint=\"127.0.0.1\" ipv6hint=\"::1\"", "x-auditable": true } } }, "type": { "description": "Record type.", "type": "string", "example": "SVCB", "enum": [ "SVCB" ], "x-auditable": true } }, "type": "object" } ], "title": "SVCB Record" }, "dns-records_TLSARecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "Formatted TLSA content. See 'data' to set TLSA properties.", "readOnly": true, "type": "string", "x-auditable": true }, "data": { "description": "Components of a TLSA record.", "type": "object", "properties": { "certificate": { "description": "Certificate.", "type": "string", "x-auditable": true }, "matching_type": { "description": "Matching Type.", "type": "number", "example": 1, "maximum": 255, "minimum": 0, "x-auditable": true }, "selector": { "description": "Selector.", "type": "number", "example": 0, "maximum": 255, "minimum": 0, "x-auditable": true }, "usage": { "description": "Usage.", "type": "number", "example": 0, "maximum": 255, "minimum": 0, "x-auditable": true } } }, "type": { "description": "Record type.", "type": "string", "example": "TLSA", "enum": [ "TLSA" ], "x-auditable": true } }, "type": "object" } ], "title": "TLSA Record" }, "dns-records_TXTRecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "Text content for the record. The content must consist of quoted \"character strings\" (RFC 1035), each with a length of up to 255 bytes. Strings exceeding this allowed maximum length are automatically split.\n\nLearn more at .", "example": "\"v=spf1 include:example.com -all\"", "type": "string", "x-auditable": true }, "type": { "description": "Record type.", "type": "string", "example": "TXT", "enum": [ "TXT" ], "x-auditable": true } }, "type": "object" } ], "title": "TXT Record" }, "dns-records_URIRecord": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-shared-fields" }, { "properties": { "content": { "description": "Formatted URI content. See 'data' to set URI properties.", "readOnly": true, "type": "string", "x-auditable": true }, "data": { "description": "Components of a URI record.", "type": "object", "properties": { "target": { "description": "The record content.", "type": "string", "example": "http://example.com/example.html", "x-auditable": true }, "weight": { "description": "The record weight.", "type": "number", "example": 20, "maximum": 65535, "minimum": 0, "x-auditable": true } } }, "priority": { "$ref": "#/components/schemas/dns-records_priority" }, "type": { "description": "Record type.", "type": "string", "example": "URI", "enum": [ "URI" ], "x-auditable": true } }, "type": "object" } ], "title": "URI Record" }, "dns-records_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "dns-records_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/dns-records_messages" }, "messages": { "$ref": "#/components/schemas/dns-records_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "dns-records_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/dns-records_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/dns-records_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "dns-records_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_api-response-common" } ] }, "dns-records_comment": { "description": "Comments or notes about the DNS record. This field has no effect on DNS responses.", "type": "string", "example": "Domain verification record", "x-auditable": true }, "dns-records_direction": { "description": "Direction to order DNS records in.", "type": "string", "default": "asc", "enum": [ "asc", "desc" ] }, "dns-records_dns-record-batch-delete": { "type": "object", "allOf": [ { "properties": { "id": { "$ref": "#/components/schemas/dns-records_identifier" } }, "type": "object" } ], "required": [ "id" ] }, "dns-records_dns-record-batch-patch": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/dns-records_identifier" } }, "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-patch" } ], "required": [ "id" ] }, "dns-records_dns-record-batch-post": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-post" } ] }, "dns-records_dns-record-batch-put": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/dns-records_identifier" } }, "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-post" } ], "required": [ "id" ] }, "dns-records_dns-record-patch": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-without-data" }, { "$ref": "#/components/schemas/dns-records_dns-record-with-data" } ] }, "dns-records_dns-record-post": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-without-data" }, { "$ref": "#/components/schemas/dns-records_dns-record-with-data" } ] }, "dns-records_dns-record-response": { "type": "object", "allOf": [ { "anyOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-without-data" }, { "$ref": "#/components/schemas/dns-records_dns-record-with-data" } ], "type": "object" }, { "properties": { "comment_modified_on": { "description": "When the record comment was last modified. Omitted if there is no comment.", "type": "string", "format": "date-time", "example": "2024-01-01T05:20:00.12345Z", "readOnly": true, "x-stainless-terraform-configurability": "computed" }, "created_on": { "description": "When the record was created.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true, "x-stainless-terraform-configurability": "computed" }, "id": { "$ref": "#/components/schemas/dns-records_identifier" }, "meta": { "description": "Extra Cloudflare-specific metadata about the record.", "type": "object", "properties": { "dead_glue": { "description": "Whether this glue record is not served because a shallower NS delegation takes precedence over the deeper delegation that needs it. Present only when true; reachable glue carries only `is_glue`. See [Unreachable glue records](https://developers.cloudflare.com/dns/manage-dns-records/reference/shadowed-records#unreachable-glue-records).\n", "type": "boolean", "example": true, "readOnly": true }, "is_glue": { "description": "Whether this A or AAAA record is glue for a subdomain NS delegation. See [Glue records](https://developers.cloudflare.com/dns/manage-dns-records/reference/shadowed-records#glue-records).\n", "type": "boolean", "example": true, "readOnly": true }, "shadowed_by": { "description": "IDs of the NS records that shadow this record. See [Shadowed records](https://developers.cloudflare.com/dns/manage-dns-records/reference/shadowed-records).\n", "type": "array", "items": { "example": "372e67954025e0ba6aaa6d586b9e0b59", "type": "string" }, "readOnly": true }, "shadowed_records_count": { "description": "Number of records shadowed by this NS delegation. See [Shadowed records](https://developers.cloudflare.com/dns/manage-dns-records/reference/shadowed-records).\n", "type": "integer", "example": 42, "maximum": 10000, "minimum": 0, "readOnly": true } }, "readOnly": true, "x-stainless-terraform-configurability": "computed" }, "modified_on": { "description": "When the record was last modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true, "x-stainless-terraform-configurability": "computed" }, "proxiable": { "description": "Whether the record can be proxied by Cloudflare or not.", "type": "boolean", "example": true, "readOnly": true, "x-stainless-terraform-configurability": "computed" }, "tags_modified_on": { "description": "When the record tags were last modified. Omitted if there are no tags.", "type": "string", "format": "date-time", "example": "2025-01-01T05:20:00.12345Z", "readOnly": true, "x-stainless-terraform-configurability": "computed" } }, "required": [ "id", "proxiable", "created_on", "modified_on", "meta" ], "type": "object" } ], "required": [ "name", "type", "content", "data", "proxied", "ttl", "settings", "comment", "tags" ] }, "dns-records_dns-record-scan-batch-accept": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_dns-record-patch" } ] }, "dns-records_dns-record-scan-batch-reject": { "type": "object", "allOf": [ { "properties": { "id": { "$ref": "#/components/schemas/dns-records_identifier" } }, "type": "object" } ], "required": [ "id" ] }, "dns-records_dns-record-shared-fields": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/dns-records_comment" }, "name": { "$ref": "#/components/schemas/dns-records_name" }, "proxied": { "$ref": "#/components/schemas/dns-records_proxied" }, "settings": { "$ref": "#/components/schemas/dns-records_settings" }, "tags": { "$ref": "#/components/schemas/dns-records_tags" }, "ttl": { "$ref": "#/components/schemas/dns-records_ttl" } } }, "dns-records_dns-record-with-data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/dns-records_CAARecord" }, { "$ref": "#/components/schemas/dns-records_CERTRecord" }, { "$ref": "#/components/schemas/dns-records_DNSKEYRecord" }, { "$ref": "#/components/schemas/dns-records_DSRecord" }, { "$ref": "#/components/schemas/dns-records_HTTPSRecord" }, { "$ref": "#/components/schemas/dns-records_LOCRecord" }, { "$ref": "#/components/schemas/dns-records_NAPTRRecord" }, { "$ref": "#/components/schemas/dns-records_SMIMEARecord" }, { "$ref": "#/components/schemas/dns-records_SRVRecord" }, { "$ref": "#/components/schemas/dns-records_SSHFPRecord" }, { "$ref": "#/components/schemas/dns-records_SVCBRecord" }, { "$ref": "#/components/schemas/dns-records_TLSARecord" }, { "$ref": "#/components/schemas/dns-records_URIRecord" } ] }, "dns-records_dns-record-without-data": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/dns-records_ARecord" }, { "$ref": "#/components/schemas/dns-records_AAAARecord" }, { "$ref": "#/components/schemas/dns-records_CNAMERecord" }, { "$ref": "#/components/schemas/dns-records_MXRecord" }, { "$ref": "#/components/schemas/dns-records_NSRecord" }, { "$ref": "#/components/schemas/dns-records_OPENPGPKEYRecord" }, { "$ref": "#/components/schemas/dns-records_PTRRecord" }, { "$ref": "#/components/schemas/dns-records_TXTRecord" } ] }, "dns-records_dns-request-batch-object": { "type": "object", "properties": { "deletes": { "type": "array", "items": { "$ref": "#/components/schemas/dns-records_dns-record-batch-delete" } }, "patches": { "type": "array", "items": { "$ref": "#/components/schemas/dns-records_dns-record-batch-patch" } }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/dns-records_dns-record-batch-post" } }, "puts": { "type": "array", "items": { "$ref": "#/components/schemas/dns-records_dns-record-batch-put" } } } }, "dns-records_dns-request-review-scan-object": { "type": "object", "properties": { "accepts": { "type": "array", "items": { "$ref": "#/components/schemas/dns-records_dns-record-scan-batch-accept" } }, "rejects": { "type": "array", "items": { "$ref": "#/components/schemas/dns-records_dns-record-scan-batch-reject" } } } }, "dns-records_dns-response-batch-object": { "type": "object", "properties": { "deletes": { "type": "array", "items": { "$ref": "#/components/schemas/dns-records_dns-record-response" } }, "patches": { "type": "array", "items": { "$ref": "#/components/schemas/dns-records_dns-record-response" } }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/dns-records_dns-record-response" } }, "puts": { "type": "array", "items": { "$ref": "#/components/schemas/dns-records_dns-record-response" } } } }, "dns-records_dns-response-review-scan-object": { "type": "object", "properties": { "accepts": { "type": "array", "items": { "$ref": "#/components/schemas/dns-records_dns-record-response" } }, "rejects": { "type": "array", "items": { "$ref": "#/components/schemas/dns-records_identifier" } } } }, "dns-records_dns_response_account_usage": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "internal_record_quota": { "description": "Maximum number of DNS records allowed across all internal zones in the account. Only present if internal DNS is enabled.", "type": "integer", "example": 1000000, "minimum": 0 }, "internal_record_usage": { "description": "Current number of DNS records across all internal zones in the account. Only present if internal DNS is enabled.", "type": "integer", "example": 5000, "minimum": 0 }, "record_quota": { "description": "Maximum number of DNS records allowed across all public zones in the account. Null if using zone-level quota.", "type": "integer", "example": 1000000, "minimum": 0, "nullable": true }, "record_usage": { "description": "Current number of DNS records across all public zones in the account.", "type": "integer", "example": 5000, "minimum": 0 } }, "required": [ "record_usage", "record_quota" ] } }, "type": "object" } ] }, "dns-records_dns_response_batch": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dns-records_dns-response-batch-object" } }, "type": "object" } ] }, "dns-records_dns_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/dns-records_dns-record-response" } } }, "type": "object" } ] }, "dns-records_dns_response_import_scan": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "recs_added": { "description": "Number of DNS records added.", "type": "number", "example": 5 }, "total_records_parsed": { "description": "Total number of DNS records parsed.", "type": "number", "example": 5 } } } }, "type": "object" } ] }, "dns-records_dns_response_review_scan": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dns-records_dns-response-review-scan-object" } }, "type": "object" } ] }, "dns-records_dns_response_single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dns-records_dns-record-response" } }, "type": "object" } ] }, "dns-records_dns_response_trigger_scan": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_api-response-single" } ] }, "dns-records_dns_response_zone_usage": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-records_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "record_quota": { "description": "Maximum number of DNS records allowed for the zone. Null if using account-level quota.", "type": "integer", "example": 200, "minimum": 0, "nullable": true }, "record_usage": { "description": "Current number of DNS records in the zone.", "type": "integer", "example": 150, "minimum": 0 } }, "required": [ "record_usage", "record_quota" ] } }, "type": "object" } ] }, "dns-records_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "dns-records_match": { "description": "Whether to match all search requirements or at least one (any). If set to `all`, acts like a logical AND between filters. If set to `any`, acts like a logical OR instead. Note that the interaction between tag filters is controlled by the `tag-match` parameter instead.\n", "type": "string", "example": "any", "default": "all", "enum": [ "any", "all" ] }, "dns-records_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "dns-records_name": { "description": "Complete DNS record name, including the zone name, in Punycode.", "type": "string", "example": "example.com", "maxLength": 255, "minLength": 1, "x-auditable": true }, "dns-records_order": { "description": "Field to order DNS records by.", "type": "string", "default": "type", "enum": [ "type", "name", "content", "ttl", "proxied" ] }, "dns-records_page": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 }, "dns-records_per_page": { "description": "Number of DNS records per page.", "type": "number", "example": 5, "default": 100, "maximum": 5000000, "minimum": 1 }, "dns-records_priority": { "description": "Required for MX and URI records; ignored for other record types (but may still be returned by the API). Records with lower priorities are preferred. This field is to be deprecated in favor of the priority field within the data map.", "type": "number", "example": 10, "maximum": 65535, "minimum": 0, "x-auditable": true }, "dns-records_proxied": { "description": "Whether the record is receiving the performance and security benefits of Cloudflare.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "dns-records_search": { "description": "Allows searching in multiple properties of a DNS record simultaneously. This parameter is intended for human users, not automation. Its exact behavior is intentionally left unspecified and is subject to change in the future. This parameter works independently of the `match` setting. For automated searches, please use the other available parameters.\n", "type": "string", "example": "www.cloudflare.com" }, "dns-records_settings": { "description": "Settings for the DNS record.", "type": "object", "properties": { "ipv4_only": { "description": "When enabled, only A records will be generated, and AAAA records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "ipv6_only": { "description": "When enabled, only AAAA records will be generated, and A records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.", "type": "boolean", "example": true, "default": false, "x-auditable": true } } }, "dns-records_tag_match": { "description": "Whether to match all tag search requirements or at least one (any). If set to `all`, acts like a logical AND between tag filters. If set to `any`, acts like a logical OR instead. Note that the regular `match` parameter is still used to combine the resulting condition with other filters that aren't related to tags.\n", "type": "string", "example": "any", "default": "all", "enum": [ "any", "all" ] }, "dns-records_tags": { "description": "Custom tags for the DNS record. This field has no effect on DNS responses.", "type": "array", "items": { "description": "Individual tag of the form name:value (the name must consist of only letters, numbers, underscores and hyphens)", "example": "owner:dns-team", "type": "string", "x-auditable": true }, "default": [], "x-stainless-collection-type": "set" }, "dns-records_ttl": { "description": "Time To Live (TTL) of the DNS record in seconds. Setting to 1 means 'automatic'. Value must be between 60 and 86400, with the minimum reduced to 30 for Enterprise zones.", "type": "number", "example": 3600, "default": 1, "anyOf": [ { "example": 3600, "maximum": 86400, "minimum": 30, "type": "number" }, { "enum": [ 1 ], "type": "number" } ], "x-auditable": true }, "dns-records_type": { "description": "Record type.", "type": "string", "example": "A", "enum": [ "A", "AAAA", "CAA", "CERT", "CNAME", "DNSKEY", "DS", "HTTPS", "LOC", "MX", "NAPTR", "NS", "OPENPGPKEY", "PTR", "SMIMEA", "SRV", "SSHFP", "SVCB", "TLSA", "TXT", "URI" ], "x-auditable": true }, "dns-settings_account_settings": { "type": "object", "properties": { "enforce_dns_only": { "$ref": "#/components/schemas/dns-settings_enforce_dns_only" }, "zone_defaults": { "$ref": "#/components/schemas/dns-settings_dns-settings-account-response" } }, "required": [ "zone_defaults" ] }, "dns-settings_account_settings_patch": { "type": "object", "properties": { "enforce_dns_only": { "$ref": "#/components/schemas/dns-settings_enforce_dns_only" }, "zone_defaults": { "$ref": "#/components/schemas/dns-settings_dns-settings-account-patch" } } }, "dns-settings_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "dns-settings_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/dns-settings_messages" }, "messages": { "$ref": "#/components/schemas/dns-settings_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "dns-settings_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/dns-settings_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/dns-settings_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "dns-settings_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_api-response-common" } ] }, "dns-settings_created_time": { "description": "When the view was created.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true, "x-auditable": true }, "dns-settings_direction": { "description": "Direction to order DNS views in.", "type": "string", "default": "asc", "enum": [ "asc", "desc" ] }, "dns-settings_dns-settings-account-patch": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_dns-settings-patch" }, { "properties": { "nameservers": { "description": "Settings determining the nameservers through which the zone should be available.", "type": "object", "properties": { "type": { "description": "Nameserver type", "type": "string", "example": "cloudflare.standard", "enum": [ "cloudflare.standard", "cloudflare.advanced", "cloudflare.standard.random", "custom.account", "custom.tenant" ], "x-auditable": true } }, "x-stainless-terraform-configurability": "computed_optional" } }, "type": "object" } ] }, "dns-settings_dns-settings-account-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_dns-settings-response" }, { "properties": { "nameservers": { "description": "Settings determining the nameservers through which the zone should be available.", "type": "object", "properties": { "type": { "description": "Nameserver type", "type": "string", "example": "cloudflare.standard", "enum": [ "cloudflare.standard", "cloudflare.advanced", "cloudflare.standard.random", "custom.account", "custom.tenant" ], "x-auditable": true } }, "required": [ "type" ] } }, "required": [ "nameservers" ], "type": "object" } ] }, "dns-settings_dns-settings-base": { "type": "object", "properties": { "flatten_all_cnames": { "$ref": "#/components/schemas/dns-settings_flatten_all_cnames" }, "foundation_dns": { "$ref": "#/components/schemas/dns-settings_foundation_dns" }, "internal_dns": { "$ref": "#/components/schemas/dns-settings_internal_dns_base" }, "multi_provider": { "$ref": "#/components/schemas/dns-settings_multi_provider" }, "ns_ttl": { "$ref": "#/components/schemas/dns-settings_ns_ttl" }, "secondary_overrides": { "$ref": "#/components/schemas/dns-settings_secondary_overrides" }, "soa": { "$ref": "#/components/schemas/dns-settings_soa-base" }, "zone_mode": { "$ref": "#/components/schemas/dns-settings_zone_mode" } } }, "dns-settings_dns-settings-patch": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_dns-settings-base" } ] }, "dns-settings_dns-settings-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_dns-settings-base" }, { "properties": { "internal_dns": { "$ref": "#/components/schemas/dns-settings_internal_dns_response" }, "soa": { "$ref": "#/components/schemas/dns-settings_soa-response" } }, "required": [ "flatten_all_cnames", "foundation_dns", "multi_provider", "secondary_overrides", "soa", "ns_ttl", "zone_mode", "internal_dns" ], "type": "object" } ] }, "dns-settings_dns-settings-zone-patch": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_dns-settings-patch" }, { "properties": { "nameservers": { "description": "Settings determining the nameservers through which the zone should be available.", "type": "object", "properties": { "ns_set": { "description": "Configured nameserver set to be used for this zone", "type": "integer", "example": 1, "maximum": 5, "minimum": 1, "x-auditable": true }, "type": { "description": "Nameserver type", "type": "string", "example": "cloudflare.standard", "enum": [ "cloudflare.standard", "cloudflare.advanced", "custom.account", "custom.tenant", "custom.zone" ], "x-auditable": true } }, "x-stainless-terraform-configurability": "computed_optional" } }, "type": "object" } ] }, "dns-settings_dns-settings-zone-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_dns-settings-response" }, { "properties": { "nameservers": { "description": "Settings determining the nameservers through which the zone should be available.", "type": "object", "properties": { "ns_set": { "description": "Configured nameserver set to be used for this zone", "type": "integer", "example": 1, "maximum": 5, "minimum": 1, "x-auditable": true }, "type": { "description": "Nameserver type", "type": "string", "example": "cloudflare.standard", "enum": [ "cloudflare.standard", "cloudflare.advanced", "custom.account", "custom.tenant", "custom.zone" ], "x-auditable": true } }, "required": [ "type" ] } }, "required": [ "nameservers" ], "type": "object" } ] }, "dns-settings_dns-view": { "type": "object", "properties": { "created_time": { "$ref": "#/components/schemas/dns-settings_created_time" }, "modified_time": { "$ref": "#/components/schemas/dns-settings_modified_time" }, "name": { "$ref": "#/components/schemas/dns-settings_name" }, "zones": { "$ref": "#/components/schemas/dns-settings_zones" } } }, "dns-settings_dns-view-patch": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_dns-view" } ] }, "dns-settings_dns-view-post": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_dns-view" } ], "required": [ "name", "zones" ] }, "dns-settings_dns-view-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_dns-view" }, { "properties": { "id": { "$ref": "#/components/schemas/dns-settings_identifier" } }, "required": [ "id" ], "type": "object" } ], "required": [ "id", "name", "zones", "created_time", "modified_time" ] }, "dns-settings_dns_response_single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dns-settings_account_settings" } }, "type": "object" } ], "required": [ "result" ] }, "dns-settings_dns_response_single-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dns-settings_dns-settings-zone-response" } }, "type": "object" } ], "required": [ "result" ] }, "dns-settings_dns_view_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/dns-settings_dns-view-response" } } }, "type": "object" } ] }, "dns-settings_dns_view_response_single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dns-settings_dns-view-response" } }, "type": "object" } ] }, "dns-settings_enforce_dns_only": { "description": "When enabled, forces all proxied DNS records in the account to behave as DNS-only at the edge, regardless of each record's individual proxy setting. Note that this account-level override does not modify the records themselves; it only affects how they are served at the edge. See more on [Enforce DNS-only](https://developers.cloudflare.com/dns/proxy-status/enforce-dns-only).", "type": "boolean", "example": false, "x-auditable": true }, "dns-settings_flatten_all_cnames": { "description": "Whether to flatten all CNAME records in the zone. Note that, due to DNS limitations, a CNAME record at the zone apex will always be flattened.", "type": "boolean", "example": false, "x-auditable": true }, "dns-settings_foundation_dns": { "description": "Deprecated. Use nameservers.type to configure Advanced Nameservers.", "type": "boolean", "example": false, "deprecated": true, "x-auditable": true, "x-stainless-deprecation-message": "foundation_dns is deprecated. Use nameservers.type: cloudflare.advanced to turn on Advanced Nameservers and cloudflare.standard to turn it off. This field will be removed in a future API version.\n" }, "dns-settings_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "dns-settings_internal_dns_base": { "description": "Settings for this internal zone.", "type": "object", "properties": { "reference_zone_id": { "description": "The ID of the zone to fallback to.", "type": "string", "example": { "description": "Identifier.", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "type": "string", "x-auditable": true } } }, "x-stainless-terraform-configurability": "computed_optional" }, "dns-settings_internal_dns_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_internal_dns_base" }, { "required": [ "reference_zone_id" ], "type": "object" } ] }, "dns-settings_match": { "description": "Whether to match all search requirements or at least one (any). If set to `all`, acts like a logical AND between filters. If set to `any`, acts like a logical OR instead.\n", "type": "string", "example": "any", "default": "all", "enum": [ "any", "all" ] }, "dns-settings_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "dns-settings_modified_time": { "description": "When the view was last modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true, "x-auditable": true }, "dns-settings_multi_provider": { "description": "Whether to enable multi-provider DNS, which causes Cloudflare to activate the zone even when non-Cloudflare NS records exist, and to respect NS records at the zone apex during outbound zone transfers.", "type": "boolean", "example": false, "x-auditable": true }, "dns-settings_name": { "description": "The name of the view.", "type": "string", "example": "my view", "maxLength": 255, "minLength": 1, "x-auditable": true }, "dns-settings_ns_ttl": { "description": "The time to live (TTL) of the zone's nameserver (NS) records.", "type": "number", "example": 86400, "maximum": 86400, "minimum": 30, "x-auditable": true }, "dns-settings_order": { "description": "Field to order DNS views by.", "type": "string", "default": "type", "enum": [ "name", "created_on", "modified_on" ] }, "dns-settings_page": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 }, "dns-settings_per_page": { "description": "Number of DNS views per page.", "type": "number", "example": 5, "default": 100, "maximum": 5000000, "minimum": 1 }, "dns-settings_secondary_overrides": { "description": "Allows a Secondary DNS zone to use (proxied) override records and CNAME flattening at the zone apex.", "type": "boolean", "example": false, "x-auditable": true }, "dns-settings_soa-base": { "description": "Components of the zone's SOA record.", "type": "object", "properties": { "expire": { "description": "Time in seconds of being unable to query the primary server after which secondary servers should stop serving the zone.", "type": "number", "example": 604800, "maximum": 2419200, "minimum": 86400, "x-auditable": true }, "min_ttl": { "description": "The time to live (TTL) for negative caching of records within the zone.", "type": "number", "example": 1800, "maximum": 86400, "minimum": 60, "x-auditable": true }, "mname": { "description": "The primary nameserver, which may be used for outbound zone transfers. If null, a Cloudflare-assigned value will be used.", "type": "string", "example": "kristina.ns.cloudflare.com", "nullable": true, "x-auditable": true }, "refresh": { "description": "Time in seconds after which secondary servers should re-check the SOA record to see if the zone has been updated.", "type": "number", "example": 10000, "maximum": 86400, "minimum": 600, "x-auditable": true }, "retry": { "description": "Time in seconds after which secondary servers should retry queries after the primary server was unresponsive.", "type": "number", "example": 2400, "maximum": 86400, "minimum": 600, "x-auditable": true }, "rname": { "description": "The email address of the zone administrator, with the first label representing the local part of the email address.", "type": "string", "example": "admin.example.com", "x-auditable": true }, "ttl": { "description": "The time to live (TTL) of the SOA record itself.", "type": "number", "example": 3600, "maximum": 86400, "minimum": 300, "x-auditable": true } }, "x-stainless-terraform-configurability": "computed_optional" }, "dns-settings_soa-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dns-settings_soa-base" }, { "required": [ "mname", "rname", "refresh", "retry", "expire", "min_ttl", "ttl" ], "type": "object" } ] }, "dns-settings_zone_mode": { "description": "Whether the zone mode is a regular or CDN/DNS only zone.", "type": "string", "example": "dns_only", "enum": [ "standard", "cdn_only", "dns_only" ], "x-auditable": true }, "dns-settings_zones": { "description": "The list of zones linked to this view.", "type": "array", "items": { "description": "The zone ID.", "example": "372e67954025e0ba6aaa6d586b9e0b59", "maxLength": 32, "minLength": 32, "type": "string", "x-auditable": true }, "x-stainless-collection-type": "set" }, "dnssec_algorithm": { "description": "Algorithm key code.", "type": "string", "example": "13", "nullable": true, "readOnly": true, "x-auditable": true }, "dnssec_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/dnssec_messages" }, "messages": { "$ref": "#/components/schemas/dnssec_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "dnssec_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/dnssec_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/dnssec_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "dnssec_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dnssec_api-response-common" } ] }, "dnssec_delete_dnssec_response_single": { "allOf": [ { "$ref": "#/components/schemas/dnssec_api-response-single" }, { "properties": { "result": { "type": "string", "example": "" } }, "type": "object" } ] }, "dnssec_digest": { "description": "Digest hash.", "type": "string", "example": "48E939042E82C22542CB377B580DFDC52A361CEFDC72E7F9107E2B6BD9306A45", "nullable": true, "readOnly": true, "x-auditable": true }, "dnssec_digest_algorithm": { "description": "Type of digest algorithm.", "type": "string", "example": "SHA256", "nullable": true, "readOnly": true, "x-auditable": true }, "dnssec_digest_type": { "description": "Coded type for digest algorithm.", "type": "string", "example": "2", "nullable": true, "readOnly": true, "x-auditable": true }, "dnssec_dnskey_record": { "type": "object", "properties": { "Algorithm": { "type": "integer", "example": 13, "nullable": true, "readOnly": true }, "Flags": { "type": "integer", "example": 256, "nullable": true, "readOnly": true }, "Hdr": { "$ref": "#/components/schemas/dnssec_dnskey_record_header" }, "Protocol": { "type": "integer", "example": 3, "nullable": true, "readOnly": true }, "PublicKey": { "type": "string", "example": "oXiGYrSTO+LSCJ3mohc8EP+CzF9KxBj8/ydXJ22pKuZP3VAC3/Md/k7xZfz470CoRyZJ6gV6vml07IC3d8xqhA==", "nullable": true, "readOnly": true } } }, "dnssec_dnskey_record_header": { "type": "object", "properties": { "Class": { "type": "integer", "example": 1, "nullable": true, "readOnly": true }, "Name": { "type": "string", "example": "example.com.", "nullable": true, "readOnly": true }, "Rdlength": { "type": "integer", "example": 0, "nullable": true, "readOnly": true }, "Rrtype": { "type": "integer", "example": 48, "nullable": true, "readOnly": true }, "Ttl": { "type": "integer", "example": 3600, "nullable": true, "readOnly": true } } }, "dnssec_dnskey_signing_key": { "type": "object", "properties": { "kek": { "description": "Key encryption key name used to encrypt the private key.", "type": "string", "example": "edge_kek_default", "nullable": true, "readOnly": true }, "privkey": { "description": "Encrypted private key material for the signing key.", "type": "string", "format": "byte", "example": "U3ZlbidzIHZlcnkgc2VjcmV0IGtleQ==", "nullable": true, "readOnly": true }, "pubkey": { "description": "Public key content associated with the signing key.", "type": "string", "example": "256 3 13 oXiGYrSTO+LSCJ3mohc8EP+CzF9KxBj8/ydXJ22pKuZP3VAC3/Md/k7xZfz470CoRyZJ6gV6vml07IC3d8xqhA==", "nullable": true, "readOnly": true } } }, "dnssec_dnssec": { "type": "object", "properties": { "algorithm": { "$ref": "#/components/schemas/dnssec_algorithm" }, "digest": { "$ref": "#/components/schemas/dnssec_digest" }, "digest_algorithm": { "$ref": "#/components/schemas/dnssec_digest_algorithm" }, "digest_type": { "$ref": "#/components/schemas/dnssec_digest_type" }, "dnssec_multi_signer": { "$ref": "#/components/schemas/dnssec_dnssec_multi_signer" }, "dnssec_presigned": { "$ref": "#/components/schemas/dnssec_dnssec_presigned" }, "dnssec_use_nsec3": { "$ref": "#/components/schemas/dnssec_dnssec_use_nsec3" }, "ds": { "$ref": "#/components/schemas/dnssec_ds" }, "flags": { "$ref": "#/components/schemas/dnssec_flags" }, "key_tag": { "$ref": "#/components/schemas/dnssec_key_tag" }, "key_type": { "$ref": "#/components/schemas/dnssec_key_type" }, "modified_on": { "$ref": "#/components/schemas/dnssec_modified_on" }, "public_key": { "$ref": "#/components/schemas/dnssec_public_key" }, "status": { "$ref": "#/components/schemas/dnssec_status" } } }, "dnssec_dnssec_key_state": { "description": "Lifecycle state tag attached to the DNSSEC key.", "type": "string", "example": "active", "enum": [ "active", "publish", "external", "retired", "revoked", "removed" ], "x-auditable": true }, "dnssec_dnssec_multi_signer": { "description": "If true, multi-signer DNSSEC is enabled on the zone, allowing multiple\nproviders to serve a DNSSEC-signed zone at the same time.\nThis is required for DNSKEY records (except those automatically\ngenerated by Cloudflare) to be added to the zone.\n\nSee [Multi-signer DNSSEC](https://developers.cloudflare.com/dns/dnssec/multi-signer-dnssec/) for details.", "type": "boolean", "example": false, "x-auditable": true }, "dnssec_dnssec_presigned": { "description": "If true, allows Cloudflare to transfer in a DNSSEC-signed zone\nincluding signatures from an external provider, without requiring\nCloudflare to sign any records on the fly.\n\nNote that this feature has some limitations.\nSee [Cloudflare as Secondary](https://developers.cloudflare.com/dns/zone-setups/zone-transfers/cloudflare-as-secondary/setup/#dnssec) for details.", "type": "boolean", "example": true, "x-auditable": true }, "dnssec_dnssec_response_single": { "allOf": [ { "$ref": "#/components/schemas/dnssec_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/dnssec_dnssec" } }, "type": "object" } ] }, "dnssec_dnssec_use_nsec3": { "description": "If true, enables the use of NSEC3 together with DNSSEC on the zone.\nCombined with setting dnssec_presigned to true, this enables the use of\nNSEC3 records when transferring in from an external provider.\nIf dnssec_presigned is instead set to false (default), NSEC3 records will be\ngenerated and signed at request time.\n\nSee [DNSSEC with NSEC3](https://developers.cloudflare.com/dns/dnssec/enable-nsec3/) for details.", "type": "boolean", "example": false, "x-auditable": true }, "dnssec_dnssec_zsk": { "type": "object", "properties": { "DNSKEY": { "$ref": "#/components/schemas/dnssec_dnskey_record" }, "Location": { "$ref": "#/components/schemas/dnssec_key_storage_location" }, "Name": { "description": "Internal key name for the ZSK.", "type": "string", "example": "zsk_default", "readOnly": true }, "SigningKey": { "$ref": "#/components/schemas/dnssec_dnskey_signing_key" }, "Tag": { "$ref": "#/components/schemas/dnssec_dnssec_key_state" } } }, "dnssec_dnssec_zsk_response_collection": { "allOf": [ { "$ref": "#/components/schemas/dnssec_api-response-single" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/dnssec_dnssec_zsk" } } }, "type": "object" } ] }, "dnssec_ds": { "description": "Full DS record.", "type": "string", "example": "example.com. 3600 IN DS 16953 13 2 48E939042E82C22542CB377B580DFDC52A361CEFDC72E7F9107E2B6BD9306A45", "nullable": true, "readOnly": true, "x-auditable": true }, "dnssec_flags": { "description": "Flag for DNSSEC record.", "type": "number", "example": 257, "nullable": true, "readOnly": true, "x-auditable": true }, "dnssec_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "dnssec_key_storage_location": { "description": "Storage backend where the DNSSEC key material is stored.", "type": "string", "example": "database", "enum": [ "database", "vault" ], "x-auditable": true }, "dnssec_key_tag": { "description": "Code for key tag.", "type": "number", "example": 42, "nullable": true, "readOnly": true, "x-auditable": true }, "dnssec_key_type": { "description": "Algorithm key type.", "type": "string", "example": "ECDSAP256SHA256", "nullable": true, "readOnly": true, "x-auditable": true }, "dnssec_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "dnssec_modified_on": { "description": "When DNSSEC was last modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00Z", "nullable": true, "readOnly": true, "x-auditable": true }, "dnssec_public_key": { "description": "Public key for DS record.", "type": "string", "example": "oXiGYrSTO+LSCJ3mohc8EP+CzF9KxBj8/ydXJ22pKuZP3VAC3/Md/k7xZfz470CoRyZJ6gV6vml07IC3d8xqhA==", "nullable": true, "readOnly": true, "x-auditable": true }, "dnssec_status": { "description": "Status of DNSSEC, based on user-desired state and presence of necessary records.", "example": "active", "enum": [ "active", "pending", "disabled", "pending-disabled", "error" ], "x-auditable": true }, "dos_DnsProtectionRule": { "type": "object", "properties": { "block_any_queries": { "description": "Whether to block DNS ANY queries. Defaults to true.", "type": "boolean", "x-auditable": true }, "burst_sensitivity": { "description": "The burst sensitivity. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true }, "created_on": { "description": "The creation timestamp of the DNS Protection rule.", "type": "string", "format": "date-time", "x-auditable": true }, "id": { "description": "The unique ID of the DNS Protection rule.", "type": "string", "x-auditable": true }, "mode": { "description": "The mode for DNS Protection. Must be one of 'enabled', 'disabled', 'monitoring'.", "type": "string", "x-auditable": true }, "modified_on": { "description": "The last modification timestamp of the DNS Protection rule.", "type": "string", "format": "date-time", "x-auditable": true }, "name": { "description": "The name of the DNS Protection rule. Value is relative to the 'scope' setting. For 'global' scope, name should be 'global'. For either the 'region' or 'datacenter' scope, name should be the actual name of the region or datacenter, e.g., 'wnam' or 'lax'.", "type": "string", "x-auditable": true }, "profile_sensitivity": { "description": "The profile sensitivity. Recommended setting is 'low'. Must be one of 'low', 'medium', 'high', or 'very_high'.", "type": "string", "x-auditable": true }, "rate_sensitivity": { "description": "The rate sensitivity. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true }, "scope": { "description": "The scope for the DNS Protection rule. Must be one of 'global', 'region', or 'datacenter'.", "type": "string", "x-auditable": true } }, "additionalProperties": false, "required": [ "id", "scope", "name", "mode", "profile_sensitivity", "rate_sensitivity", "burst_sensitivity", "block_any_queries", "created_on", "modified_on" ] }, "dos_DnsProtectionRuleUpdate": { "type": "object", "properties": { "block_any_queries": { "description": "The new value for whether to block DNS ANY queries. Optional.", "type": "boolean", "x-auditable": true }, "burst_sensitivity": { "description": "The new burst sensitivity. Optional. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true }, "mode": { "description": "The new mode for DNS Protection. Optional. Must be one of 'enabled', 'disabled', 'monitoring'.", "type": "string", "x-auditable": true }, "profile_sensitivity": { "description": "The new profile sensitivity. Optional. Recommended setting is 'low'. Must be one of 'low', 'medium', 'high', or 'very_high'.", "type": "string", "x-auditable": true }, "rate_sensitivity": { "description": "The new rate sensitivity. Optional. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true } }, "additionalProperties": false }, "dos_ExpressionFilter": { "type": "object", "properties": { "created_on": { "description": "The creation timestamp of the expression filter.", "type": "string", "format": "date-time", "x-auditable": true }, "expression": { "description": "The filter expression.", "type": "string", "example": "ip.dst in { 192.0.2.0/24 198.51.100.0/24 } and tcp.srcport in { 80 443 10000..65535 }", "x-auditable": true }, "id": { "description": "The unique ID of the expression filter.", "type": "string", "x-auditable": true }, "mode": { "description": "The filter's mode. Must be one of 'enabled', 'disabled', 'monitoring'.", "type": "string", "x-auditable": true }, "modified_on": { "description": "The last modification timestamp of the expression filter.", "type": "string", "format": "date-time", "x-auditable": true } }, "additionalProperties": false, "required": [ "id", "expression", "mode", "created_on", "modified_on" ] }, "dos_ExpressionFilterUpdate": { "type": "object", "properties": { "expression": { "description": "The new filter expression. Optional.", "type": "string", "example": "ip.dst in { 192.0.2.0/24 198.51.100.0/24 } and tcp.srcport in { 80 443 10000..65535 }", "x-auditable": true }, "mode": { "description": "The new mode for the filter. Optional. Must be one of 'enabled', 'disabled', 'monitoring'.", "type": "string", "x-auditable": true } }, "additionalProperties": false }, "dos_InfraPrefix": { "type": "object", "properties": { "comment": { "description": "An optional comment describing the allowlist prefix.", "type": "string", "x-auditable": true }, "created_on": { "description": "The creation timestamp of the allowlist prefix.", "type": "string", "format": "date-time", "x-auditable": true }, "enabled": { "description": "Whether to enable the allowlist prefix into effect. Defaults to false.", "type": "boolean", "x-auditable": true }, "id": { "description": "The unique ID of the allowlist prefix.", "type": "string", "x-auditable": true }, "modified_on": { "description": "The last modification timestamp of the allowlist prefix.", "type": "string", "format": "date-time", "x-auditable": true }, "prefix": { "description": "The allowlist prefix in CIDR format.", "type": "string", "x-auditable": true } }, "additionalProperties": false, "required": [ "id", "prefix", "comment", "enabled", "created_on", "modified_on" ] }, "dos_InfraPrefixUpdate": { "type": "object", "properties": { "comment": { "description": "A comment describing the allowlist prefix. Optional.", "type": "string", "x-auditable": true }, "enabled": { "description": "Whether to enable the allowlist prefix into effect. Optional.", "type": "boolean", "x-auditable": true } }, "additionalProperties": false }, "dos_NewDnsProtectionRule": { "type": "object", "properties": { "block_any_queries": { "description": "Whether to block DNS ANY queries. Optional. Defaults to true.", "type": "boolean", "x-auditable": true }, "burst_sensitivity": { "description": "The burst sensitivity. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true }, "mode": { "description": "The mode for DNS Protection. Must be one of 'enabled', 'disabled', 'monitoring'.", "type": "string", "x-auditable": true }, "name": { "description": "The name of the DNS Protection rule. Value is relative to the 'scope' setting. For 'global' scope, name should be 'global'. For either the 'region' or 'datacenter' scope, name should be the actual name of the region or datacenter, e.g., 'wnam' or 'lax'.", "type": "string", "x-auditable": true }, "profile_sensitivity": { "description": "The profile sensitivity. Recommended setting is 'low'. Must be one of 'low', 'medium', 'high', or 'very_high'.", "type": "string", "x-auditable": true }, "rate_sensitivity": { "description": "The rate sensitivity. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true }, "scope": { "description": "The scope for the DNS Protection rule. Must be one of 'global', 'region', or 'datacenter'.", "type": "string", "x-auditable": true } }, "additionalProperties": false, "required": [ "scope", "name", "mode", "profile_sensitivity", "rate_sensitivity", "burst_sensitivity" ] }, "dos_NewExpressionFilter": { "type": "object", "properties": { "expression": { "description": "The filter expression.", "type": "string", "example": "ip.dst in { 192.0.2.0/24 198.51.100.0/24 } and tcp.srcport in { 80 443 10000..65535 }", "x-auditable": true }, "mode": { "description": "The filter's mode. Must be one of 'enabled', 'disabled', 'monitoring'.", "type": "string", "x-auditable": true } }, "additionalProperties": false, "required": [ "expression", "mode" ] }, "dos_NewInfraPrefix": { "type": "object", "properties": { "comment": { "description": "An comment describing the allowlist prefix.", "type": "string", "x-auditable": true }, "enabled": { "description": "Whether to enable the allowlist prefix into effect.", "type": "boolean", "x-auditable": true }, "prefix": { "description": "The allowlist prefix to add in CIDR format.", "type": "string", "x-auditable": true } }, "additionalProperties": false, "required": [ "prefix", "comment", "enabled" ] }, "dos_NewPrefix": { "type": "object", "properties": { "comment": { "description": "A comment describing the prefix.", "type": "string", "x-auditable": true }, "excluded": { "description": "Whether to exclude the prefix from protection.", "type": "boolean", "x-auditable": true }, "prefix": { "description": "The prefix to add in CIDR format.", "type": "string", "example": "192.0.2.0/24", "x-auditable": true } }, "additionalProperties": false, "required": [ "prefix", "comment", "excluded" ] }, "dos_NewSynProtectionRule": { "type": "object", "properties": { "burst_sensitivity": { "description": "The burst sensitivity. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true }, "mitigation_type": { "description": "The type of mitigation. Must be one of 'challenge' or 'retransmit'. Optional. Defaults to 'challenge'.", "type": "string", "x-auditable": true }, "mode": { "description": "The mode for SYN Protection. Must be one of 'enabled', 'disabled', 'monitoring'.", "type": "string", "x-auditable": true }, "name": { "description": "The name of the SYN Protection rule. Value is relative to the 'scope' setting. For 'global' scope, name should be 'global'. For either the 'region' or 'datacenter' scope, name should be the actual name of the region or datacenter, e.g., 'wnam' or 'lax'.", "type": "string", "x-auditable": true }, "rate_sensitivity": { "description": "The rate sensitivity. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true }, "scope": { "description": "The scope for the SYN Protection rule. Must be one of 'global', 'region', or 'datacenter'.", "type": "string", "x-auditable": true } }, "additionalProperties": false, "required": [ "scope", "name", "mode", "rate_sensitivity", "burst_sensitivity" ] }, "dos_NewTcpFlowProtectionRule": { "type": "object", "properties": { "burst_sensitivity": { "description": "The burst sensitivity. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true }, "mode": { "description": "The mode for the TCP Flow Protection. Must be one of 'enabled', 'disabled', 'monitoring'.", "type": "string", "x-auditable": true }, "name": { "description": "The name of the TCP Flow Protection rule. Value is relative to the 'scope' setting. For 'global' scope, name should be 'global'. For either the 'region' or 'datacenter' scope, name should be the actual name of the region or datacenter, e.g., 'wnam' or 'lax'.", "type": "string", "x-auditable": true }, "rate_sensitivity": { "description": "The rate sensitivity. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true }, "scope": { "description": "The scope for the TCP Flow Protection rule.", "type": "string", "x-auditable": true } }, "additionalProperties": false, "required": [ "scope", "name", "mode", "rate_sensitivity", "burst_sensitivity" ] }, "dos_Prefix": { "type": "object", "properties": { "comment": { "description": "A comment describing the prefix.", "type": "string", "x-auditable": true }, "created_on": { "description": "The creation timestamp of the prefix.", "type": "string", "format": "date-time", "x-auditable": true }, "excluded": { "description": "Whether to exclude the prefix from protection.", "type": "boolean", "x-auditable": true }, "id": { "description": "The unique ID of the prefix.", "type": "string", "x-auditable": true }, "modified_on": { "description": "The last modification timestamp of the prefix.", "type": "string", "format": "date-time", "x-auditable": true }, "prefix": { "description": "The prefix in CIDR format.", "type": "string", "example": "192.0.2.0/24", "x-auditable": true } }, "additionalProperties": false, "required": [ "id", "prefix", "comment", "excluded", "created_on", "modified_on" ] }, "dos_PrefixUpdate": { "type": "object", "properties": { "comment": { "description": "A new comment for the prefix. Optional.", "type": "string", "x-auditable": true }, "excluded": { "description": "Whether to exclude the prefix from protection. Optional.", "type": "boolean", "x-auditable": true } }, "additionalProperties": false }, "dos_ProtectionStatus": { "type": "object", "properties": { "enabled": { "type": "boolean", "x-auditable": true } }, "additionalProperties": false, "required": [ "enabled" ] }, "dos_SynProtectionRule": { "type": "object", "properties": { "burst_sensitivity": { "description": "The burst sensitivity. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true }, "created_on": { "description": "The creation timestamp of the SYN Protection rule.", "type": "string", "format": "date-time", "x-auditable": true }, "id": { "description": "The unique ID of the SYN Protection rule.", "type": "string", "x-auditable": true }, "mitigation_type": { "description": "The type of mitigation for SYN Protection. Must be one of 'challenge' or 'retransmit'.", "type": "string", "x-auditable": true }, "mode": { "description": "The mode for SYN Protection. Must be one of 'enabled', 'disabled', 'monitoring'.", "type": "string", "x-auditable": true }, "modified_on": { "description": "The last modification timestamp of the SYN Protection rule.", "type": "string", "format": "date-time", "x-auditable": true }, "name": { "description": "The name of the SYN Protection rule. Value is relative to the 'scope' setting. For 'global' scope, name should be 'global'. For either the 'region' or 'datacenter' scope, name should be the actual name of the region or datacenter, e.g., 'wnam' or 'lax'.", "type": "string", "x-auditable": true }, "rate_sensitivity": { "description": "The rate sensitivity. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true }, "scope": { "description": "The scope for the SYN Protection rule. Must be one of 'global', 'region', or 'datacenter'.", "type": "string", "x-auditable": true } }, "additionalProperties": false, "required": [ "id", "scope", "name", "mode", "mitigation_type", "rate_sensitivity", "burst_sensitivity", "created_on", "modified_on" ] }, "dos_SynProtectionRuleUpdate": { "type": "object", "properties": { "burst_sensitivity": { "description": "The new burst sensitivity. Optional. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true }, "mitigation_type": { "description": "The new mitigation type. Optional. Must be one of 'challenge' or 'retransmit'.", "type": "string", "x-auditable": true }, "mode": { "description": "The new mode for SYN Protection. Optional. Must be one of 'enabled', 'disabled', 'monitoring'.", "type": "string", "x-auditable": true }, "rate_sensitivity": { "description": "The new rate sensitivity. Optional. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true } }, "additionalProperties": false }, "dos_TcpFlowProtectionRule": { "type": "object", "properties": { "burst_sensitivity": { "description": "The burst sensitivity. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true }, "created_on": { "description": "The creation timestamp of the TCP Flow Protection rule.", "type": "string", "format": "date-time", "x-auditable": true }, "id": { "description": "The unique ID of the TCP Flow Protection rule.", "type": "string", "x-auditable": true }, "mode": { "description": "The mode for TCP Flow Protection. Must be one of 'enabled', 'disabled', 'monitoring'.", "type": "string", "x-auditable": true }, "modified_on": { "description": "The last modification timestamp of the TCP Flow Protection rule.", "type": "string", "format": "date-time", "x-auditable": true }, "name": { "description": "The name of the TCP Flow Protection rule. Value is relative to the 'scope' setting. For 'global' scope, name should be 'global'. For either the 'region' or 'datacenter' scope, name should be the actual name of the region or datacenter, e.g., 'wnam' or 'lax'.", "type": "string", "x-auditable": true }, "rate_sensitivity": { "description": "The rate sensitivity. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true }, "scope": { "description": "The scope for the TCP Flow Protection rule. Must be one of 'global', 'region', or 'datacenter'.", "type": "string", "x-auditable": true } }, "additionalProperties": false, "required": [ "id", "scope", "name", "mode", "rate_sensitivity", "burst_sensitivity", "created_on", "modified_on" ] }, "dos_TcpFlowProtectionRuleUpdate": { "type": "object", "properties": { "burst_sensitivity": { "description": "The new burst sensitivity. Optional. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true }, "mode": { "description": "The new mode for TCP Flow Protection. Optional. Must be one of 'enabled', 'disabled', 'monitoring'.", "type": "string", "x-auditable": true }, "rate_sensitivity": { "description": "The new rate sensitivity. Optional. Must be one of 'low', 'medium', 'high'.", "type": "string", "x-auditable": true } }, "additionalProperties": false }, "dos_UpdateProtectionStatus": { "type": "object", "properties": { "enabled": { "description": "Enables or disables protection.", "type": "boolean", "x-auditable": true } }, "additionalProperties": false, "required": [ "enabled" ] }, "dos_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/dos_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "dos_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/dos_messages" }, "messages": { "$ref": "#/components/schemas/dos_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "dos_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/dos_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/dos_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "dos_api-response-common-paginated": { "$ref": "#/components/schemas/dos_api-response-collection" }, "dos_asn": { "type": "integer" }, "dos_asn_country": { "type": "string", "example": "US" }, "dos_asn_description": { "type": "string", "example": "CLOUDFLARENET" }, "dos_asn_type": { "description": "Infrastructure type of this ASN.", "type": "string", "example": "hosting_provider", "enum": [ "hosting_provider", "isp", "organization" ] }, "dos_dns-protection-rule-list-response": { "allOf": [ { "$ref": "#/components/schemas/dos_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/dos_DnsProtectionRule" } } }, "type": "object" } ] }, "dos_dns-protection-rule-response": { "allOf": [ { "$ref": "#/components/schemas/dos_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/dos_DnsProtectionRule" } }, "type": "object" } ] }, "dos_expression-filter-list-response": { "allOf": [ { "$ref": "#/components/schemas/dos_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/dos_ExpressionFilter" } } }, "type": "object" } ] }, "dos_expression-filter-response": { "allOf": [ { "$ref": "#/components/schemas/dos_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/dos_ExpressionFilter" } }, "type": "object" } ] }, "dos_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "dos_infra-prefix-list-response": { "allOf": [ { "$ref": "#/components/schemas/dos_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/dos_InfraPrefix" } } }, "type": "object" } ] }, "dos_infra-prefix-response": { "allOf": [ { "$ref": "#/components/schemas/dos_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/dos_InfraPrefix" } }, "type": "object" } ] }, "dos_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "dos_prefix-list-response": { "allOf": [ { "$ref": "#/components/schemas/dos_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/dos_Prefix" } } }, "type": "object" } ] }, "dos_prefix-response": { "allOf": [ { "$ref": "#/components/schemas/dos_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/dos_Prefix" } }, "type": "object" } ] }, "dos_protection-status-response": { "allOf": [ { "$ref": "#/components/schemas/dos_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/dos_ProtectionStatus" } }, "type": "object" } ] }, "dos_syn-protection-rule-list-response": { "allOf": [ { "$ref": "#/components/schemas/dos_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/dos_SynProtectionRule" } } }, "type": "object" } ] }, "dos_syn-protection-rule-response": { "allOf": [ { "$ref": "#/components/schemas/dos_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/dos_SynProtectionRule" } }, "type": "object" } ] }, "dos_tcp-flow-protection-rule-list-response": { "allOf": [ { "$ref": "#/components/schemas/dos_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/dos_TcpFlowProtectionRule" } } }, "type": "object" } ] }, "dos_tcp-flow-protection-rule-response": { "allOf": [ { "$ref": "#/components/schemas/dos_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/dos_TcpFlowProtectionRule" } }, "type": "object" } ] }, "dos_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "x-auditable": true }, "dos_uuid": { "description": "UUID.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "x-auditable": true }, "email-auth_ApprovedSourceResponse": { "description": "A single approved sending source", "type": "object", "properties": { "created": { "description": "Deprecated, use created_at", "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.12345Z", "deprecated": true, "x-stainless-deprecation-message": "Use `created_at` instead." }, "created_at": { "description": "Creation timestamp", "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.12345Z" }, "domain": { "description": "The source domain", "type": "string", "example": "sendgrid.net" }, "ips": { "description": "Resolved IP addresses from SPF", "type": "array", "items": { "type": "string" }, "example": [ "192.168.1.1", "10.0.0.1" ] }, "modified": { "description": "Deprecated, use modified_at", "type": "string", "format": "date-time", "example": "2024-01-15T11:45:00.12345Z", "deprecated": true, "x-stainless-deprecation-message": "Use `modified_at` instead." }, "modified_at": { "description": "Last modification timestamp", "type": "string", "format": "date-time", "example": "2024-01-15T11:45:00.12345Z" }, "name": { "description": "Source name (typically same as domain)", "type": "string", "example": "SendGrid" }, "slug": { "description": "URL-friendly identifier", "type": "string", "example": "sendgrid-net" }, "tag": { "description": "Source UUID", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" } } }, "email-auth_ConfigureDmarcReportsRequest": { "description": "Request body for PATCH /dmarc-reports", "type": "object", "properties": { "enabled": { "description": "Enable or disable DMARC reports for this zone", "type": "boolean", "example": true, "nullable": true }, "skip_wizard": { "description": "Skip the DMARC setup wizard", "type": "boolean", "example": false, "nullable": true } } }, "email-auth_DmarcReportResponse": { "description": "Response for GET/PATCH /dmarc-reports", "type": "object", "properties": { "approved_sources": { "description": "List of approved sending sources (omitted when empty)", "type": "array", "items": { "$ref": "#/components/schemas/email-auth_ApprovedSourceResponse" } }, "created": { "description": "Deprecated, use created_at", "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.12345Z", "deprecated": true, "x-stainless-deprecation-message": "Use `created_at` instead." }, "created_at": { "description": "Creation timestamp", "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.12345Z" }, "enabled": { "description": "Whether DMARC reports are enabled", "type": "boolean", "example": true }, "modified": { "description": "Deprecated, use modified_at", "type": "string", "format": "date-time", "example": "2024-01-15T11:45:00.12345Z", "deprecated": true, "x-stainless-deprecation-message": "Use `modified_at` instead." }, "modified_at": { "description": "Last modification timestamp", "type": "string", "format": "date-time", "example": "2024-01-15T11:45:00.12345Z" }, "records": { "$ref": "#/components/schemas/email-auth_ZoneDnsRecords" }, "rua_prefix": { "description": "Prefix for DMARC RUA addresses (32-char hex string)", "type": "string", "example": "9233c80fc89f43e3a7b749605f651868" }, "skip_wizard": { "description": "Whether to skip the setup wizard", "type": "boolean", "example": false }, "status": { "$ref": "#/components/schemas/email-auth_DmarcStatus" }, "tag": { "description": "Use `zone_id` instead", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "deprecated": true, "x-stainless-deprecation-message": "Use `zone_id` instead." }, "zone_id": { "description": "Zone identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } } }, "email-auth_DmarcStatus": { "description": "DMARC configuration status. The API omits this field when DMARC is correctly configured. If the zone lacks a DMARC TXT record of its own, the API resolves _dmarc.{zone} recursively and evaluates whatever that lookup returns. A CNAME at _dmarc.{zone} that points to a valid DMARC record is therefore healthy; the cname-on-dmarc-record value means the CNAME resolves to no DMARC record at all.", "type": "string", "enum": [ "missing-dmarc-report", "multiple-dmarc-reports", "missing-dmarc-rua", "cname-on-dmarc-record", "unauthorized-reporting-domain" ] }, "email-auth_DnsRecordInfo": { "description": "Summary of a single DNS record", "type": "object", "properties": { "content": { "description": "Record content", "example": "v=DMARC1; p=none; rua=mailto:rua@dmarc-reports.cloudflare.net", "type": "string" }, "id": { "description": "DNS record ID", "type": "string", "example": "e5bb46707a802688812d5d1c9f7977d4" }, "name": { "description": "DNS record name", "type": "string", "example": "_dmarc.example.com" }, "resolved": { "description": "For a CNAME record, the TXT content(s) found by following the CNAME chain to its target. An empty array means the chain was resolved but nothing usable was found there; omitted/null means resolution was not attempted for this record (always the case for non-CNAME entries). A CNAME chain that terminates in more than one TXT value at the target yields multiple entries. Populated on entries in cname_dmarc_records, cname_spf_records, and cname_dkim_records.", "type": "array", "items": { "type": "string" }, "example": [ "v=DMARC1; p=reject; rua=mailto:rua@dmarc-reports.cloudflare.net" ], "nullable": true }, "ttl": { "description": "Time to live in seconds", "type": "integer", "example": 300 }, "type": { "description": "Record type", "type": "string", "example": "TXT" } } }, "email-auth_InspectError": { "description": "An error encountered during SPF inspection", "type": "object", "properties": { "code": { "description": "Error code. Known values:\n- `lookup_failed` — DNS TXT lookup failed\n- `spf_not_found` — no SPF record found\n- `invalid_spf` — record does not start with `v=spf1`\n- `invalid_domain` — PSL validation failed\n- `loop_detected` — include/redirect cycle detected\n- `invalid_mechanism` — unrecognised or malformed mechanism\n- `resource_limit_exceeded` — internal resource protection limits exceeded (recursion depth or query budget)\n- `max_lookups` — RFC 7208 10-lookup limit exceeded\n", "type": "string", "example": "max_lookups" }, "details": { "description": "Additional error-specific details (optional).\n- For `invalid_domain` errors: the invalid domain string\n- For `invalid_mechanism` errors: the invalid mechanism text (e.g., \"invalidmech123\")\n- For `loop_detected` errors: the domain that caused the loop\n- For other error types: not present\n", "type": "string", "example": "invalid" }, "domain": { "description": "Domain where the error occurred", "type": "string", "example": "example.com" }, "message": { "description": "Human-readable error message", "type": "string", "example": "RFC 7208 10-lookup limit exceeded" } }, "required": [ "code", "message", "domain" ] }, "email-auth_ResolvedDmarcRecord": { "description": "A DMARC TXT record that a recursive lookup of _dmarc.{zone} returned. Such a record usually lives in another zone outside this account's control, so this schema omits the DNS record ID. The API therefore treats such a record as read-only.", "type": "object", "properties": { "content": { "description": "The TXT record value. The API joins all character-strings into a single string.", "example": "v=DMARC1; p=reject; rua=mailto:rua@dmarc-reports.cloudflare.net", "type": "string" }, "name": { "description": "The name the API queried.", "type": "string", "example": "_dmarc.example.com" } }, "deprecated": true }, "email-auth_SpfComponent": { "description": "A single SPF component (mechanism) in the inspection tree.\n\nThe `value` field includes the qualifier prefix (e.g., \"-all\", \"~mx:example.com\")\nto match the raw SPF record syntax. The qualifier is also available separately\nin the `result` field for programmatic access.\n", "type": "object", "properties": { "lookup_count": { "description": "Number of DNS lookups this component requires (per RFC 7208).\n- MX, A, EXISTS, INCLUDE, REDIRECT, PTR: 1\n- IP4, IP6, ALL: 0\n", "type": "integer", "example": 0 }, "nested": { "description": "Nested SPF tree for INCLUDE or REDIRECT mechanisms.\nOnly present for INCLUDE/REDIRECT components.\n", "allOf": [ { "$ref": "#/components/schemas/email-auth_SpfTree" } ] }, "result": { "$ref": "#/components/schemas/email-auth_SpfResult" }, "type": { "description": "Component type (UPPERCASE)", "type": "string", "example": "IP4", "enum": [ "ALL", "A", "MX", "IP4", "IP6", "EXISTS", "INCLUDE", "PTR", "REDIRECT" ] }, "value": { "description": "Component value with qualifier prefix.\nFor IP4/IP6, stores just the IP address (no \"ip4:\" or \"ip6:\" prefix).\nExamples: \"203.0.113.1\", \"203.0.113.0/24\", \"2001:db8::1/64\", \"-all\", \"~mx:example.com\", \"include:_spf.example.com\"\n", "type": "string", "example": "203.0.113.1" } }, "required": [ "type", "value", "result", "lookup_count" ] }, "email-auth_SpfResult": { "description": "SPF mechanism result qualifier", "type": "string", "enum": [ "pass", "neutral", "fail", "soft_fail", "none", "temp_error", "perm_error" ] }, "email-auth_SpfTree": { "description": "Recursive SPF inspection tree\n", "type": "object", "properties": { "components": { "description": "Parsed SPF components (mechanisms)", "items": { "$ref": "#/components/schemas/email-auth_SpfComponent" }, "type": "array" }, "domain": { "description": "Domain being inspected", "type": "string", "example": "example.com" }, "errors": { "description": "All errors encountered during inspection, collected from the entire tree.\nThis includes errors from nested includes at any depth, providing a quick\noverview of all issues without needing to traverse the nested structure.\nEach error includes a `domain` field to identify where it occurred.\nEmpty array if no errors (omitted from JSON when empty).\n", "type": "array", "items": { "$ref": "#/components/schemas/email-auth_InspectError" }, "example": [] }, "record": { "description": "Raw SPF record content", "type": "string", "example": "v=spf1 ip4:203.0.113.1 include:spf.example.com -all" }, "total_lookups": { "description": "Total number of DNS lookups performed across all includes", "type": "integer", "example": 2 } }, "required": [ "domain", "record", "total_lookups", "components" ] }, "email-auth_ZoneDnsRecords": { "description": "Live DNS records for the zone, grouped by type", "type": "object", "properties": { "bimi_records": { "description": "BIMI TXT records", "type": "array", "items": { "$ref": "#/components/schemas/email-auth_DnsRecordInfo" } }, "cname_dkim_records": { "description": "CNAME records for DKIM selectors. Each selector is resolved independently; when a selector's CNAME resolves to a DKIM TXT record, the API returns that record's content in the `resolved` field of the corresponding entry.", "type": "array", "items": { "$ref": "#/components/schemas/email-auth_DnsRecordInfo" } }, "cname_dmarc_records": { "description": "CNAME records at _dmarc. When such a CNAME resolves to a DMARC TXT record, the API returns that record's content in the `resolved` field of the corresponding entry.", "type": "array", "items": { "$ref": "#/components/schemas/email-auth_DnsRecordInfo" } }, "cname_spf_records": { "description": "CNAME records at the zone apex. When such a CNAME resolves to an SPF TXT record, the API returns that record's content in the `resolved` field of the corresponding entry.", "type": "array", "items": { "$ref": "#/components/schemas/email-auth_DnsRecordInfo" } }, "dkim_records": { "description": "DKIM TXT records", "type": "array", "items": { "$ref": "#/components/schemas/email-auth_DnsRecordInfo" } }, "dmarc_records": { "description": "DMARC TXT records", "type": "array", "items": { "$ref": "#/components/schemas/email-auth_DnsRecordInfo" } }, "resolved_dmarc_records": { "description": "DMARC records that a recursive lookup of _dmarc.{zone} returned. The API populates this only when the zone lacks a DMARC TXT record of its own, which usually means a CNAME delegates DMARC to another zone.", "type": "array", "items": { "$ref": "#/components/schemas/email-auth_ResolvedDmarcRecord" }, "deprecated": true, "x-stainless-deprecation-message": "Use the `resolved` field on the corresponding entry in cname_dmarc_records instead." }, "spf_records": { "description": "SPF TXT records", "type": "array", "items": { "$ref": "#/components/schemas/email-auth_DnsRecordInfo" } } } }, "email-auth_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/email-auth_messages" }, "messages": { "$ref": "#/components/schemas/email-auth_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "email-auth_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/email-auth_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/email-auth_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "email-auth_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/email-auth_api-response-common" } ] }, "email-auth_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "email-auth_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "email-security_ActionEntry": { "type": "object", "properties": { "completed_at": { "description": "Timestamp when the action completed.", "type": "string", "format": "date-time", "nullable": true }, "operation": { "type": "string", "enum": [ "PREVIEW", "QUARANTINE_RELEASE", "SUBMISSION", "MOVE" ] }, "properties": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/email-security_ActionEntryProperties" } ], "nullable": true }, "started_at": { "description": "Timestamp when the action was initiated.", "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "nullable": true }, "success": { "type": "boolean", "nullable": true } }, "required": [ "operation" ] }, "email-security_ActionEntryProperties": { "type": "object", "properties": { "folder": { "type": "string", "nullable": true }, "requested_by": { "type": "string", "nullable": true }, "requested_disposition": { "type": "string", "nullable": true }, "service": { "type": "string", "nullable": true }, "submission_id": { "type": "string", "nullable": true }, "submission_type": { "type": "string", "nullable": true } } }, "email-security_ActionLogEntry": { "type": "object", "properties": { "completed_at": { "description": "Timestamp when action completed.", "type": "string", "format": "date-time", "readOnly": true }, "completed_timestamp": { "description": "Deprecated, use `completed_at` instead. End of life: November 1, 2026.", "type": "string", "deprecated": true, "readOnly": true, "x-stainless-deprecation-message": "Use `completed_at` instead." }, "operation": { "description": "Type of action performed.", "type": "string", "enum": [ "MOVE", "RELEASE", "RECLASSIFY", "SUBMISSION", "QUARANTINE_RELEASE", "PREVIEW" ] }, "properties": { "description": "Additional properties for the action.", "type": "object", "properties": { "folder": { "description": "Target folder for move operations.", "type": "string" }, "requested_by": { "description": "User who requested the action.", "type": "string" } } }, "status": { "description": "Status of the action.", "type": "string", "nullable": true } }, "required": [ "completed_at", "operation" ] }, "email-security_AllowPolicy": { "description": "An email allow policy.", "type": "object", "properties": { "comments": { "type": "string", "example": "Trust all messages send from test@example.com", "maxLength": 1024, "nullable": true }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "readOnly": true }, "id": { "allOf": [ { "$ref": "#/components/schemas/email-security_AllowPolicyId" } ], "readOnly": true }, "is_acceptable_sender": { "description": "Exempts messages from this sender from Spam, Spoof and Bulk dispositions only; Malicious and Suspicious dispositions still apply.", "type": "boolean", "example": false, "x-auditable": true }, "is_exempt_recipient": { "description": "Bypasses all detections for messages to this recipient.", "type": "boolean", "example": false, "x-auditable": true }, "is_recipient": { "description": "Deprecated as of July 1, 2025. Use `is_exempt_recipient` instead. End of life: July 1, 2026.", "type": "boolean", "example": false, "deprecated": true, "x-auditable": true, "x-stainless-deprecation-message": "Use `is_exempt_recipient` instead." }, "is_regex": { "type": "boolean", "example": false, "x-auditable": true }, "is_sender": { "description": "Deprecated as of July 1, 2025. Use `is_trusted_sender` instead. End of life: July 1, 2026.", "type": "boolean", "example": true, "deprecated": true, "x-auditable": true, "x-stainless-deprecation-message": "Use `is_trusted_sender` instead." }, "is_spoof": { "description": "Deprecated as of July 1, 2025. Use `is_acceptable_sender` instead. End of life: July 1, 2026.", "type": "boolean", "example": false, "deprecated": true, "x-auditable": true, "x-stainless-deprecation-message": "Use `is_acceptable_sender` instead." }, "is_trusted_sender": { "description": "Bypasses all detections and link following for messages from this sender.", "type": "boolean", "example": true, "x-auditable": true }, "last_modified": { "description": "Deprecated, use `modified_at` instead. End of life: November 1, 2026.", "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "deprecated": true, "readOnly": true, "x-stainless-deprecation-message": "Use `modified_at` instead." }, "modified_at": { "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "readOnly": true }, "pattern": { "description": "The pattern value to match. The format depends on `pattern_type`: a valid email address for EMAIL (e.g. `user@example.com`), a valid domain name for DOMAIN (e.g. `example.com`), or a plain IPv4 or IPv6 address or CIDR block for IP (e.g. `1.2.3.4`, `1.2.3.0/24`, `2606:4700:4700::1111`, or `2606:4700:4700::/48`); the API rejects private or unique-local, loopback, link-local, unspecified, and IPv4 broadcast addresses, including their IPv4-mapped IPv6 equivalents.", "type": "string", "example": "test@example.com", "maxLength": 1024, "minLength": 1, "x-auditable": true }, "pattern_type": { "$ref": "#/components/schemas/email-security_PatternType" }, "verify_sender": { "description": "Enforce DMARC, SPF or DKIM authentication. When on, Email Security only honors policies that pass authentication.", "type": "boolean", "example": true, "x-auditable": true } }, "required": [ "id", "created_at", "last_modified" ] }, "email-security_AllowPolicyId": { "description": "Allow policy identifier.", "type": "string", "format": "uuid", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "x-auditable": true }, "email-security_AllowPolicyList": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_AllowPolicy" } }, "email-security_Attachment": { "type": "object", "properties": { "content_type": { "description": "MIME type of the attachment.", "type": "string", "nullable": true }, "detection": { "description": "Detection result for this attachment.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/email-security_DispositionLabel" } ], "nullable": true }, "encrypted": { "description": "Whether the attachment is encrypted.", "type": "boolean", "nullable": true }, "filename": { "description": "Name of the attached file.", "type": "string", "nullable": true }, "md5": { "description": "MD5 hash of the attachment.", "type": "string", "nullable": true }, "name": { "description": "Attachment name (alternative to filename).", "type": "string", "nullable": true }, "sha1": { "description": "SHA1 hash of the attachment.", "type": "string", "nullable": true }, "sha256": { "description": "SHA256 hash of the attachment.", "type": "string", "nullable": true }, "size": { "description": "Size of the attachment in bytes.", "type": "integer", "minimum": 0 } }, "required": [ "size" ] }, "email-security_BlockedSender": { "description": "A blocked sender pattern.", "type": "object", "properties": { "comments": { "type": "string", "example": "Block sender with email test@example.com", "maxLength": 1024, "nullable": true }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "readOnly": true }, "id": { "allOf": [ { "$ref": "#/components/schemas/email-security_BlockedSenderId" } ], "readOnly": true }, "is_regex": { "type": "boolean", "example": false, "x-auditable": true }, "last_modified": { "description": "Deprecated, use `modified_at` instead. End of life: November 1, 2026.", "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "deprecated": true, "readOnly": true, "x-stainless-deprecation-message": "Use `modified_at` instead." }, "modified_at": { "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "readOnly": true }, "pattern": { "description": "The pattern value to match. The format depends on `pattern_type`: a valid email address for EMAIL (e.g. `user@example.com`), a valid domain name for DOMAIN (e.g. `example.com`), or a plain IPv4 or IPv6 address or CIDR block for IP (e.g. `1.2.3.4`, `1.2.3.0/24`, `2606:4700:4700::1111`, or `2606:4700:4700::/48`); the API rejects private or unique-local, loopback, link-local, unspecified, and IPv4 broadcast addresses, including their IPv4-mapped IPv6 equivalents.", "type": "string", "example": "test@example.com", "maxLength": 1024, "minLength": 1, "x-auditable": true }, "pattern_type": { "$ref": "#/components/schemas/email-security_PatternType" } } }, "email-security_BlockedSenderId": { "description": "Blocked sender pattern identifier.", "type": "string", "format": "uuid", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "x-auditable": true }, "email-security_BlockedSenderList": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_BlockedSender" } }, "email-security_BulkActionMessageDetail": { "type": "object", "properties": { "action_params": { "$ref": "#/components/schemas/email-security_BulkMessageActionParams" }, "action_type": { "type": "string", "enum": [ "MOVE", "RELEASE" ] }, "alert_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "email_message_id": { "type": "string", "nullable": true }, "message": { "$ref": "#/components/schemas/email-security_MessageDetails" }, "message_id": { "type": "string", "format": "uuid" }, "postfix_id": { "type": "string" }, "processed_at": { "type": "string", "format": "date-time", "nullable": true }, "retry_after": { "description": "When to retry the action if it failed.", "type": "string", "format": "date-time", "nullable": true }, "retry_count": { "type": "integer" }, "status": { "type": "string", "enum": [ "PENDING", "DISCOVERING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED", "SKIPPED" ] }, "status_message": { "type": "string", "nullable": true } }, "required": [ "message_id", "postfix_id", "action_type", "action_params", "status", "retry_count", "created_at" ] }, "email-security_BulkActionRequest": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "MOVE", "RELEASE" ] }, "comment": { "type": "string", "nullable": true }, "destination": { "$ref": "#/components/schemas/email-security_MailboxDestination" }, "expected_disposition": { "$ref": "#/components/schemas/email-security_DispositionLabel" }, "search_params": { "$ref": "#/components/schemas/email-security_BulkSearchParams" } }, "required": [ "action", "search_params" ] }, "email-security_BulkJobActionParams": { "discriminator": { "propertyName": "type" }, "oneOf": [ { "properties": { "destination": { "$ref": "#/components/schemas/email-security_MailboxDestination" }, "expected_disposition": { "$ref": "#/components/schemas/email-security_DispositionLabel" }, "type": { "type": "string", "enum": [ "MOVE" ] } }, "required": [ "type", "destination" ], "type": "object" }, { "properties": { "type": { "type": "string", "enum": [ "RELEASE" ] } }, "required": [ "type" ], "type": "object" } ] }, "email-security_BulkJobDetail": { "type": "object", "properties": { "action_params": { "$ref": "#/components/schemas/email-security_BulkJobActionParams" }, "action_type": { "type": "string", "enum": [ "MOVE", "RELEASE" ] }, "comment": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "job_id": { "type": "string", "format": "uuid" }, "messages_failed": { "type": "integer" }, "messages_pending": { "type": "integer" }, "messages_successful": { "type": "integer" }, "search_params": { "$ref": "#/components/schemas/email-security_BulkSearchParams" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "enum": [ "PENDING", "DISCOVERING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED", "SKIPPED" ] }, "status_message": { "type": "string", "nullable": true }, "total_messages_discovered": { "type": "integer" } }, "required": [ "job_id", "action_type", "action_params", "search_params", "status", "total_messages_discovered", "messages_pending", "messages_successful", "messages_failed", "created_at" ] }, "email-security_BulkMessageActionParams": { "discriminator": { "propertyName": "type" }, "oneOf": [ { "properties": { "client_recipient": { "type": "string" }, "destination": { "$ref": "#/components/schemas/email-security_MailboxDestination" }, "expected_disposition": { "$ref": "#/components/schemas/email-security_DispositionLabel" }, "type": { "type": "string", "enum": [ "MOVE" ] } }, "required": [ "type", "destination", "client_recipient" ], "type": "object" }, { "properties": { "client_recipient": { "type": "string" }, "type": { "type": "string", "enum": [ "RELEASE" ] } }, "required": [ "type", "client_recipient" ], "type": "object" } ] }, "email-security_BulkSearchParams": { "type": "object", "properties": { "action_log": { "description": "Deprecated, use `GET /investigate/{investigate_id}/action_log` instead. End of life: November 1, 2026.", "type": "boolean", "default": false, "deprecated": true, "x-stainless-deprecation-message": "Use GET /investigate/{investigate_id}/action_log instead." }, "alert_id": { "type": "string", "nullable": true }, "delivery_status": { "$ref": "#/components/schemas/email-security_MessageDeliveryStatus" }, "detections_only": { "type": "boolean", "default": true }, "domain": { "type": "string", "nullable": true }, "end": { "description": "End of search date range.", "type": "string", "format": "date-time", "example": "2022-07-25T14:30:00Z" }, "exact_subject": { "type": "string", "nullable": true }, "final_disposition": { "$ref": "#/components/schemas/email-security_DispositionLabel" }, "message_action": { "type": "string", "enum": [ "PREVIEW", "QUARANTINE_RELEASED", "MOVED" ], "nullable": true }, "message_id": { "type": "string", "nullable": true }, "metric": { "type": "string", "nullable": true }, "query": { "nullable": true, "type": "string" }, "recipient": { "type": "string", "nullable": true }, "sender": { "type": "string", "nullable": true }, "smtp_helo_ip": { "description": "Matches messages whose SMTP HELO server IP address equals this value.", "type": "string", "nullable": true }, "start": { "description": "Beginning of search date range.", "type": "string", "format": "date-time", "example": "2022-06-25T14:30:00Z" }, "subject": { "type": "string", "nullable": true }, "submissions": { "type": "boolean", "default": false } } }, "email-security_ContentPolicy": { "description": "A content policy pattern that matches against the subject or body of an email.", "type": "object", "properties": { "created_at": { "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "readOnly": true }, "enabled": { "type": "boolean", "example": true, "x-auditable": true }, "id": { "allOf": [ { "$ref": "#/components/schemas/email-security_ContentPolicyId" } ], "readOnly": true }, "modified_at": { "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "readOnly": true }, "name": { "type": "string", "example": "Block phishing keywords", "maxLength": 256, "minLength": 1, "x-auditable": true }, "notes": { "type": "string", "example": "Blocks common phishing subject lines", "maxLength": 4096, "nullable": true }, "pattern": { "type": "string", "example": "urgent.*verify.*account", "maxLength": 2048, "minLength": 1, "x-auditable": true }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_ContentPolicyTarget" }, "example": [ "SUBJECT" ], "minItems": 1, "x-auditable": true } } }, "email-security_ContentPolicyId": { "description": "Content policy identifier.", "type": "string", "format": "uuid", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "x-auditable": true }, "email-security_ContentPolicyList": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_ContentPolicy" } }, "email-security_ContentPolicyTarget": { "description": "The part of the email to match the pattern against.", "type": "string", "example": "SUBJECT", "enum": [ "SUBJECT", "BODY" ] }, "email-security_CreateAllowPolicy": { "description": "Create an allow policy.", "allOf": [ { "$ref": "#/components/schemas/email-security_AllowPolicy" } ], "required": [ "is_exempt_recipient", "is_trusted_sender", "is_acceptable_sender", "pattern", "is_regex", "verify_sender", "pattern_type" ] }, "email-security_CreateBlockedSender": { "description": "Create a blocked sender pattern.", "allOf": [ { "$ref": "#/components/schemas/email-security_BlockedSender" } ], "required": [ "pattern", "is_regex", "pattern_type" ] }, "email-security_CreateContentPolicy": { "description": "Create a content policy.", "allOf": [ { "$ref": "#/components/schemas/email-security_ContentPolicy" } ], "required": [ "name", "pattern", "targets", "enabled" ] }, "email-security_CreateDomain": { "type": "object", "properties": { "allowed_delivery_modes": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_DeliveryMode" }, "maxItems": 10, "minItems": 1, "x-stainless-collection-type": "set" }, "domain": { "type": "string", "x-auditable": true }, "drop_dispositions": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_DispositionLabel" }, "maxItems": 10, "x-stainless-collection-type": "set" }, "folder": { "allOf": [ { "$ref": "#/components/schemas/email-security_ScannableFolder" } ], "x-stainless-terraform-configurability": "computed_optional" }, "integration_id": { "type": "string", "format": "uuid", "nullable": true, "x-auditable": true }, "ip_restrictions": { "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "192.0.2.0/24", "2001:db8::/32" ], "maxItems": 100, "x-stainless-collection-type": "set" }, "lookback_hops": { "type": "integer", "maximum": 20, "minimum": 1, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "regions": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_Region" }, "maxItems": 10, "minItems": 1, "x-stainless-collection-type": "set" }, "require_tls_inbound": { "type": "boolean", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "require_tls_outbound": { "type": "boolean", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "transport": { "type": "string", "nullable": true, "x-auditable": true } }, "additionalProperties": false, "required": [ "domain", "allowed_delivery_modes", "ip_restrictions", "drop_dispositions", "regions" ] }, "email-security_CreateImpersonationRegistry": { "description": "Create an impersonation registry entry.", "allOf": [ { "$ref": "#/components/schemas/email-security_ImpersonationRegistry" } ], "required": [ "name", "email", "is_email_regex" ] }, "email-security_CreateSendingDomainRestriction": { "description": "Create a sending domain restriction.", "allOf": [ { "$ref": "#/components/schemas/email-security_SendingDomainRestriction" } ], "required": [ "domain", "exclude" ] }, "email-security_CreateTrustedDomain": { "description": "Create a trusted domain.", "allOf": [ { "$ref": "#/components/schemas/email-security_TrustedDomain" } ], "required": [ "pattern", "is_regex", "is_recent", "is_similarity" ] }, "email-security_CreateUrlIgnorePattern": { "description": "Creates a URL ignore pattern that exempts matching URLs from rewriting.", "type": "object", "properties": { "comments": { "description": "Optional note describing the reason for the ignore pattern.", "type": "string", "example": "Trusted internal redirect service", "maxLength": 1024, "nullable": true, "x-auditable": true }, "pattern": { "description": "Regular expression identifying URLs to exempt from rewriting.", "type": "string", "example": "https://example\\.com/.*", "maxLength": 1024, "minLength": 1, "x-auditable": true } }, "additionalProperties": false, "required": [ "pattern" ] }, "email-security_CursorResultInfo": { "type": "object", "properties": { "count": { "description": "Number of items in current page.", "type": "integer", "minimum": 0 }, "next": { "description": "Cursor for next page.", "type": "string", "nullable": true }, "page": { "description": "Deprecated: Always returns 0. End of life: November 1, 2026.", "type": "integer", "deprecated": true, "minimum": 0, "x-stainless-deprecation-message": "This field always returns 0 and is deprecated." }, "per_page": { "description": "Number of items per page.", "type": "integer", "minimum": 0 }, "previous": { "description": "Cursor for previous page.", "type": "string", "nullable": true }, "total_count": { "description": "Deprecated: Always returns 0. End of life: November 1, 2026.", "type": "integer", "deprecated": true, "minimum": 0, "x-stainless-deprecation-message": "This field always returns 0 and is deprecated." } }, "required": [ "per_page", "count", "total_count" ] }, "email-security_CustomerStatus": { "type": "string", "enum": [ "escalated", "reviewed", "unreviewed" ], "nullable": true }, "email-security_DeletedAllowPolicy": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/email-security_AllowPolicyId" } }, "required": [ "id" ] }, "email-security_DeletedBlockedSender": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/email-security_BlockedSenderId" } }, "required": [ "id" ] }, "email-security_DeletedContentPolicy": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/email-security_ContentPolicyId" } }, "required": [ "id" ] }, "email-security_DeletedDomain": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/email-security_DomainId" } }, "required": [ "id" ] }, "email-security_DeletedImpersonationRegistry": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/email-security_ImpersonationRegistryId" } }, "required": [ "id" ] }, "email-security_DeletedSendingDomainRestriction": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/email-security_SendingDomainRestrictionId" } }, "required": [ "id" ] }, "email-security_DeletedTrustedDomain": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/email-security_TrustedDomainId" } }, "required": [ "id" ] }, "email-security_DeletedUrlIgnorePattern": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/email-security_UrlIgnorePatternId" } }, "required": [ "id" ] }, "email-security_DeliveryMode": { "type": "string", "enum": [ "DIRECT", "BCC", "JOURNAL", "API", "RETRO_SCAN" ] }, "email-security_DispositionLabel": { "type": "string", "enum": [ "MALICIOUS", "MALICIOUS-BEC", "SUSPICIOUS", "SPOOF", "SPAM", "BULK", "ENCRYPTED", "EXTERNAL", "UNKNOWN", "NONE" ] }, "email-security_DmarcStatus": { "type": "string", "enum": [ "none", "good", "invalid", null ], "nullable": true }, "email-security_Domain": { "type": "object", "properties": { "allowed_delivery_modes": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_DeliveryMode" }, "x-stainless-collection-type": "set" }, "authorization": { "$ref": "#/components/schemas/email-security_DomainAuthorization" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "readOnly": true }, "dmarc_status": { "$ref": "#/components/schemas/email-security_DmarcStatus" }, "domain": { "type": "string", "example": "example.com", "x-auditable": true }, "drop_dispositions": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_DispositionLabel" }, "x-stainless-collection-type": "set" }, "emails_processed": { "$ref": "#/components/schemas/email-security_EmailsProcessed" }, "folder": { "allOf": [ { "$ref": "#/components/schemas/email-security_ScannableFolder" } ], "x-stainless-terraform-configurability": "computed_optional" }, "id": { "$ref": "#/components/schemas/email-security_DomainId" }, "inbox_provider": { "type": "string", "enum": [ "Microsoft", "Google", null ], "nullable": true }, "integration_id": { "type": "string", "format": "uuid", "nullable": true }, "ip_restrictions": { "type": "array", "items": { "type": "string" }, "example": [ "192.0.2.0/24", "2001:db8::/32" ], "x-stainless-collection-type": "set" }, "last_modified": { "description": "Deprecated, use `modified_at` instead. End of life: November 1, 2026.", "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "deprecated": true, "readOnly": true, "x-stainless-deprecation-message": "Use `modified_at` instead." }, "lookback_hops": { "type": "integer", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "modified_at": { "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "readOnly": true }, "o365_tenant_id": { "type": "string", "nullable": true }, "regions": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_Region" }, "x-stainless-collection-type": "set" }, "require_tls_inbound": { "type": "boolean", "nullable": true, "x-stainless-terraform-configurability": "computed_optional" }, "require_tls_outbound": { "type": "boolean", "nullable": true, "x-stainless-terraform-configurability": "computed_optional" }, "spf_status": { "$ref": "#/components/schemas/email-security_SpfStatus" }, "status": { "$ref": "#/components/schemas/email-security_DomainStatus" }, "transport": { "type": "string", "x-auditable": true } } }, "email-security_DomainAuthorization": { "type": "object", "properties": { "authorized": { "type": "boolean" }, "status_message": { "type": "string", "nullable": true }, "timestamp": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "authorized", "timestamp" ] }, "email-security_DomainId": { "description": "Domain identifier.", "type": "string", "format": "uuid", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "x-auditable": true }, "email-security_DomainList": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_Domain" } }, "email-security_DomainStatus": { "type": "string", "enum": [ "PENDING", "ACTIVE", "FAILED", "TIMEOUT", null ], "nullable": true }, "email-security_DomainVerificationInfo": { "type": "object", "properties": { "last_checked_at": { "description": "When the last DNS TXT check was attempted, if any.", "type": "string", "format": "date-time", "nullable": true }, "status": { "$ref": "#/components/schemas/email-security_DomainStatus" }, "txt_record_name": { "description": "Full DNS TXT record name (e.g. `_cf-email-sec-challenge.example.com`).", "type": "string" }, "txt_record_value": { "description": "Token value to publish in the TXT record.", "type": "string" } }, "required": [ "status" ] }, "email-security_EmailsProcessed": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time", "readOnly": true }, "total_emails_processed": { "type": "integer", "minimum": 0 }, "total_emails_processed_previous": { "type": "integer", "minimum": 0 } }, "required": [ "total_emails_processed", "total_emails_processed_previous", "timestamp" ] }, "email-security_Finding": { "description": "A single detection finding for a message.", "type": "object", "properties": { "attachment": { "type": "string", "nullable": true }, "detail": { "type": "string", "nullable": true }, "detection": { "description": "Detection result associated with this finding.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/email-security_DispositionLabel" } ], "nullable": true }, "field": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "portion": { "type": "string", "nullable": true }, "reason": { "type": "string", "nullable": true }, "score": { "type": "number", "format": "double", "nullable": true }, "value": { "type": "string", "nullable": true } } }, "email-security_ImpersonationRegistry": { "description": "An impersonation registry entry.", "type": "object", "properties": { "comments": { "type": "string", "nullable": true }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "readOnly": true }, "directory_id": { "type": "integer", "nullable": true }, "directory_node_id": { "type": "integer", "nullable": true }, "email": { "type": "string", "example": "john.doe@example.com", "x-auditable": true }, "external_directory_node_id": { "type": "string", "deprecated": true, "nullable": true, "x-stainless-deprecation-message": "This field is deprecated." }, "id": { "allOf": [ { "$ref": "#/components/schemas/email-security_ImpersonationRegistryId" } ], "readOnly": true }, "is_email_regex": { "type": "boolean", "example": false, "x-auditable": true }, "last_modified": { "description": "Deprecated, use `modified_at` instead. End of life: November 1, 2026.", "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "deprecated": true, "readOnly": true, "x-stainless-deprecation-message": "Use `modified_at` instead." }, "modified_at": { "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "readOnly": true }, "name": { "type": "string", "example": "John Doe", "maxLength": 1024, "x-auditable": true }, "provenance": { "$ref": "#/components/schemas/email-security_Provenance" } } }, "email-security_ImpersonationRegistryId": { "description": "Impersonation registry entry identifier.", "type": "string", "format": "uuid", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "title": "identifier", "x-auditable": true }, "email-security_ImpersonationRegistryList": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_ImpersonationRegistry" } }, "email-security_InvestigateId": { "description": "Unique identifier for a message retrieved from investigation.", "type": "string", "example": "4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678" }, "email-security_Link": { "type": "object", "properties": { "href": { "type": "string" }, "text": { "type": "string", "nullable": true } }, "required": [ "href" ] }, "email-security_MailboxDestination": { "type": "string", "enum": [ "Inbox", "JunkEmail", "DeletedItems", "RecoverableItemsDeletions", "RecoverableItemsPurges" ] }, "email-security_MessageDeliveryMode": { "type": "string", "enum": [ "DIRECT", "BCC", "JOURNAL", "REVIEW_SUBMISSION", "DMARC_UNVERIFIED", "DMARC_FAILURE_REPORT", "DMARC_AGGREGATE_REPORT", "THREAT_INTEL_SUBMISSION", "SIMULATION_SUBMISSION", "API", "RETRO_SCAN" ] }, "email-security_MessageDeliveryStatus": { "description": "Delivery status of the message.", "type": "string", "enum": [ "delivered", "moved", "quarantined", "rejected", "deferred", "bounced", "queued", "move_failed" ] }, "email-security_MessageDetails": { "type": "object", "properties": { "action_log": { "description": "Deprecated, use `GET /investigate/{investigate_id}/action_log` instead. End of life: November 1, 2026.", "type": "array", "items": { "$ref": "#/components/schemas/email-security_ActionLogEntry" }, "deprecated": true, "x-stainless-deprecation-message": "Use GET /investigate/{investigate_id}/action_log instead." }, "alert_id": { "type": "string", "nullable": true }, "client_recipients": { "type": "array", "items": { "type": "string" } }, "delivery_mode": { "$ref": "#/components/schemas/email-security_MessageDeliveryMode" }, "delivery_status": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_MessageDeliveryStatus" }, "nullable": true }, "detection_reasons": { "type": "array", "items": { "type": "string" } }, "edf_hash": { "type": "string", "nullable": true }, "envelope_from": { "type": "string", "nullable": true }, "envelope_to": { "type": "array", "items": { "type": "string" }, "nullable": true }, "final_disposition": { "$ref": "#/components/schemas/email-security_DispositionLabel" }, "findings": { "description": "Deprecated, use the `findings` field from `GET /investigate/{investigate_id}/detections` instead. End of life: November 1, 2026. Detection findings for this message.", "type": "array", "items": { "properties": { "attachment": { "type": "string", "nullable": true }, "detail": { "type": "string", "nullable": true }, "detection": { "$ref": "#/components/schemas/email-security_DispositionLabel" }, "field": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "portion": { "type": "string", "nullable": true }, "reason": { "type": "string", "nullable": true }, "score": { "type": "number", "format": "double", "nullable": true }, "value": { "type": "string", "nullable": true } }, "type": "object" }, "deprecated": true, "nullable": true, "x-stainless-deprecation-message": "Use the `findings` field from GET /investigate/{investigate_id}/detections instead." }, "from": { "type": "string", "nullable": true }, "from_name": { "type": "string", "nullable": true }, "htmltext_structure_hash": { "type": "string", "nullable": true }, "id": { "allOf": [ { "$ref": "#/components/schemas/email-security_InvestigateId" } ], "x-auditable": true }, "is_phish_submission": { "type": "boolean" }, "is_quarantined": { "type": "boolean" }, "message_id": { "type": "string", "nullable": true }, "post_delivery_operations": { "description": "Post-delivery operations performed on this message.", "type": "array", "items": { "enum": [ "PREVIEW", "QUARANTINE_RELEASE", "SUBMISSION", "MOVE" ], "type": "string" }, "nullable": true }, "postfix_id": { "$ref": "#/components/schemas/email-security_PostfixId" }, "postfix_id_outbound": { "type": "string", "nullable": true }, "properties": { "description": "Message processing properties.", "type": "object", "properties": { "allowlisted_pattern": { "description": "Pattern that allowlisted this message.", "nullable": true, "type": "string" }, "allowlisted_pattern_type": { "description": "Type of allowlist pattern.", "enum": [ "quarantine_release", "acceptable_sender", "allowed_sender", "allowed_recipient", "domain_similarity", "domain_recency", "managed_acceptable_sender", "outbound_ndr" ], "nullable": true, "type": "string" }, "blocklisted_message": { "description": "Whether message was blocklisted.", "nullable": true, "type": "boolean" }, "blocklisted_pattern": { "description": "Pattern that blocklisted this message.", "nullable": true, "type": "string" }, "whitelisted_pattern_type": { "description": "Legacy field for allowlist pattern type.", "enum": [ "quarantine_release", "acceptable_sender", "allowed_sender", "allowed_recipient", "domain_similarity", "domain_recency", "managed_acceptable_sender", "outbound_ndr" ], "nullable": true, "type": "string" } } }, "replyto": { "type": "string", "nullable": true }, "scanned_at": { "description": "When the message was scanned (UTC).", "type": "string", "format": "date-time", "nullable": true }, "sent_at": { "description": "When the message was sent (UTC).", "type": "string", "format": "date-time", "nullable": true }, "sent_date": { "type": "string", "nullable": true }, "smtp_helo_server_ip": { "type": "string", "nullable": true }, "smtp_previous_hop_ip": { "type": "string", "nullable": true }, "subject": { "type": "string", "nullable": true }, "threat_categories": { "type": "array", "items": { "type": "string" }, "nullable": true }, "to": { "type": "array", "items": { "type": "string" }, "nullable": true }, "to_name": { "type": "array", "items": { "type": "string" }, "nullable": true }, "ts": { "description": "Deprecated, use `scanned_at` instead. End of life: November 1, 2026.", "type": "string", "deprecated": true, "readOnly": true, "x-stainless-deprecation-message": "Use `scanned_at` instead." }, "validation": { "$ref": "#/components/schemas/email-security_Validation" }, "x_originating_ip": { "type": "string", "nullable": true } }, "required": [ "id", "ts", "client_recipients", "postfix_id", "detection_reasons", "action_log", "is_quarantined", "is_phish_submission", "properties" ] }, "email-security_MessageDetectionDetails": { "type": "object", "properties": { "action": { "type": "string" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_Attachment" } }, "final_disposition": { "$ref": "#/components/schemas/email-security_DispositionLabel" }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_Finding" }, "nullable": true }, "headers": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_MessageHeader" } }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_Link" } }, "sender_info": { "type": "object", "properties": { "as_name": { "description": "The name of the autonomous system.", "type": "string", "nullable": true }, "as_number": { "description": "The number of the autonomous system.", "type": "integer", "nullable": true }, "geo": { "type": "string", "nullable": true }, "ip": { "type": "string", "nullable": true }, "pld": { "type": "string", "nullable": true } } }, "threat_categories": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_ThreatCategory" } }, "validation": { "$ref": "#/components/schemas/email-security_Validation" } }, "required": [ "validation", "headers", "threat_categories", "sender_info", "links", "action", "attachments", "findings" ] }, "email-security_MessageHeader": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ] }, "email-security_MessagePreview": { "type": "object", "properties": { "screenshot": { "description": "A base64 encoded PNG image of the email.", "type": "string" } }, "required": [ "screenshot" ] }, "email-security_MessageRaw": { "type": "object", "properties": { "raw": { "description": "A UTF-8 encoded eml file of the email.", "type": "string" } }, "required": [ "raw" ] }, "email-security_MessageTrace": { "type": "object", "properties": { "inbound": { "type": "object", "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_TraceLine" }, "nullable": true }, "pending": { "type": "boolean", "nullable": true } } }, "outbound": { "type": "object", "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_TraceLine" }, "nullable": true }, "pending": { "type": "boolean", "nullable": true } } } }, "required": [ "inbound", "outbound" ] }, "email-security_MoveResponseItem": { "type": "object", "properties": { "completed_at": { "description": "When the move operation completed (UTC).", "type": "string", "format": "date-time", "nullable": true }, "completed_timestamp": { "description": "Deprecated, use `completed_at` instead. End of life: November 1, 2026.", "type": "string", "format": "date-time", "deprecated": true, "x-stainless-deprecation-message": "Use `completed_at` instead." }, "destination": { "description": "Destination folder for the message.", "type": "string", "nullable": true }, "item_count": { "description": "Number of items moved. End of life: November 1, 2026.", "type": "integer", "deprecated": true, "x-stainless-deprecation-message": "This field is deprecated." }, "message_id": { "description": "Message identifier.", "type": "string", "nullable": true }, "operation": { "description": "Type of operation performed.", "type": "string", "nullable": true }, "recipient": { "description": "Recipient email address.", "type": "string", "nullable": true }, "status": { "description": "Operation status.", "type": "string", "nullable": true }, "success": { "description": "Whether the operation succeeded.", "type": "boolean" } }, "required": [ "success" ] }, "email-security_OptionalSubmissionDisposition": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/email-security_SubmissionDisposition" } ], "nullable": true }, "email-security_PatternType": { "description": "Type of pattern matching.\n- EMAIL: matches a full email address (e.g. `user@example.com`)\n- DOMAIN: matches a domain name (e.g. `example.com`)\n- IP: matches a plain IPv4 or IPv6 address (e.g. `1.2.3.4` or `2606:4700:4700::1111`) or CIDR block (e.g. `1.2.3.0/24` or `2606:4700:4700::/48`). The API rejects private or unique-local, loopback, link-local, unspecified, and IPv4 broadcast addresses, including their IPv4-mapped IPv6 equivalents.\n- UNKNOWN: deprecated; you cannot use this when creating or updating policies, but it may appear on existing entries.\n", "type": "string", "example": "EMAIL", "enum": [ "EMAIL", "DOMAIN", "IP", "UNKNOWN" ], "x-auditable": true }, "email-security_PhishGuardReport": { "type": "object", "properties": { "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "disposition": { "$ref": "#/components/schemas/email-security_DispositionLabel" }, "fields": { "type": "object", "properties": { "from": { "type": "string", "nullable": true }, "occurred_at": { "type": "string", "format": "date-time", "readOnly": true }, "postfix_id": { "type": "string", "nullable": true }, "to": { "type": "array", "items": { "type": "string" } }, "ts": { "description": "Deprecated, use `occurred_at` instead.", "type": "string", "format": "date-time", "deprecated": true, "readOnly": true, "x-stainless-deprecation-message": "Use `occurred_at` instead." } }, "required": [ "to" ] }, "id": { "type": "integer" }, "priority": { "type": "string" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_PhishGuardReportTag" }, "nullable": true }, "title": { "type": "string" }, "ts": { "description": "Deprecated, use `created_at` instead.", "type": "string", "format": "date-time", "deprecated": true, "readOnly": true, "x-stainless-deprecation-message": "Use `created_at` instead." }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true } }, "required": [ "id", "title", "content", "fields", "priority", "disposition" ] }, "email-security_PhishGuardReportTag": { "type": "object", "properties": { "category": { "type": "string" }, "value": { "type": "string" } }, "required": [ "category", "value" ] }, "email-security_PostfixId": { "description": "The identifier of the message.", "type": "string", "example": "4Njp3P0STMz2c02Q" }, "email-security_Provenance": { "type": "string", "enum": [ "A1S_INTERNAL", "SNOOPY-CASB_OFFICE_365", "SNOOPY-OFFICE_365", "SNOOPY-GOOGLE_DIRECTORY" ] }, "email-security_ReclassifyRequest": { "type": "object", "properties": { "eml_content": { "description": "Base64 encoded content of the EML file.", "type": "string" }, "escalated_submission_id": { "type": "string", "x-auditable": true }, "expected_disposition": { "type": "string", "enum": [ "NONE", "BULK", "MALICIOUS", "SPAM", "SPOOF", "SUSPICIOUS" ] } }, "required": [ "expected_disposition" ] }, "email-security_Region": { "type": "string", "enum": [ "GLOBAL", "AU", "DE", "IN", "US" ] }, "email-security_ReleaseResponse": { "type": "object", "properties": { "delivered": { "type": "array", "items": { "type": "string" }, "nullable": true }, "failed": { "type": "array", "items": { "type": "string" }, "nullable": true }, "id": { "allOf": [ { "$ref": "#/components/schemas/email-security_InvestigateId" } ], "x-auditable": true }, "postfix_id": { "description": "Deprecated, use `id` instead. End of life: November 1, 2026.", "allOf": [ { "$ref": "#/components/schemas/email-security_PostfixId" } ], "deprecated": true, "x-stainless-deprecation-message": "Use `id` instead." }, "undelivered": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "required": [ "id" ] }, "email-security_ReplaceDomain": { "description": "Request body for replacing an email domain. The `domain` field is intentionally\nabsent — the domain name is immutable after creation.\n", "type": "object", "properties": { "allowed_delivery_modes": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_DeliveryMode" }, "maxItems": 10, "minItems": 1, "x-stainless-collection-type": "set" }, "drop_dispositions": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_DispositionLabel" }, "maxItems": 10, "x-stainless-collection-type": "set" }, "folder": { "allOf": [ { "$ref": "#/components/schemas/email-security_ScannableFolder" } ], "x-stainless-terraform-configurability": "computed_optional" }, "integration_id": { "type": "string", "format": "uuid", "nullable": true, "x-auditable": true }, "ip_restrictions": { "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "192.0.2.0/24", "2001:db8::/32" ], "maxItems": 100, "x-stainless-collection-type": "set" }, "lookback_hops": { "type": "integer", "maximum": 20, "minimum": 1, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "regions": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_Region" }, "maxItems": 10, "minItems": 1, "x-stainless-collection-type": "set" }, "require_tls_inbound": { "type": "boolean", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "require_tls_outbound": { "type": "boolean", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "transport": { "type": "string", "nullable": true, "x-auditable": true } }, "required": [ "allowed_delivery_modes", "ip_restrictions", "drop_dispositions", "regions" ] }, "email-security_ScannableFolder": { "type": "string", "enum": [ "AllItems", "Inbox", null ], "nullable": true }, "email-security_SendingDomainRestriction": { "description": "A sending domain restriction that enforces TLS (Transport Layer Security) requirements for emails from specific domains. If TLS is required, the system drops mail without TLS from the specified domain.", "type": "object", "properties": { "comments": { "type": "string", "example": "Enforce TLS for all mail from this domain", "maxLength": 1024, "nullable": true }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "readOnly": true }, "domain": { "description": "Domain that requires TLS enforcement.", "type": "string", "example": "example.com", "x-auditable": true }, "exclude": { "description": "Subdomains to exempt from TLS requirements.", "type": "array", "items": { "type": "string" }, "example": [ "subdomain.example.com" ], "x-auditable": true }, "id": { "allOf": [ { "$ref": "#/components/schemas/email-security_SendingDomainRestrictionId" } ], "readOnly": true }, "last_modified": { "description": "Deprecated, use `modified_at` instead. End of life: November 1, 2026.", "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "deprecated": true, "readOnly": true, "x-stainless-deprecation-message": "Use `modified_at` instead." }, "modified_at": { "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "readOnly": true } } }, "email-security_SendingDomainRestrictionId": { "description": "Sending domain restriction identifier.", "type": "string", "format": "uuid", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "title": "identifier", "x-auditable": true }, "email-security_SendingDomainRestrictionList": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_SendingDomainRestriction" } }, "email-security_SpfStatus": { "type": "string", "enum": [ "none", "good", "neutral", "open", "invalid", null ], "nullable": true }, "email-security_Submission": { "type": "object", "properties": { "customer_status": { "$ref": "#/components/schemas/email-security_CustomerStatus" }, "escalated_as": { "$ref": "#/components/schemas/email-security_OptionalSubmissionDisposition" }, "escalated_at": { "type": "string", "format": "date-time", "nullable": true }, "escalated_by": { "type": "string", "nullable": true }, "escalated_submission_id": { "type": "string", "nullable": true }, "original_disposition": { "$ref": "#/components/schemas/email-security_OptionalSubmissionDisposition" }, "original_edf_hash": { "type": "string", "nullable": true }, "original_postfix_id": { "description": "The postfix ID of the original message that was submitted.", "type": "string", "nullable": true }, "outcome": { "type": "string", "nullable": true }, "outcome_disposition": { "$ref": "#/components/schemas/email-security_OptionalSubmissionDisposition" }, "requested_at": { "description": "When the submission was requested (UTC).", "type": "string", "format": "date-time" }, "requested_by": { "type": "string", "nullable": true }, "requested_disposition": { "$ref": "#/components/schemas/email-security_OptionalSubmissionDisposition" }, "requested_ts": { "description": "Deprecated, use `requested_at` instead.", "type": "string", "deprecated": true, "readOnly": true, "x-stainless-deprecation-message": "Use `requested_at` instead." }, "status": { "type": "string", "nullable": true }, "subject": { "type": "string", "nullable": true }, "submission_id": { "type": "string", "x-auditable": true }, "type": { "description": "Indicates whether a team member or an end user created the submission.", "type": "string", "enum": [ "Team", "User" ], "nullable": true } }, "required": [ "submission_id", "requested_at" ] }, "email-security_SubmissionDisposition": { "type": "string", "enum": [ "MALICIOUS", "SUSPICIOUS", "SPOOF", "SPAM", "BULK", "NONE" ] }, "email-security_ThreatCategory": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "id": { "type": "integer" }, "name": { "type": "string", "nullable": true } } }, "email-security_TraceLine": { "type": "object", "properties": { "lineno": { "description": "Line number in the trace log.", "type": "integer" }, "logged_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "message": { "type": "string" }, "ts": { "description": "Deprecated, use `logged_at` instead. End of life: November 1, 2026.", "type": "string", "deprecated": true, "readOnly": true, "x-stainless-deprecation-message": "Use `logged_at` instead." } } }, "email-security_TrustedDomain": { "description": "A trusted email domain.", "type": "object", "properties": { "comments": { "type": "string", "example": "Trusted partner domain", "maxLength": 1024, "nullable": true }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "readOnly": true }, "id": { "allOf": [ { "$ref": "#/components/schemas/email-security_TrustedDomainId" } ], "readOnly": true }, "is_recent": { "description": "Select to prevent recently registered domains from triggering a Suspicious or Malicious disposition.", "type": "boolean", "example": true, "x-auditable": true }, "is_regex": { "type": "boolean", "example": false, "x-auditable": true }, "is_similarity": { "description": "Select for partner or other approved domains that have similar spelling to your connected domains. Prevents listed domains from triggering a Spoof disposition.", "type": "boolean", "example": false, "x-auditable": true }, "last_modified": { "description": "Deprecated, use `modified_at` instead. End of life: November 1, 2026.", "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "deprecated": true, "readOnly": true, "x-stainless-deprecation-message": "Use `modified_at` instead." }, "modified_at": { "allOf": [ { "$ref": "#/components/schemas/email-security_timestamp" } ], "readOnly": true }, "pattern": { "type": "string", "example": "example.com", "maxLength": 1024, "minLength": 1, "x-auditable": true } } }, "email-security_TrustedDomainId": { "description": "Trusted domain identifier.", "type": "string", "format": "uuid", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "x-auditable": true }, "email-security_TrustedDomainList": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_TrustedDomain" } }, "email-security_UpdateAllowPolicy": { "description": "Update an allow policy.", "allOf": [ { "$ref": "#/components/schemas/email-security_AllowPolicy" } ], "minProperties": 1 }, "email-security_UpdateBlockedSender": { "description": "Update a blocked sender pattern.", "allOf": [ { "$ref": "#/components/schemas/email-security_BlockedSender" } ], "minProperties": 1 }, "email-security_UpdateContentPolicy": { "description": "Update a content policy.", "allOf": [ { "$ref": "#/components/schemas/email-security_ContentPolicy" } ], "minProperties": 1 }, "email-security_UpdateDomain": { "type": "object", "properties": { "allowed_delivery_modes": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_DeliveryMode" }, "x-stainless-collection-type": "set" }, "drop_dispositions": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_DispositionLabel" }, "x-stainless-collection-type": "set" }, "folder": { "allOf": [ { "$ref": "#/components/schemas/email-security_ScannableFolder" } ], "x-stainless-terraform-configurability": "computed_optional" }, "integration_id": { "type": "string", "format": "uuid", "nullable": true, "x-auditable": true }, "ip_restrictions": { "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "192.0.2.0/24", "2001:db8::/32" ], "x-stainless-collection-type": "set" }, "lookback_hops": { "type": "integer", "maximum": 20, "minimum": 1, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "regions": { "type": "array", "items": { "$ref": "#/components/schemas/email-security_Region" }, "x-stainless-collection-type": "set" }, "require_tls_inbound": { "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "require_tls_outbound": { "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "transport": { "type": "string", "x-auditable": true } } }, "email-security_UpdateImpersonationRegistry": { "description": "Update an impersonation registry entry.", "allOf": [ { "$ref": "#/components/schemas/email-security_ImpersonationRegistry" } ], "minProperties": 1 }, "email-security_UpdateSendingDomainRestriction": { "description": "Update a sending domain restriction.", "allOf": [ { "$ref": "#/components/schemas/email-security_SendingDomainRestriction" } ], "minProperties": 1 }, "email-security_UpdateTrustedDomain": { "description": "Update a trusted domain.", "allOf": [ { "$ref": "#/components/schemas/email-security_TrustedDomain" } ], "minProperties": 1 }, "email-security_UpdateUrlIgnorePattern": { "description": "Updates a URL rewrite ignore pattern; modifies only the provided fields.", "type": "object", "properties": { "comments": { "description": "Optional note describing the reason for the ignore pattern.", "type": "string", "example": "Trusted internal redirect service", "maxLength": 1024, "nullable": true, "x-auditable": true }, "pattern": { "description": "Regular expression identifying URLs to exempt from rewriting.", "type": "string", "example": "https://example\\.com/.*", "maxLength": 1024, "minLength": 1, "x-auditable": true } }, "additionalProperties": false, "minProperties": 1 }, "email-security_UrlIgnorePattern": { "description": "A URL ignore pattern that exempts matching URLs from Email Security's URL rewriting.", "type": "object", "properties": { "comments": { "description": "Optional note describing the reason for the ignore pattern.", "type": "string", "example": "Trusted internal redirect service", "maxLength": 1024, "nullable": true, "x-auditable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "x-auditable": true }, "id": { "allOf": [ { "$ref": "#/components/schemas/email-security_UrlIgnorePatternId" } ], "readOnly": true }, "last_modified": { "description": "Deprecated, use `modified_at` instead. End of life: November 1, 2026.", "type": "string", "format": "date-time", "deprecated": true, "readOnly": true, "x-auditable": true, "x-stainless-deprecation-message": "Use `modified_at` instead." }, "modified_at": { "type": "string", "format": "date-time", "readOnly": true, "x-auditable": true }, "pattern": { "description": "Regular expression identifying URLs to exempt from rewriting.", "type": "string", "example": "https://example\\.com/.*", "maxLength": 1024, "minLength": 1, "x-auditable": true } }, "required": [ "id", "created_at", "pattern" ] }, "email-security_UrlIgnorePatternId": { "description": "URL ignore pattern identifier.", "type": "string", "format": "uuid", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "title": "identifier", "x-auditable": true }, "email-security_Validation": { "type": "object", "properties": { "comment": { "type": "string", "nullable": true }, "dkim": { "$ref": "#/components/schemas/email-security_ValidationStatus" }, "dmarc": { "$ref": "#/components/schemas/email-security_ValidationStatus" }, "spf": { "$ref": "#/components/schemas/email-security_ValidationStatus" } } }, "email-security_ValidationStatus": { "type": "string", "enum": [ "pass", "neutral", "fail", "error", "none" ] }, "email-security_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/email-security_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 } } } }, "type": "object" } ] }, "email-security_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/email-security_messages" }, "messages": { "$ref": "#/components/schemas/email-security_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "email-security_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/email-security_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/email-security_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "email-security_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/email-security_api-response-common" } ] }, "email-security_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "email-security_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "email-security_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "x-auditable": true }, "email-sending_EmailAddressObject": { "type": "object", "properties": { "address": { "description": "Email address (e.g., 'user@example.com').", "type": "string", "example": "user@example.com", "pattern": "^[\\x20-\\x7E]+$" }, "name": { "description": "Display name for the email address (e.g., 'John Doe'). Optional; set to null or leave it unset to send the address on its own.", "type": "string", "example": "John Doe", "nullable": true } }, "example": { "address": "user@example.com", "name": "John Doe" }, "required": [ "address" ] }, "email-sending_EmailAddressString": { "description": "An email address as a plain string.", "type": "string", "example": "user@example.com", "pattern": "^[\\x20-\\x7E]+$" }, "email-sending_EmailApiError": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "email-sending_EmailAttachment": { "type": "object", "properties": { "content": { "description": "Base64-encoded content of the attachment.", "example": "JVBERi0xLjQK...", "type": "string" }, "disposition": { "description": "Use 'attachment' for a standard file attachment.", "type": "string", "enum": [ "attachment" ] }, "filename": { "description": "Filename for the attachment.", "type": "string", "example": "report.pdf" }, "type": { "description": "MIME type of the attachment (e.g., 'application/pdf', 'text/plain').", "type": "string", "example": "application/pdf" } }, "example": { "content": "JVBERi0xLjQK...", "disposition": "attachment", "filename": "report.pdf", "type": "application/pdf" }, "required": [ "disposition", "filename", "type", "content" ] }, "email-sending_EmailBuilder": { "type": "object", "properties": { "attachments": { "description": "File attachments and inline images.", "type": "array", "items": { "discriminator": { "mapping": { "attachment": "#/components/schemas/email-sending_EmailAttachment", "inline": "#/components/schemas/email-sending_EmailInlineAttachment" }, "propertyName": "disposition" }, "oneOf": [ { "$ref": "#/components/schemas/email-sending_EmailInlineAttachment" }, { "$ref": "#/components/schemas/email-sending_EmailAttachment" } ] }, "example": [ { "content": "JVBERi0xLjQK...", "disposition": "attachment", "filename": "report.pdf", "type": "application/pdf" } ] }, "bcc": { "description": "Blind carbon copy recipient(s). Optional. A single email string, a named address object, or an array of either.", "example": [ "bcc-recipient@example.com" ], "oneOf": [ { "$ref": "#/components/schemas/email-sending_EmailAddressString" }, { "$ref": "#/components/schemas/email-sending_EmailAddressObject" }, { "items": { "oneOf": [ { "$ref": "#/components/schemas/email-sending_EmailAddressString" }, { "$ref": "#/components/schemas/email-sending_EmailAddressObject" } ] }, "type": "array" } ] }, "cc": { "description": "Carbon copy recipient(s). Optional. A single email string, a named address object, or an array of either.", "example": [ "cc-recipient@example.com" ], "oneOf": [ { "$ref": "#/components/schemas/email-sending_EmailAddressString" }, { "$ref": "#/components/schemas/email-sending_EmailAddressObject" }, { "items": { "oneOf": [ { "$ref": "#/components/schemas/email-sending_EmailAddressString" }, { "$ref": "#/components/schemas/email-sending_EmailAddressObject" } ] }, "type": "array" } ] }, "from": { "description": "Sender email address. Either a plain string or an object with address and name.", "example": "sender@example.com", "oneOf": [ { "$ref": "#/components/schemas/email-sending_EmailAddressString" }, { "$ref": "#/components/schemas/email-sending_EmailAddressObject" } ] }, "headers": { "description": "Custom email headers as key-value pairs.", "type": "object", "example": { "X-Custom-Header": "value" }, "additionalProperties": { "type": "string" } }, "html": { "description": "HTML body of the email. Provide at least one of text or html (non-empty).", "type": "string", "example": "

Hello

Please find your report attached.

" }, "reply_to": { "description": "Reply-to address. Either a plain string or an object with address and name.", "example": "replies@example.com", "oneOf": [ { "$ref": "#/components/schemas/email-sending_EmailAddressString" }, { "$ref": "#/components/schemas/email-sending_EmailAddressObject" } ] }, "subject": { "description": "Email subject line.", "type": "string", "example": "Monthly Report" }, "text": { "description": "Plain text body of the email. Provide at least one of text or html (non-empty).", "type": "string", "example": "Hello\n\nPlease find your report attached." }, "to": { "description": "Recipient(s). Optional if cc or bcc is provided. A single email string, a named address object, or an array of either.", "example": [ "recipient@example.com" ], "oneOf": [ { "$ref": "#/components/schemas/email-sending_EmailAddressString" }, { "$ref": "#/components/schemas/email-sending_EmailAddressObject" }, { "items": { "oneOf": [ { "$ref": "#/components/schemas/email-sending_EmailAddressString" }, { "$ref": "#/components/schemas/email-sending_EmailAddressObject" } ] }, "type": "array" } ] } }, "example": { "attachments": [ { "content": "JVBERi0xLjQK...", "disposition": "attachment", "filename": "report.pdf", "type": "application/pdf" } ], "from": "sender@example.com", "html": "

Hello

Please find your report attached.

", "subject": "Monthly Report", "text": "Hello\n\nPlease find your report attached.", "to": [ "recipient@example.com" ] }, "additionalProperties": false, "required": [ "from", "subject" ] }, "email-sending_EmailInlineAttachment": { "type": "object", "properties": { "content": { "description": "Base64-encoded content of the attachment.", "example": "iVBORw0KGgoAAAANSUhEUgAA...", "type": "string" }, "content_id": { "description": "Content ID used to reference this attachment in HTML via cid: URI (e.g., ).", "type": "string", "example": "logo" }, "disposition": { "description": "Use 'inline' to embed the attachment in the email body.", "type": "string", "enum": [ "inline" ] }, "filename": { "description": "Filename for the attachment.", "type": "string", "example": "logo.png" }, "type": { "description": "MIME type of the attachment (e.g., 'image/png', 'text/plain').", "type": "string", "example": "image/png" } }, "example": { "content": "iVBORw0KGgoAAAANSUhEUgAA...", "content_id": "logo", "disposition": "inline", "filename": "logo.png", "type": "image/png" }, "required": [ "disposition", "content_id", "filename", "type", "content" ] }, "email-sending_EmailSendResponse": { "type": "object", "properties": { "delivered": { "description": "Email addresses to which the message was delivered immediately.", "type": "array", "items": { "pattern": "^[\\x20-\\x7E]+$", "type": "string" }, "example": [ "recipient@example.com" ] }, "message_id": { "description": "Message ID of the sent email.", "type": "string", "example": "", "pattern": "^[\\x20-\\x7E]+$" }, "permanent_bounces": { "description": "Email addresses that permanently bounced.", "type": "array", "items": { "pattern": "^[\\x20-\\x7E]+$", "type": "string" }, "example": [] }, "queued": { "description": "Email addresses for which delivery was queued for later.", "type": "array", "items": { "pattern": "^[\\x20-\\x7E]+$", "type": "string" }, "example": [] }, "suppressed_recipients": { "description": "Email addresses dropped because they are on the suppression list. Returned when suppressed-recipient dropping is enabled for the sending subdomain; otherwise the request fails instead.", "type": "array", "items": { "pattern": "^[\\x20-\\x7E]+$", "type": "string" }, "example": [] } }, "example": { "delivered": [ "recipient@example.com" ], "message_id": "", "permanent_bounces": [], "queued": [], "suppressed_recipients": [] }, "required": [ "message_id", "delivered", "queued", "permanent_bounces", "suppressed_recipients" ] }, "email-sending_SendRawRequest": { "type": "object", "properties": { "from": { "description": "Sender email address.", "type": "string", "example": "sender@example.com", "pattern": "^[\\x20-\\x7E]+$" }, "mime_message": { "description": "The full MIME-encoded email message. Should include standard RFC 5322 headers such as From, To, Subject, and Content-Type. The from and recipients fields in the request body control SMTP envelope routing; the From and To headers in the MIME message control what the recipient's email client displays.", "type": "string", "example": "From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: Hello\r\nContent-Type: text/plain\r\n\r\nHello, World!" }, "recipients": { "description": "List of recipient email addresses.", "type": "array", "items": { "pattern": "^[\\x20-\\x7E]+$", "type": "string" }, "example": [ "recipient@example.com" ] } }, "example": { "from": "sender@example.com", "mime_message": "From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: Hello\r\nContent-Type: text/plain\r\n\r\nHello, World!", "recipients": [ "recipient@example.com" ] }, "additionalProperties": false, "required": [ "from", "recipients", "mime_message" ] }, "email_ReputationPolicy": { "type": "object", "properties": { "complaint": { "$ref": "#/components/schemas/email_ReputationThreshold" }, "customer_bounce": { "$ref": "#/components/schemas/email_ReputationThreshold" }, "spam_rejection": { "$ref": "#/components/schemas/email_ReputationThreshold" }, "suspension_after_hours": { "description": "The grace period before suspension. The value must be a whole number of days.", "type": "integer", "format": "int64", "example": 168, "minimum": 24, "multipleOf": 24 } }, "additionalProperties": false, "required": [ "customer_bounce", "complaint", "spam_rejection", "suspension_after_hours" ] }, "email_ReputationThreshold": { "type": "object", "properties": { "at_risk_at": { "type": "number", "format": "double" }, "minimum_denominator": { "type": "integer", "format": "int64" }, "warning_at": { "type": "number", "format": "double" } }, "additionalProperties": false, "required": [ "warning_at", "at_risk_at", "minimum_denominator" ] }, "email_account_id": { "$ref": "#/components/schemas/email_identifier" }, "email_account_rule": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/email_rule_properties" }, { "properties": { "zone": { "description": "Zone information for the routing rule.", "type": "object", "properties": { "name": { "description": "Zone name.", "type": "string", "example": "example.com", "readOnly": true }, "tag": { "description": "Zone tag.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true } } } } } ] }, "email_account_rules_plan": { "type": "object", "properties": { "zones": { "type": "array", "items": { "$ref": "#/components/schemas/email_account_rules_plan_zone" } } }, "example": { "zones": [ { "changes": [ { "target": "support@example.com", "type": "added" }, { "remote": { "actions": [ { "type": "worker", "value": [ "my-worker" ] } ], "enabled": false, "id": "f1e2d3c4b5a6978869708192a3b4c5d6", "matchers": [ { "field": "to", "type": "literal", "value": "info@example.com" } ], "source": "wrangler" }, "target": "info@example.com", "type": "updated" }, { "remote": { "actions": [ { "type": "worker", "value": [ "my-worker" ] } ], "enabled": true, "id": "0a1b2c3d4e5f60718293a4b5c6d7e8f9", "matchers": [ { "field": "to", "type": "literal", "value": "old@example.com" } ], "source": "wrangler" }, "target": "old@example.com", "type": "deleted" }, { "remote": { "actions": [ { "type": "forward", "value": [ "billing-team@example.net" ] } ], "enabled": true, "id": "9f8e7d6c5b4a39281706f5e4d3c2b1a0", "matchers": [ { "field": "to", "type": "literal", "value": "billing@example.com" } ], "source": "api" }, "target": "billing@example.com", "type": "conflict" }, { "remote": { "actions": [ { "type": "worker", "value": [ "other-worker" ] } ], "enabled": true, "id": "3c4d5e6f70819203a4b5c6d7e8f90a1b", "matchers": [ { "type": "all" } ], "owner_worker_name": "other-worker", "source": "wrangler" }, "target": "*@example.com", "type": "conflict" } ], "zone_id": "023e105f4ecef8ad9ca31a8372d0c353", "zone_name": "example.com" } ] } }, "email_account_rules_plan_catch_all_entry": { "type": "object", "properties": { "rule": { "$ref": "#/components/schemas/email_account_rules_plan_catch_all_rule" }, "target": { "description": "Catch-all target to plan for, using the `*@domain` shape.", "type": "string", "example": "*@example.com" } }, "required": [ "target", "rule" ] }, "email_account_rules_plan_catch_all_rule": { "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/email_rule_catchall-actions" }, "enabled": { "$ref": "#/components/schemas/email_rule_enabled" }, "matchers": { "$ref": "#/components/schemas/email_rule_catchall-matchers" } }, "required": [ "actions", "matchers" ] }, "email_account_rules_plan_change": { "type": "object", "properties": { "remote": { "$ref": "#/components/schemas/email_account_rules_plan_remote_rule" }, "target": { "description": "Canonical recipient address or catch-all target.", "type": "string", "example": "support@example.com" }, "type": { "description": "Planned change type.", "type": "string", "example": "added", "enum": [ "added", "updated", "deleted", "conflict" ] } } }, "email_account_rules_plan_remote_rule": { "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/email_rule_actions" }, "enabled": { "$ref": "#/components/schemas/email_rule_enabled" }, "id": { "$ref": "#/components/schemas/email_rule_identifier" }, "matchers": { "$ref": "#/components/schemas/email_rule_matchers" }, "owner_worker_name": { "description": "Name of the Wrangler-owned Worker that owns the remote rule, when available for display.", "type": "string", "example": "email-processor" }, "source": { "$ref": "#/components/schemas/email_rule_source" } } }, "email_account_rules_plan_request": { "type": "object", "properties": { "catch_all_rules": { "description": "Desired catch-all Email Routing rules managed by the deploying Worker.", "type": "array", "items": { "$ref": "#/components/schemas/email_account_rules_plan_catch_all_entry" } }, "owner_worker_tag": { "$ref": "#/components/schemas/email_rule_owner_worker_tag" }, "rules": { "description": "Desired normal Email Routing rules managed by the deploying Worker.", "type": "array", "items": { "$ref": "#/components/schemas/email_account_rules_plan_rule" } } }, "example": { "catch_all_rules": [ { "rule": { "actions": [ { "type": "worker", "value": [ "my-worker" ] } ], "matchers": [ { "type": "all" } ] }, "target": "*@example.com" } ], "owner_worker_tag": "a7e6fb77503c41d8a7f3113c6918f10c", "rules": [ { "actions": [ { "type": "worker", "value": [ "my-worker" ] } ], "matchers": [ { "field": "to", "type": "literal", "value": "support@example.com" } ] }, { "actions": [ { "type": "worker", "value": [ "my-worker" ] } ], "matchers": [ { "field": "to", "type": "literal", "value": "info@example.com" } ] }, { "actions": [ { "type": "worker", "value": [ "my-worker" ] } ], "matchers": [ { "field": "to", "type": "literal", "value": "billing@example.com" } ] } ] }, "required": [ "owner_worker_tag" ] }, "email_account_rules_plan_response_single": { "allOf": [ { "$ref": "#/components/schemas/email_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/email_account_rules_plan" } } } ] }, "email_account_rules_plan_rule": { "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/email_rule_actions" }, "enabled": { "$ref": "#/components/schemas/email_rule_enabled" }, "matchers": { "$ref": "#/components/schemas/email_rule_matchers" } }, "required": [ "actions", "matchers" ] }, "email_account_rules_plan_zone": { "type": "object", "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/email_account_rules_plan_change" } }, "zone_id": { "$ref": "#/components/schemas/email_identifier" }, "zone_name": { "description": "Zone name.", "type": "string", "example": "example.com" } } }, "email_account_rules_response_collection": { "allOf": [ { "$ref": "#/components/schemas/email_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/email_account_rule" } }, "result_info": { "type": "object", "properties": { "count": { "example": 1 }, "page": { "example": 1 }, "per_page": { "example": 20 }, "total_count": { "example": 1 } } } } } ] }, "email_addresses": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/email_destination_address_properties" } ] }, "email_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/email_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "email_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/email_messages" }, "messages": { "$ref": "#/components/schemas/email_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "email_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/email_api-response-common" } ] }, "email_catch_all_rule": { "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/email_rule_catchall-actions" }, "enabled": { "$ref": "#/components/schemas/email_rule_enabled" }, "id": { "$ref": "#/components/schemas/email_rule_identifier" }, "matchers": { "$ref": "#/components/schemas/email_rule_catchall-matchers" }, "name": { "$ref": "#/components/schemas/email_rule_name" }, "source": { "$ref": "#/components/schemas/email_rule_source" }, "tag": { "$ref": "#/components/schemas/email_rule_tag" } } }, "email_catch_all_rule_response_single": { "allOf": [ { "$ref": "#/components/schemas/email_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/email_catch_all_rule" } } } ] }, "email_create_destination_address_properties": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/email_email" } }, "required": [ "email" ] }, "email_create_rule_properties": { "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/email_rule_actions" }, "enabled": { "$ref": "#/components/schemas/email_rule_enabled" }, "matchers": { "$ref": "#/components/schemas/email_rule_matchers" }, "name": { "$ref": "#/components/schemas/email_rule_name" }, "owner_worker_tag": { "$ref": "#/components/schemas/email_rule_owner_worker_tag" }, "priority": { "$ref": "#/components/schemas/email_rule_priority" }, "source": { "$ref": "#/components/schemas/email_rule_source" } }, "required": [ "actions", "matchers" ] }, "email_create_sending_subdomain_properties": { "type": "object", "properties": { "name": { "description": "The domain name within the zone. A wildcard is allowed only as the complete leftmost label (`*.example.com`) and requires the account wildcard Email Sending entitlement.", "type": "string", "example": "sub.example.com" } }, "required": [ "name" ] }, "email_created": { "description": "The date and time the destination address has been created.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z", "readOnly": true }, "email_destination_address_identifier": { "description": "Destination address identifier.", "type": "string", "example": "ea95132c15732412d22c1476fa83f27a", "maxLength": 32, "readOnly": true, "x-auditable": true }, "email_destination_address_properties": { "type": "object", "properties": { "created": { "$ref": "#/components/schemas/email_created" }, "email": { "$ref": "#/components/schemas/email_email" }, "id": { "$ref": "#/components/schemas/email_destination_address_identifier" }, "modified": { "$ref": "#/components/schemas/email_modified" }, "tag": { "$ref": "#/components/schemas/email_destination_address_tag" }, "verified": { "$ref": "#/components/schemas/email_verified" } } }, "email_destination_address_response_single": { "allOf": [ { "$ref": "#/components/schemas/email_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/email_addresses" } } } ] }, "email_destination_address_tag": { "description": "Destination address tag. (Deprecated, replaced by destination address identifier)", "type": "string", "example": "ea95132c15732412d22c1476fa83f27a", "deprecated": true, "maxLength": 32, "readOnly": true }, "email_destination_addresses_response_collection": { "allOf": [ { "$ref": "#/components/schemas/email_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/email_addresses" } }, "result_info": { "type": "object", "properties": { "count": { "example": 1 }, "page": { "example": 1 }, "per_page": { "example": 20 }, "total_count": { "example": 1 } } } } } ] }, "email_dns_record": { "description": "List of records needed to enable an Email Routing zone.", "type": "object", "properties": { "content": { "description": "DNS record content.", "example": "route1.mx.cloudflare.net", "type": "string" }, "name": { "description": "DNS record name (or @ for the zone apex).", "type": "string", "example": "example.com", "maxLength": 255, "x-auditable": true }, "priority": { "description": "Required for MX, SRV and URI records. Unused by other record types. Records with lower priorities are preferred.", "type": "number", "example": 12, "maximum": 65535, "minimum": 0, "x-auditable": true }, "ttl": { "description": "Time to live, in seconds, of the DNS record. Must be between 60 and 86400, or 1 for 'automatic'.", "type": "number", "example": 1, "anyOf": [ { "example": 3600, "maximum": 86400, "minimum": 1, "type": "number" }, { "enum": [ 1 ], "type": "number" } ], "x-auditable": true }, "type": { "description": "DNS record type.", "type": "string", "example": "NS", "enum": [ "A", "AAAA", "CNAME", "HTTPS", "TXT", "SRV", "LOC", "MX", "NS", "CERT", "DNSKEY", "DS", "NAPTR", "SMIMEA", "SSHFP", "SVCB", "TLSA", "URI" ], "readOnly": true, "x-auditable": true } } }, "email_dns_settings_response_collection": { "allOf": [ { "$ref": "#/components/schemas/email_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/email_dns_record" } } } } ] }, "email_email": { "description": "The contact email address of the user.", "type": "string", "example": "user@example.com", "maxLength": 90, "x-auditable": true }, "email_email_setting_created": { "description": "The date and time the settings have been created.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z", "readOnly": true }, "email_email_setting_dns_request_body": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/email_email_setting_name" } }, "nullable": true }, "email_email_setting_enabled": { "description": "State of the zone settings for Email Routing.", "type": "boolean", "example": true, "enum": [ true, false ], "readOnly": true, "x-auditable": true }, "email_email_setting_identifier": { "description": "Email Routing settings identifier.", "type": "string", "example": "75610dab9e69410a82cf7e400a09ecec", "maxLength": 32, "readOnly": true, "x-auditable": true }, "email_email_setting_modified": { "description": "The date and time the settings have been modified.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z", "readOnly": true }, "email_email_setting_name": { "description": "Domain of your zone.", "type": "string", "example": "example.net", "x-auditable": true }, "email_email_setting_skip-wizard": { "description": "Flag to check if the user skipped the configuration wizard.", "type": "boolean", "example": true, "enum": [ true, false ], "readOnly": true }, "email_email_setting_status": { "description": "Show the state of your account, and the type or configuration error.", "type": "string", "example": "ready", "enum": [ "ready", "unconfigured", "misconfigured", "misconfigured/locked", "unlocked" ], "readOnly": true }, "email_email_setting_support_subaddress": { "description": "Whether subaddressing (plus-addressing) is honored when matching incoming mail against routing rules.", "type": "boolean", "example": true, "enum": [ true, false ], "readOnly": true }, "email_email_setting_tag": { "description": "Email Routing settings tag. (Deprecated, replaced by Email Routing settings identifier)", "type": "string", "example": "75610dab9e69410a82cf7e400a09ecec", "deprecated": true, "maxLength": 32, "readOnly": true }, "email_email_settings_properties": { "type": "object", "properties": { "created": { "$ref": "#/components/schemas/email_email_setting_created" }, "enabled": { "$ref": "#/components/schemas/email_email_setting_enabled" }, "id": { "$ref": "#/components/schemas/email_email_setting_identifier" }, "modified": { "$ref": "#/components/schemas/email_email_setting_modified" }, "name": { "$ref": "#/components/schemas/email_email_setting_name" }, "skip_wizard": { "$ref": "#/components/schemas/email_email_setting_skip-wizard" }, "status": { "$ref": "#/components/schemas/email_email_setting_status" }, "support_subaddress": { "$ref": "#/components/schemas/email_email_setting_support_subaddress" }, "tag": { "$ref": "#/components/schemas/email_email_setting_tag" } }, "required": [ "id", "name", "enabled" ] }, "email_email_settings_response_single": { "allOf": [ { "$ref": "#/components/schemas/email_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/email_settings" } } } ] }, "email_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "email_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "email_modified": { "description": "The date and time the destination address was last modified.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z", "readOnly": true }, "email_rule_action": { "description": "Actions pattern.", "type": "object", "properties": { "type": { "description": "Type of supported action.", "type": "string", "example": "forward", "enum": [ "drop", "forward", "worker" ], "x-auditable": true }, "value": { "type": "array", "items": { "description": "Value for action.", "example": "destinationaddress@example.net", "maxLength": 90, "type": "string", "x-auditable": true }, "maxItems": 1 } }, "required": [ "type" ] }, "email_rule_actions": { "description": "List actions patterns.", "type": "array", "items": { "$ref": "#/components/schemas/email_rule_action" }, "maxItems": 1, "minItems": 1 }, "email_rule_catchall-action": { "description": "Action for the catch-all routing rule.", "type": "object", "properties": { "type": { "description": "Type of action for catch-all rule.", "type": "string", "example": "forward", "enum": [ "drop", "forward", "worker" ], "x-auditable": true }, "value": { "type": "array", "items": { "description": "Input value for action.", "example": "destinationaddress@example.net", "maxLength": 90, "type": "string", "x-auditable": true }, "maxItems": 1 } }, "required": [ "type" ] }, "email_rule_catchall-actions": { "description": "List actions for the catch-all routing rule.", "type": "array", "items": { "$ref": "#/components/schemas/email_rule_catchall-action" }, "maxItems": 1, "minItems": 1 }, "email_rule_catchall-matcher": { "description": "Matcher for catch-all routing rule.", "type": "object", "properties": { "type": { "description": "Type of matcher. Default is 'all'.", "type": "string", "example": "all", "enum": [ "all" ], "x-auditable": true } }, "required": [ "type" ] }, "email_rule_catchall-matchers": { "description": "List of matchers for the catch-all routing rule.", "type": "array", "items": { "$ref": "#/components/schemas/email_rule_catchall-matcher" } }, "email_rule_enabled": { "description": "Routing rule status.", "type": "boolean", "example": true, "default": true, "enum": [ true, false ], "x-auditable": true }, "email_rule_identifier": { "description": "Routing rule identifier.", "type": "string", "example": "a7e6fb77503c41d8a7f3113c6918f10c", "maxLength": 32, "readOnly": true, "x-auditable": true }, "email_rule_matcher": { "description": "Matching pattern to forward your actions.", "type": "object", "properties": { "field": { "description": "Field for type matcher.", "type": "string", "example": "to", "enum": [ "to" ], "x-auditable": true }, "type": { "description": "Type of matcher.", "type": "string", "example": "literal", "enum": [ "all", "literal" ], "x-auditable": true }, "value": { "description": "Value for matcher.", "type": "string", "example": "test@example.com", "maxLength": 90, "x-auditable": true } }, "required": [ "type" ] }, "email_rule_matchers": { "description": "Matching patterns to forward to your actions.", "type": "array", "items": { "$ref": "#/components/schemas/email_rule_matcher" } }, "email_rule_name": { "description": "Routing rule name.", "type": "string", "example": "Send to user@example.net rule.", "maxLength": 256, "x-auditable": true }, "email_rule_owner_worker_tag": { "description": "Public tag (script_tag) of the Worker that owns this rule. Required when\n`source` is `wrangler`.\n", "type": "string", "example": "a7e6fb77503c41d8a7f3113c6918f10c", "maxLength": 32, "writeOnly": true, "x-auditable": true }, "email_rule_priority": { "description": "Priority of the routing rule.", "type": "number", "default": 0, "minimum": 0, "x-auditable": true }, "email_rule_properties": { "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/email_rule_actions" }, "enabled": { "$ref": "#/components/schemas/email_rule_enabled" }, "id": { "$ref": "#/components/schemas/email_rule_identifier" }, "matchers": { "$ref": "#/components/schemas/email_rule_matchers" }, "name": { "$ref": "#/components/schemas/email_rule_name" }, "priority": { "$ref": "#/components/schemas/email_rule_priority" }, "source": { "$ref": "#/components/schemas/email_rule_source" }, "tag": { "$ref": "#/components/schemas/email_rule_tag" } } }, "email_rule_response_single": { "allOf": [ { "$ref": "#/components/schemas/email_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/email_rules" } } } ] }, "email_rule_source": { "description": "Who manages the rule. `api` covers dashboard, generic API, and Terraform;\n`wrangler` means the rule is managed by a Worker's wrangler.jsonc. Defaults\nto `api` when omitted on write.\n", "type": "string", "example": "api", "default": "api", "enum": [ "api", "wrangler" ], "x-auditable": true }, "email_rule_tag": { "description": "Routing rule tag. (Deprecated, replaced by routing rule identifier)", "type": "string", "example": "a7e6fb77503c41d8a7f3113c6918f10c", "deprecated": true, "maxLength": 32, "readOnly": true }, "email_rules": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/email_rule_properties" } ] }, "email_rules_response_collection": { "allOf": [ { "$ref": "#/components/schemas/email_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/email_rules" } }, "result_info": { "type": "object", "properties": { "count": { "example": 1 }, "page": { "example": 1 }, "per_page": { "example": 20 }, "total_count": { "example": 1 } } } } } ] }, "email_sending_limits_properties": { "type": "object", "properties": { "quota": { "description": "The resolved daily sending quota for the account. Null when the quota is not yet available.", "type": "object", "nullable": true, "properties": { "unit": { "description": "The time period for the quota.", "type": "string", "example": "day", "enum": [ "day", "hour" ] }, "value": { "description": "The quota limit.", "type": "integer", "example": 1000 } }, "readOnly": true }, "usage": { "description": "The account's current daily sending usage. Null when there is no resolved quota or usage is temporarily unavailable.", "type": "object", "nullable": true, "properties": { "over_quota": { "description": "Whether the account has exceeded its daily sending quota.", "type": "boolean", "example": false }, "resets_at": { "description": "When the current daily quota window resets. Null when there is no active window.", "type": "string", "format": "date-time", "example": "2026-07-08T00:00:00Z", "nullable": true, "readOnly": true }, "sent": { "description": "Emails sent against the daily quota in the current window.", "type": "integer", "example": 42 } }, "readOnly": true } } }, "email_sending_limits_response_single": { "allOf": [ { "$ref": "#/components/schemas/email_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/email_sending_limits_properties" } } } ] }, "email_sending_reputation_properties": { "type": "object", "properties": { "active_policy": { "$ref": "#/components/schemas/email_ReputationPolicy" }, "evaluated_at": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "enum": [ "healthy", "warning", "at_risk", "suspended" ] }, "status_since": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false, "required": [ "status", "status_since", "evaluated_at", "active_policy" ] }, "email_sending_reputation_response_single": { "allOf": [ { "$ref": "#/components/schemas/email_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/email_sending_reputation_properties" } } } ] }, "email_sending_subdomain": { "allOf": [ { "$ref": "#/components/schemas/email_sending_subdomain_properties" } ] }, "email_sending_subdomain_config_error": { "description": "A DNS record, sending-configuration, or policy issue detected during preview, status, or fix.", "type": "object", "properties": { "code": { "description": "Error code identifying the type of issue. `dkim.conflict` is\nreported whenever 2+ TXT records exist at the DKIM selector,\neven if one matches the canonical Cloudflare content — multi-record\nDKIM can permerror at recipient verification regardless of which\nentry is correct. `domainkey.delegated` indicates that\n`_domainkey.` has NS records in the Cloudflare zone,\ncreating a zone cut that shadows the DKIM TXT record we publish;\nthe customer must remove the NS delegation for DKIM to verify.\n`dmarc.incompatible` indicates that a wildcard sending row no longer\nsatisfies its DMARC safety requirements, such as relaxed alignment,\na valid governing policy, and the organizational-domain constraint.\nThe customer must correct the zone or policy configuration manually;\nDNS Fix cannot resolve this error.\n`sending_subdomain.conflict` is reported by preview when an enabled\nexplicit or wildcard sending row would give some senders a different\nsigning identity.\n", "type": "string", "example": "dkim.conflict", "enum": [ "mx.missing", "mx.foreign", "spf.missing", "spf.foreign", "spf.multiple", "dkim.missing", "dkim.conflict", "dmarc.missing", "dmarc.multiple", "dmarc.incompatible", "domainkey.delegated", "sending_subdomain.conflict" ] }, "conflicting_subdomain": { "description": "The enabled sending-subdomain row that conflicts with the requested name.", "type": "string", "example": "*.example.com" }, "existing": { "$ref": "#/components/schemas/email_dns_record" }, "missing": { "$ref": "#/components/schemas/email_dns_record" }, "multiple": { "type": "array", "items": { "$ref": "#/components/schemas/email_dns_record" } } }, "required": [ "code" ] }, "email_sending_subdomain_dns_status_response": { "allOf": [ { "$ref": "#/components/schemas/email_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "errors": { "description": "DNS issues detected against the current zone state.", "type": "array", "items": { "$ref": "#/components/schemas/email_sending_subdomain_config_error" } }, "records": { "description": "Desired DNS records for the subdomain.", "type": "array", "items": { "$ref": "#/components/schemas/email_dns_record" } }, "status": { "description": "Aggregated DNS state for the subdomain. `unlocked` means desired records exist with correct content but at least one has had its email_routing/read_only lock cleared.", "type": "string", "enum": [ "ready", "unconfigured", "unlocked", "misconfigured" ] } } } } } ] }, "email_sending_subdomain_identifier": { "description": "Sending subdomain identifier.", "type": "string", "example": "aabbccdd11223344aabbccdd11223344", "maxLength": 32, "readOnly": true, "x-auditable": true }, "email_sending_subdomain_preview_response": { "allOf": [ { "$ref": "#/components/schemas/email_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "errors": { "description": "DNS or sending-configuration issues detected during the preview.", "type": "array", "items": { "$ref": "#/components/schemas/email_sending_subdomain_config_error" } }, "records": { "description": "DNS records that would be created for the subdomain.", "type": "array", "items": { "$ref": "#/components/schemas/email_dns_record" } } } } } } ] }, "email_sending_subdomain_properties": { "type": "object", "properties": { "created": { "$ref": "#/components/schemas/email_created" }, "dkim_selector": { "description": "The DKIM selector used for email signing. Wildcard rows publish the selector and sign with `d=`.", "type": "string", "example": "cf-bounce", "readOnly": true }, "drop_suppressed_recipients": { "description": "Whether a send request that includes a recipient suppressed on\nthis subdomain drops that recipient and still delivers to the\nrest, instead of failing the entire request.\n", "type": "boolean", "example": false, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "enabled": { "description": "Whether Email Sending is enabled on this subdomain.", "type": "boolean", "readOnly": true }, "modified": { "$ref": "#/components/schemas/email_modified" }, "name": { "description": "The exact domain name or a leftmost wildcard such as `*.example.com`.", "type": "string", "example": "sub.example.com", "x-auditable": true }, "preview_enabled": { "description": "Whether sent messages from this subdomain can be previewed in the activity log.", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "return_path_domain": { "description": "The return-path domain used for bounce handling. Wildcard rows use `cf-bounce.`.", "type": "string", "example": "cf-bounce.sub.example.com", "readOnly": true }, "tag": { "$ref": "#/components/schemas/email_sending_subdomain_identifier" } }, "required": [ "tag", "name", "enabled" ] }, "email_sending_subdomain_reputation_complaints": { "type": "object", "properties": { "complaints": { "type": "integer", "minimum": 0 } }, "required": [ "complaints" ] }, "email_sending_subdomain_reputation_complaints_response": { "allOf": [ { "$ref": "#/components/schemas/email_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/email_sending_subdomain_reputation_complaints" } } } ] }, "email_sending_subdomain_response_single": { "allOf": [ { "$ref": "#/components/schemas/email_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/email_sending_subdomain" } } } ] }, "email_sending_subdomains_response_collection": { "allOf": [ { "$ref": "#/components/schemas/email_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/email_sending_subdomain" } } } } ] }, "email_settings": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/email_email_settings_properties" } ] }, "email_update_catch_all_rule_properties": { "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/email_rule_catchall-actions" }, "enabled": { "$ref": "#/components/schemas/email_rule_enabled" }, "matchers": { "$ref": "#/components/schemas/email_rule_catchall-matchers" }, "name": { "$ref": "#/components/schemas/email_rule_name" }, "owner_worker_tag": { "$ref": "#/components/schemas/email_rule_owner_worker_tag" }, "source": { "$ref": "#/components/schemas/email_rule_source" } }, "required": [ "actions", "matchers" ] }, "email_update_destination_address_properties": { "type": "object", "properties": { "status": { "description": "Destination address status. Non-admin callers may only set verified addresses back to unverified; setting to verified requires admin privileges.", "type": "string", "example": "verified", "enum": [ "unverified", "verified" ], "x-auditable": true } }, "required": [ "status" ] }, "email_update_email_routing_settings_properties": { "type": "object", "properties": { "enabled": { "description": "State of your zone Email Routing settings. No-op on this endpoint - use `POST`/`DELETE /zones/{zone_id}/email/routing/dns`.", "type": "boolean", "example": true, "enum": [ true, false ] }, "skip_wizard": { "description": "Flag to check if the user skipped the configuration wizard.", "type": "boolean", "example": true, "enum": [ true, false ] }, "support_subaddress": { "description": "Whether subaddressing (plus-addressing) is honored when matching incoming mail against routing rules.", "type": "boolean", "example": true, "enum": [ true, false ] } } }, "email_update_rule_properties": { "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/email_rule_actions" }, "enabled": { "$ref": "#/components/schemas/email_rule_enabled" }, "matchers": { "$ref": "#/components/schemas/email_rule_matchers" }, "name": { "$ref": "#/components/schemas/email_rule_name" }, "owner_worker_tag": { "$ref": "#/components/schemas/email_rule_owner_worker_tag" }, "priority": { "$ref": "#/components/schemas/email_rule_priority" }, "source": { "$ref": "#/components/schemas/email_rule_source" } }, "required": [ "actions", "matchers" ] }, "email_update_sending_subdomain_properties": { "description": "At least one of `preview_enabled` or `drop_suppressed_recipients` must\nbe provided. A field omitted from the request body is left unchanged.\n", "type": "object", "properties": { "drop_suppressed_recipients": { "description": "Whether a send request that includes a recipient suppressed on\nthis subdomain drops that recipient and still delivers to the\nrest, instead of failing the entire request.\n", "type": "boolean", "example": true, "x-stainless-terraform-configurability": "computed_optional" }, "preview_enabled": { "description": "Whether sent messages from this subdomain can be previewed in the activity log.", "type": "boolean", "example": true, "x-stainless-terraform-configurability": "computed_optional" } }, "anyOf": [ { "required": [ "preview_enabled" ] }, { "required": [ "drop_suppressed_recipients" ] } ] }, "email_verified": { "description": "The date and time the destination address has been verified. Null means not verified yet.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z", "readOnly": true }, "email_zone_id": { "$ref": "#/components/schemas/email_identifier" }, "entitlements_allocation": { "description": "Represents the allocation value for an entitlement. The shape of `value` depends on `type`: `bool` uses a boolean, `max_count` uses an integer, `enum_number` uses an array of numbers, `range` uses an object with `min` and `max` integer fields, and `string` uses a string.\n", "type": "object", "properties": { "type": { "description": "Allocation type discriminator.", "type": "string", "example": "max_count", "enum": [ "bool", "max_count", "enum_number", "range", "string" ] }, "value": { "description": "Contains the allocation value whose concrete type the `type` field determines: bool yields a boolean, max_count yields an integer, enum_number yields an array of numbers, range yields an object with `min` and `max`, and string yields a string.\n", "example": 25, "oneOf": [ { "type": "boolean" }, { "type": "integer" }, { "type": "string" }, { "items": { "type": "number" }, "type": "array" }, { "properties": { "max": { "type": "integer" }, "min": { "type": "integer" } }, "required": [ "min", "max" ], "type": "object" } ] } }, "required": [ "value", "type" ] }, "entitlements_api_error": { "description": "Represents an error that the API returns.", "type": "object", "properties": { "code": { "description": "Numeric error code.", "type": "integer", "example": 2000 }, "message": { "description": "Human-readable error message.", "type": "string", "example": "failed to fetch entitlements: internal server error" } }, "required": [ "code", "message" ] }, "entitlements_api_message": { "description": "Represents an informational message that the API returns.", "type": "object", "properties": { "code": { "description": "Numeric message code.", "type": "integer", "example": 0 }, "message": { "description": "Human-readable message.", "type": "string", "example": "" } }, "required": [ "code", "message" ] }, "entitlements_api_response_failure": { "description": "Standard Cloudflare API failure response.", "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/entitlements_api_error" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/entitlements_api_message" } }, "result": { "description": "Always null for error responses.", "type": "object", "nullable": true }, "success": { "description": "Always false for error responses.", "type": "boolean", "example": false } }, "required": [ "success", "errors", "messages", "result" ] }, "entitlements_entitlement": { "description": "A single entitlement record for a zone or account.", "type": "object", "properties": { "allocation": { "$ref": "#/components/schemas/entitlements_allocation" }, "created_date": { "description": "ISO 8601 timestamp (microsecond precision, no timezone offset) when the entitlement was created. Format: `YYYY-MM-DDTHH:MM:SS.ffffff`.\n", "type": "string", "example": "2021-09-17T20:33:36.000000" }, "deleted_date": { "description": "ISO 8601 timestamp when the entitlement was deleted, or empty string if not deleted.\n", "type": "string", "example": "" }, "edited_date": { "description": "ISO 8601 timestamp (microsecond precision, no timezone offset) when the entitlement was last edited.\n", "type": "string", "example": "2021-09-17T20:34:01.000000" }, "feature": { "$ref": "#/components/schemas/entitlements_feature" }, "id": { "description": "Entitlement identifier — equal to the feature key.\n", "type": "string", "example": "page_rules" } }, "required": [ "id", "feature", "allocation", "created_date", "edited_date", "deleted_date" ] }, "entitlements_entitlements_response": { "description": "Standard Cloudflare API response wrapping a list of entitlements.", "type": "object", "properties": { "errors": { "description": "List of errors, empty on success.", "type": "array", "items": { "$ref": "#/components/schemas/entitlements_api_error" } }, "messages": { "description": "List of informational messages.", "type": "array", "items": { "$ref": "#/components/schemas/entitlements_api_message" } }, "result": { "description": "List of entitlements for the requested object.", "type": "array", "items": { "$ref": "#/components/schemas/entitlements_entitlement" } }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages", "result" ] }, "entitlements_feature": { "description": "Describes a product feature associated with an entitlement.", "type": "object", "properties": { "feature_set": { "description": "The logical grouping (set) this feature belongs to.", "type": "string", "example": "page_rules" }, "id": { "description": "Numeric identifier of the feature.", "type": "integer", "format": "int64", "example": 1 }, "key": { "description": "Unique string key for the feature.", "type": "string", "example": "page_rules" }, "name": { "description": "Human-readable name of the feature.", "type": "string", "example": "Page Rules" } }, "required": [ "feature_set", "id", "key", "name" ] }, "entitlements_identifier": { "description": "Identifier tag.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "minLength": 32, "pattern": "^[0-9a-f]{32}$" }, "field-extractors_ApiError": { "type": "object", "properties": { "code": { "type": "number" }, "message": { "type": "string" }, "source": { "description": "Points to the offending input as a JSON Pointer into the request body.", "type": "object", "example": "/rules/0/fields/0/expression", "properties": { "pointer": { "type": "string" } }, "required": [ "pointer" ] } }, "required": [ "code", "message" ] }, "field-extractors_DeleteResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/field-extractors_ApiError" } }, "messages": { "description": "Additional informational messages.", "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "description": "Result is null.", "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "field-extractors_ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/field-extractors_ApiError" } }, "messages": { "description": "Additional informational messages.", "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "description": "Result is null.", "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "field-extractors_ExtractorResult": { "type": "object", "properties": { "extractor": { "description": "Extractor type.", "type": "string", "example": "llm_prompts", "readOnly": true }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/field-extractors_RuleOutput" }, "minItems": 1 } }, "required": [ "extractor", "rules" ] }, "field-extractors_FieldOutput": { "type": "object", "properties": { "expression": { "description": "Wirefilter value expression.", "type": "string", "example": "filter(http.request.body.json.strings.values, http.request.body.json.strings.pointers[*] matches \"^/messages/\\\\d+/content$\")" }, "name": { "description": "Field name.", "type": "string", "example": "prompt" } }, "required": [ "name", "expression" ] }, "field-extractors_RuleOutput": { "type": "object", "properties": { "description": { "description": "Human-readable rule description.", "type": "string" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/field-extractors_FieldOutput" } }, "ref": { "description": "Stable rule identifier.", "type": "string", "example": "openai-chat" } }, "required": [ "ref", "fields" ] }, "field-extractors_SuccessResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/field-extractors_ApiError" } }, "messages": { "description": "Additional informational messages.", "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "result": { "$ref": "#/components/schemas/field-extractors_ExtractorResult" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "firewall_account_identifier": { "description": "Defines an account identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 }, "firewall_action": { "description": "The action to perform when the threshold of matched traffic within the configured period is exceeded.", "type": "object", "anyOf": [ { "properties": { "mode": { "$ref": "#/components/schemas/firewall_mode" }, "response": { "$ref": "#/components/schemas/firewall_custom_response" }, "timeout": { "$ref": "#/components/schemas/firewall_timeout" } }, "type": "object" } ] }, "firewall_action_mode": { "description": "The default action performed by the rules in the WAF package.", "type": "string", "default": "challenge", "enum": [ "simulate", "block", "challenge" ] }, "firewall_anomaly_description": { "description": "A summary of the purpose/function of the WAF package.", "type": "string", "example": "Covers OWASP Top 10 vulnerabilities and more.", "readOnly": true }, "firewall_anomaly_detection_mode": { "description": "When a WAF package uses anomaly detection, each rule is given a score when triggered. If the total score of all triggered rules exceeds the sensitivity defined on the WAF package, the action defined on the package will be taken.", "type": "string", "example": "anomaly", "readOnly": true }, "firewall_anomaly_name": { "description": "The name of the WAF package.", "type": "string", "example": "OWASP ModSecurity Core Rule Set", "readOnly": true }, "firewall_anomaly_package": { "allOf": [ { "$ref": "#/components/schemas/firewall_package_definition" }, { "properties": { "action_mode": { "$ref": "#/components/schemas/firewall_action_mode" }, "description": { "$ref": "#/components/schemas/firewall_anomaly_description" }, "detection_mode": { "$ref": "#/components/schemas/firewall_anomaly_detection_mode" }, "name": { "$ref": "#/components/schemas/firewall_anomaly_name" }, "sensitivity": { "$ref": "#/components/schemas/firewall_sensitivity" } }, "type": "object" } ], "required": [ "id", "name", "description", "zone_id", "detection_mode", "sensitivity", "action_mode" ], "title": "Anomaly detection WAF package (OWASP)" }, "firewall_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "type": "object" }, "nullable": true }, "result_info": { "$ref": "#/components/schemas/firewall_result_info" } }, "type": "object" } ] }, "firewall_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/firewall_messages" }, "messages": { "$ref": "#/components/schemas/firewall_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": { "type": "object" }, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Defines whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "firewall_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/firewall_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/firewall_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Defines whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "firewall_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-common" }, { "properties": { "result": { "anyOf": [ { "nullable": true, "type": "object" }, { "nullable": true, "type": "string" } ] } }, "type": "object" } ] }, "firewall_api-response-single-id": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-common" }, { "properties": { "result": { "type": "object", "nullable": true, "properties": { "id": { "$ref": "#/components/schemas/firewall_identifier" } }, "required": [ "id" ] } }, "type": "object" } ] }, "firewall_asn_configuration": { "type": "object", "properties": { "target": { "description": "The configuration target. You must set the target to `asn` when specifying an Autonomous System Number (ASN) in the rule.", "type": "string", "example": "asn", "enum": [ "asn" ] }, "value": { "description": "The AS number to match.", "type": "string", "example": "AS12345" } }, "title": "An ASN configuration." }, "firewall_body": { "description": "The response body to return. The value must conform to the configured content type.", "type": "string", "example": "This request has been rate-limited.", "maxLength": 10240 }, "firewall_bypass": { "description": "Criteria specifying when the current rate limit should be bypassed. You can specify that the rate limit should not apply to one or more URLs.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "url", "enum": [ "url" ] }, "value": { "description": "The URL to bypass.", "type": "string", "example": "api.example.com/*" } }, "type": "object" } }, "firewall_cidr_configuration": { "type": "object", "properties": { "target": { "description": "The configuration target. You must set the target to `ip_range` when specifying an IP address range in the rule.", "type": "string", "example": "ip_range", "enum": [ "ip_range" ] }, "value": { "description": "The IP address range to match. You can only use prefix lengths `/16` and `/24` for IPv4 ranges, and prefix lengths `/32`, `/48`, and `/64` for IPv6 ranges.", "type": "string", "example": "198.51.100.4/16" } }, "title": "An IP address range configuration." }, "firewall_components-schemas-description": { "description": "An informative summary of the current URI-based WAF override.", "type": "string", "example": "Enable Cloudflare Magento ruleset for shop.example.com", "maxLength": 1024, "nullable": true, "x-auditable": true }, "firewall_components-schemas-identifier": { "description": "The unique identifier of the resource.", "type": "string", "example": "de677e5818985db1285d0e80225f06e5", "maxLength": 32, "readOnly": true }, "firewall_components-schemas-mode": { "description": "The action to apply to a matched request.", "example": "js_challenge", "enum": [ "block", "challenge", "js_challenge", "managed_challenge" ], "maxLength": 12 }, "firewall_components-schemas-paused": { "description": "When true, indicates that the firewall rule is currently paused.", "type": "boolean", "example": false }, "firewall_components-schemas-priority": { "description": "The priority of the rule. Optional value used to define the processing order. A lower number indicates a higher priority. If not provided, rules with a defined priority will be processed before rules without a priority.", "type": "number", "example": 50, "maximum": 2147483647, "minimum": 0 }, "firewall_components-ua-rule-id": { "description": "The unique identifier of the User Agent Blocking rule.", "type": "string", "example": "372e67954025e0ba6aaa6d586b9e0b59", "maxLength": 32, "readOnly": true, "x-auditable": true }, "firewall_configuration": { "description": "The rule configuration.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/firewall_ip_configuration" }, { "$ref": "#/components/schemas/firewall_ipv6_configuration" }, { "$ref": "#/components/schemas/firewall_cidr_configuration" }, { "$ref": "#/components/schemas/firewall_asn_configuration" }, { "$ref": "#/components/schemas/firewall_country_configuration" } ] }, "firewall_configurations": { "description": "A list of IP addresses or CIDR ranges that will be allowed to access the URLs specified in the Zone Lockdown rule. You can include any number of `ip` or `ip_range` configurations.", "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/firewall_schemas-ip_configuration" }, { "$ref": "#/components/schemas/firewall_schemas-cidr_configuration" } ] } }, "firewall_content_type": { "description": "The content type of the body. Must be one of the following: `text/plain`, `text/xml`, or `application/json`.", "type": "string", "example": "text/xml", "maxLength": 50, "x-auditable": true }, "firewall_country_configuration": { "type": "object", "properties": { "target": { "description": "The configuration target. You must set the target to `country` when specifying a country code in the rule.", "type": "string", "example": "country", "enum": [ "country" ] }, "value": { "description": "The two-letter ISO-3166-1 alpha-2 code to match. For more information, refer to [IP Access rules: Parameters](https://developers.cloudflare.com/waf/tools/ip-access-rules/parameters/#country).", "type": "string", "example": "US", "x-auditable": true } }, "title": "A country configuration." }, "firewall_created_on": { "description": "The timestamp of when the rule was created.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true, "x-auditable": true }, "firewall_custom_response": { "description": "A custom content type and reponse to return when the threshold is exceeded. The custom response configured in this object will override the custom error for the zone. This object is optional.\nNotes: If you omit this object, Cloudflare will use the default HTML error page. If \"mode\" is \"challenge\", \"managed_challenge\", or \"js_challenge\", Cloudflare will use the zone challenge pages and you should not provide the \"response\" object.", "type": "object", "anyOf": [ { "properties": { "body": { "$ref": "#/components/schemas/firewall_body" }, "content_type": { "$ref": "#/components/schemas/firewall_content_type" } }, "type": "object" } ] }, "firewall_delete_filter_if_unused": { "description": "When true, indicates that Cloudflare should also delete the associated filter if there are no other firewall rules referencing the filter.", "type": "boolean" }, "firewall_deleted": { "description": "When true, indicates that the firewall rule was deleted.", "type": "boolean", "example": true }, "firewall_deleted-filter": { "type": "object", "properties": { "deleted": { "$ref": "#/components/schemas/firewall_deleted" }, "id": { "$ref": "#/components/schemas/firewall_filters_components-schemas-id" } }, "additionalProperties": false, "required": [ "id", "deleted" ] }, "firewall_description": { "description": "An informative summary of the rule. This value is sanitized and any tags will be removed.", "type": "string", "example": "Prevent multiple login failures to mitigate brute force attacks", "maxLength": 1024, "x-auditable": true }, "firewall_description_search": { "description": "A string to search for in the description of existing rules.", "type": "string", "example": "abusive", "x-auditable": true }, "firewall_detection_mode": { "description": "The mode that defines how rules within the package are evaluated during the course of a request. When a package uses anomaly detection mode (`anomaly` value), each rule is given a score when triggered. If the total score of all triggered rules exceeds the sensitivity defined in the WAF package, the action configured in the package will be performed. Traditional detection mode (`traditional` value) will decide the action to take when it is triggered by the request. If multiple rules are triggered, the action providing the highest protection will be applied (for example, a 'block' action will win over a 'challenge' action).", "type": "string", "example": "traditional", "enum": [ "anomaly", "traditional" ], "readOnly": true }, "firewall_disabled": { "description": "When true, indicates that the rate limit is currently disabled.", "type": "boolean", "example": false, "x-auditable": true }, "firewall_email": { "description": "The contact email address of the user.", "type": "string", "example": "user@example.com", "maxLength": 90 }, "firewall_expression": { "description": "The filter expression. For more information, refer to [Expressions](https://developers.cloudflare.com/ruleset-engine/rules-language/expressions/).", "type": "string", "example": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155" }, "firewall_filter": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/firewall_filters_components-schemas-description" }, "expression": { "$ref": "#/components/schemas/firewall_expression" }, "id": { "$ref": "#/components/schemas/firewall_filters_components-schemas-id" }, "paused": { "$ref": "#/components/schemas/firewall_filters_components-schemas-paused" }, "ref": { "$ref": "#/components/schemas/firewall_schemas-ref" } }, "additionalProperties": false }, "firewall_filter-delete-response-collection": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "properties": { "id": { "$ref": "#/components/schemas/firewall_filters_components-schemas-id" } }, "type": "object" } } }, "type": "object" } ] }, "firewall_filter-delete-response-single": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/firewall_filters_components-schemas-id" } }, "required": [ "id" ] } }, "required": [ "result" ], "type": "object" } ] }, "firewall_filter-response-collection": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/firewall_filter" } } }, "type": "object" } ] }, "firewall_filter-response-single": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/firewall_filter" } }, "required": [ "result" ], "type": "object" } ] }, "firewall_filter-rule-base": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/firewall_schemas-action" }, "description": { "$ref": "#/components/schemas/firewall_firewall-rules_components-schemas-description" }, "id": { "$ref": "#/components/schemas/firewall_firewall-rules_components-schemas-id" }, "paused": { "$ref": "#/components/schemas/firewall_components-schemas-paused" }, "priority": { "$ref": "#/components/schemas/firewall_components-schemas-priority" }, "products": { "$ref": "#/components/schemas/firewall_products" }, "ref": { "$ref": "#/components/schemas/firewall_ref" } } }, "firewall_filter-rule-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/firewall_filter-rule-base" }, { "properties": { "filter": { "oneOf": [ { "$ref": "#/components/schemas/firewall_filter" }, { "$ref": "#/components/schemas/firewall_deleted-filter" } ] } }, "type": "object" } ] }, "firewall_filter-rule-update-request": { "allOf": [ { "$ref": "#/components/schemas/firewall_filter" }, { "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/firewall_filters_components-schemas-id" } ] } }, "type": "object" } ] }, "firewall_filter-rules-response-collection": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/firewall_filter-rule-response" } } }, "required": [ "result" ], "type": "object" } ] }, "firewall_filter-rules-response-collection-delete": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/firewall_filter-rule-response" } } }, "required": [ "result" ], "type": "object" } ] }, "firewall_filter-rules-single-response": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/firewall_filter-rule-response" } }, "required": [ "result" ], "type": "object" } ] }, "firewall_filter-rules-single-response-delete": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/firewall_filter-rule-response" } }, "required": [ "result" ], "type": "object" } ] }, "firewall_filters_components-schemas-description": { "description": "An informative summary of the filter.", "type": "string", "example": "Restrict access from these browsers on this address range.", "maxLength": 500 }, "firewall_filters_components-schemas-id": { "description": "The unique identifier of the filter.", "type": "string", "example": "372e67954025e0ba6aaa6d586b9e0b61", "maxLength": 32, "minLength": 32, "readOnly": true }, "firewall_filters_components-schemas-paused": { "description": "When true, indicates that the filter is currently paused.", "type": "boolean", "example": false }, "firewall_firewall-rules_components-schemas-description": { "description": "An informative summary of the firewall rule.", "type": "string", "example": "Blocks traffic identified during investigation for MIR-31", "maxLength": 500 }, "firewall_firewall-rules_components-schemas-id": { "description": "The unique identifier of the firewall rule.", "type": "string", "example": "372e67954025e0ba6aaa6d586b9e0b60", "maxLength": 32, "readOnly": true }, "firewall_firewalluablock": { "type": "object", "properties": { "configuration": { "$ref": "#/components/schemas/firewall_schemas-configuration" }, "description": { "$ref": "#/components/schemas/firewall_firewalluablock_components-schemas-description" }, "id": { "$ref": "#/components/schemas/firewall_components-ua-rule-id" }, "mode": { "$ref": "#/components/schemas/firewall_components-schemas-mode" }, "paused": { "$ref": "#/components/schemas/firewall_schemas-paused" } } }, "firewall_firewalluablock_components-schemas-description": { "description": "An informative summary of the rule.", "type": "string", "example": "Prevent access from abusive clients identified by this User Agent to mitigate a DDoS attack", "maxLength": 1024 }, "firewall_firewalluablock_response_collection": { "allOf": [ { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/firewall_firewalluablock" } } }, "type": "object" }, { "$ref": "#/components/schemas/firewall_api-response-collection" } ] }, "firewall_firewalluablock_response_single": { "allOf": [ { "properties": { "result": { "$ref": "#/components/schemas/firewall_firewalluablock" } }, "type": "object" }, { "$ref": "#/components/schemas/firewall_api-response-single" } ] }, "firewall_groups": { "description": "An object that allows you to enable or disable WAF rule groups for the current WAF override. Each key of this object must be the ID of a WAF rule group, and each value must be a valid WAF action (usually `default` or `disable`). When creating a new URI-based WAF override, you must provide a `groups` object or a `rules` object.", "type": "object", "example": { "ea8687e59929c1fd05ba97574ad43f77": "default" }, "additionalProperties": true }, "firewall_header_name": { "description": "The name of the response header to match.", "type": "string", "example": "Cf-Cache-Status", "x-auditable": true }, "firewall_header_op": { "description": "The operator used when matching: `eq` means \"equal\" and `ne` means \"not equal\".", "type": "string", "example": "ne", "enum": [ "eq", "ne" ], "x-auditable": true }, "firewall_header_value": { "description": "The value of the response header, which must match exactly.", "type": "string", "example": "HIT", "x-auditable": true }, "firewall_id": { "description": "The unique identifier of the rate limit.", "type": "string", "example": "372e67954025e0ba6aaa6d586b9e0b59", "maxLength": 32, "readOnly": true, "x-auditable": true }, "firewall_identifier": { "description": "Defines an identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "firewall_ip_configuration": { "type": "object", "properties": { "target": { "description": "The configuration target. You must set the target to `ip` when specifying an IP address in the rule.", "type": "string", "example": "ip", "enum": [ "ip" ] }, "value": { "description": "The IP address to match. This address will be compared to the IP address of incoming requests.", "type": "string", "example": "198.51.100.4" } }, "title": "An IP address configuration." }, "firewall_ip_range_search": { "description": "A single IP address range to search for in existing rules.", "type": "string", "example": "1.2.3.0/16", "x-auditable": true }, "firewall_ip_search": { "description": "A single IP address to search for in existing rules.", "type": "string", "example": "1.2.3.4" }, "firewall_ipv6_configuration": { "type": "object", "properties": { "target": { "description": "The configuration target. You must set the target to `ip6` when specifying an IPv6 address in the rule.", "type": "string", "example": "ip6", "enum": [ "ip6" ] }, "value": { "description": "The IPv6 address to match.", "type": "string", "example": "2001:DB8:100::CF" } }, "title": "An IPv6 address configuration." }, "firewall_lockdowns_components-schemas-description": { "description": "An informative summary of the rule.", "type": "string", "example": "Restrict access to these endpoints to requests from a known IP address", "maxLength": 1024 }, "firewall_lockdowns_components-schemas-id": { "description": "The unique identifier of the Zone Lockdown rule.", "type": "string", "example": "372e67954025e0ba6aaa6d586b9e0b59", "maxLength": 32, "readOnly": true, "x-auditable": true }, "firewall_match": { "description": "Determines which traffic the rate limit counts towards the threshold.", "type": "object", "oneOf": [ { "properties": { "headers": { "type": "array", "items": { "properties": { "name": { "$ref": "#/components/schemas/firewall_header_name" }, "op": { "$ref": "#/components/schemas/firewall_header_op" }, "value": { "$ref": "#/components/schemas/firewall_header_value" } }, "type": "object" } }, "request": { "type": "object", "properties": { "methods": { "$ref": "#/components/schemas/firewall_methods" }, "schemes": { "$ref": "#/components/schemas/firewall_schemes" }, "url": { "$ref": "#/components/schemas/firewall_url" } } }, "response": { "type": "object", "properties": { "origin_traffic": { "$ref": "#/components/schemas/firewall_origin_traffic" } } } }, "type": "object" } ] }, "firewall_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "firewall_methods": { "description": "The HTTP methods to match. You can specify a subset (for example, `['POST','PUT']`) or all methods (`['_ALL_']`). This field is optional when creating a rate limit.", "type": "array", "items": { "description": "An HTTP method or `_ALL_` to indicate all methods.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "_ALL_" ], "example": "GET", "type": "string", "x-auditable": true }, "example": [ "GET", "POST" ] }, "firewall_mode": { "description": "The action to perform.", "type": "string", "example": "challenge", "enum": [ "simulate", "ban", "challenge", "js_challenge", "managed_challenge" ], "x-auditable": true }, "firewall_modified_on": { "description": "The timestamp of when the rule was last modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true, "x-auditable": true }, "firewall_name": { "description": "The name of the WAF package.", "type": "string", "example": "USER", "readOnly": true }, "firewall_notes": { "description": "An informative summary of the rule, typically used as a reminder or explanation.", "type": "string", "example": "This rule is enabled because of an event that occurred on date X.", "x-auditable": true }, "firewall_origin_traffic": { "description": "When true, only the uncached traffic served from your origin servers will count towards rate limiting. In this case, any cached traffic served by Cloudflare will not count towards rate limiting. This field is optional.\nNotes: This field is deprecated. Instead, use response headers and set \"origin_traffic\" to \"false\" to avoid legacy behaviour interacting with the \"response_headers\" property.", "type": "boolean", "x-auditable": true }, "firewall_override": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/firewall_components-schemas-description" }, "groups": { "$ref": "#/components/schemas/firewall_groups" }, "id": { "$ref": "#/components/schemas/firewall_overrides-id" }, "paused": { "$ref": "#/components/schemas/firewall_paused" }, "priority": { "$ref": "#/components/schemas/firewall_priority" }, "rewrite_action": { "$ref": "#/components/schemas/firewall_rewrite_action" }, "rules": { "$ref": "#/components/schemas/firewall_rules" }, "urls": { "$ref": "#/components/schemas/firewall_urls" } } }, "firewall_override_response_collection": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/firewall_override" } } }, "required": [ "result" ], "type": "object" } ] }, "firewall_override_response_single": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/firewall_override" } }, "required": [ "result" ], "type": "object" } ] }, "firewall_overrides-id": { "description": "The unique identifier of the WAF override.", "type": "string", "example": "de677e5818985db1285d0e80225f06e5", "maxLength": 32, "readOnly": true, "x-auditable": true }, "firewall_package": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/firewall_package_definition" }, { "$ref": "#/components/schemas/firewall_anomaly_package" } ] }, "firewall_package_definition": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/firewall_schemas-description" }, "detection_mode": { "$ref": "#/components/schemas/firewall_detection_mode" }, "id": { "$ref": "#/components/schemas/firewall_identifier" }, "name": { "$ref": "#/components/schemas/firewall_name" }, "status": { "$ref": "#/components/schemas/firewall_status" }, "zone_id": { "$ref": "#/components/schemas/firewall_identifier" } }, "required": [ "id", "name", "description", "detection_mode", "zone_id" ], "title": "Traditional WAF package" }, "firewall_package_id": { "description": "Defines a package identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "firewall_package_response_collection": { "anyOf": [ { "$ref": "#/components/schemas/firewall_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/firewall_package" } } }, "type": "object" } ] }, "firewall_package_response_single": { "oneOf": [ { "$ref": "#/components/schemas/firewall_api-response-single" }, { "properties": { "result": { "type": "object" } }, "type": "object" } ] }, "firewall_paused": { "description": "When true, indicates that the rule is currently paused.", "type": "boolean", "x-auditable": true }, "firewall_period": { "description": "The time in seconds (an integer value) to count matching traffic. If the count exceeds the configured threshold within this period, Cloudflare will perform the configured action.", "type": "number", "example": 900, "maximum": 86400, "minimum": 10, "x-auditable": true }, "firewall_priority": { "description": "The relative priority of the current URI-based WAF override when multiple overrides match a single URL. A lower number indicates higher priority. Higher priority overrides may overwrite values set by lower priority overrides.", "type": "number", "example": 1, "maximum": 1000000000, "minimum": -1000000000, "x-auditable": true }, "firewall_products": { "type": "array", "items": { "description": "A list of products to bypass for a request when using the `bypass` action.", "enum": [ "zoneLockdown", "uaBlock", "bic", "hot", "securityLevel", "rateLimit", "waf" ], "example": "waf", "type": "string" } }, "firewall_rate-limits": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/firewall_ratelimit" } ] }, "firewall_rate_limit_id": { "description": "Defines the unique identifier of the rate limit.", "type": "string", "example": "372e67954025e0ba6aaa6d586b9e0b59", "maxLength": 32, "readOnly": true }, "firewall_ratelimit": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/firewall_action" }, "bypass": { "$ref": "#/components/schemas/firewall_bypass" }, "description": { "$ref": "#/components/schemas/firewall_description" }, "disabled": { "$ref": "#/components/schemas/firewall_disabled" }, "id": { "$ref": "#/components/schemas/firewall_id" }, "match": { "$ref": "#/components/schemas/firewall_match" }, "period": { "$ref": "#/components/schemas/firewall_period" }, "threshold": { "$ref": "#/components/schemas/firewall_threshold" } } }, "firewall_ratelimit_response_collection": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/firewall_rate-limits" } } }, "type": "object" } ] }, "firewall_ratelimit_response_single": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/firewall_rate-limits" } }, "type": "object" } ] }, "firewall_ref": { "description": "A short reference tag. Allows you to select related firewall rules.", "type": "string", "example": "MIR-31", "maxLength": 50 }, "firewall_response_collection": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/firewall_schemas-rule" } } }, "type": "object" } ] }, "firewall_response_single": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/firewall_schemas-rule" } }, "type": "object" } ] }, "firewall_result_info": { "type": "object", "properties": { "count": { "description": "Defines the total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Defines the current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Defines the number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Defines the total results available without any search parameters.", "type": "number", "example": 2000 } } }, "firewall_rewrite_action": { "description": "Specifies that, when a WAF rule matches, its configured action will be replaced by the action configured in this object.", "type": "object", "properties": { "block": { "$ref": "#/components/schemas/firewall_waf_rewrite_action" }, "challenge": { "$ref": "#/components/schemas/firewall_waf_rewrite_action" }, "default": { "$ref": "#/components/schemas/firewall_waf_rewrite_action" }, "disable": { "$ref": "#/components/schemas/firewall_waf_rewrite_action" }, "simulate": { "$ref": "#/components/schemas/firewall_waf_rewrite_action" } } }, "firewall_rule": { "type": "object", "properties": { "allowed_modes": { "description": "The available actions that a rule can apply to a matched request.", "type": "array", "items": { "$ref": "#/components/schemas/firewall_schemas-mode" }, "example": [ "whitelist", "block", "challenge", "js_challenge", "managed_challenge" ], "readOnly": true }, "configuration": { "$ref": "#/components/schemas/firewall_configuration" }, "created_on": { "description": "The timestamp of when the rule was created.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true }, "id": { "$ref": "#/components/schemas/firewall_schemas-identifier" }, "mode": { "$ref": "#/components/schemas/firewall_schemas-mode" }, "modified_on": { "description": "The timestamp of when the rule was last modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true }, "notes": { "$ref": "#/components/schemas/firewall_notes" } }, "required": [ "id", "mode", "allowed_modes", "configuration" ] }, "firewall_rule_collection_response": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/firewall_rule" } } }, "type": "object" } ] }, "firewall_rule_identifier": { "description": "Unique identifier for a rule.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 }, "firewall_rule_single_id_response": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/firewall_schemas-identifier" } } } }, "type": "object" } ] }, "firewall_rule_single_response": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/firewall_rule" } }, "type": "object" } ] }, "firewall_rules": { "description": "An object that allows you to override the action of specific WAF rules. Each key of this object must be the ID of a WAF rule, and each value must be a valid WAF action. Unless you are disabling a rule, ensure that you also enable the rule group that this WAF rule belongs to. When creating a new URI-based WAF override, you must provide a `groups` object or a `rules` object.", "type": "object", "example": { "100015": "disable" }, "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/firewall_waf_action" } ], "example": "default" } }, "firewall_schemas-action": { "description": "The action to apply to a matched request. The `log` action is only available on an Enterprise plan.", "type": "string", "example": "block", "enum": [ "block", "challenge", "js_challenge", "managed_challenge", "allow", "log", "bypass" ] }, "firewall_schemas-cidr_configuration": { "type": "object", "properties": { "target": { "description": "The configuration target. You must set the target to `ip_range` when specifying an IP address range in the Zone Lockdown rule.", "type": "string", "example": "ip_range", "enum": [ "ip_range" ] }, "value": { "description": "The IP address range to match. You can only use prefix lengths `/16` and `/24`.", "type": "string", "example": "198.51.100.4/16" } }, "title": "An IP address range configuration." }, "firewall_schemas-configuration": { "description": "The configuration object for the current rule.", "type": "object", "properties": { "target": { "description": "The configuration target for this rule. You must set the target to `ua` for User Agent Blocking rules.", "type": "string", "example": "ua" }, "value": { "description": "The exact user agent string to match. This value will be compared to the received `User-Agent` HTTP header value.", "type": "string", "example": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/603.2.4 (KHTML, like Gecko) Version/10.1.1 Safari/603.2.4" } } }, "firewall_schemas-description": { "description": "A summary of the purpose/function of the WAF package.", "type": "string", "example": "null", "readOnly": true }, "firewall_schemas-description_search": { "description": "A string to search for in the description of existing rules.", "type": "string", "example": "endpoints", "x-auditable": true }, "firewall_schemas-identifier": { "description": "The unique identifier of the IP Access rule.", "type": "string", "example": "92f17202ed8bd63d69a66b86a49a8f6b", "maxLength": 32, "readOnly": true, "x-auditable": true }, "firewall_schemas-ip_configuration": { "type": "object", "properties": { "target": { "description": "The configuration target. You must set the target to `ip` when specifying an IP address in the Zone Lockdown rule.", "type": "string", "example": "ip", "enum": [ "ip" ] }, "value": { "description": "The IP address to match. This address will be compared to the IP address of incoming requests.", "type": "string", "example": "198.51.100.4" } }, "title": "An IP address configuration." }, "firewall_schemas-mode": { "description": "The action to apply to a matched request.", "type": "string", "example": "challenge", "enum": [ "block", "challenge", "whitelist", "js_challenge", "managed_challenge" ], "x-auditable": true }, "firewall_schemas-paused": { "description": "When true, indicates that the rule is currently paused.", "type": "boolean", "example": false, "x-auditable": true }, "firewall_schemas-priority": { "description": "The priority of the rule to control the processing order. A lower number indicates higher priority. If not provided, any rules with a configured priority will be processed before rules without a priority.", "type": "number", "example": 5, "x-auditable": true }, "firewall_schemas-ref": { "description": "A short reference tag. Allows you to select related filters.", "type": "string", "example": "FIL-100", "maxLength": 50 }, "firewall_schemas-rule": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/firewall_rule" }, { "properties": { "scope": { "description": "All zones owned by the user will have the rule applied.", "type": "object", "properties": { "email": { "$ref": "#/components/schemas/firewall_email" }, "id": { "$ref": "#/components/schemas/firewall_identifier" }, "type": { "description": "Defines the scope of the rule.", "type": "string", "example": "user", "enum": [ "user", "organization" ], "readOnly": true } }, "readOnly": true } }, "type": "object" } ], "required": [ "id", "mode", "allowed_modes", "configuration", "scope" ] }, "firewall_schemas-urls": { "description": "The URLs to include in the rule definition. You can use wildcards. Each entered URL will be escaped before use, which means you can only use simple wildcard patterns.", "type": "array", "items": { "example": "api.mysite.com/some/endpoint*", "type": "string", "x-auditable": true } }, "firewall_schemes": { "description": "The HTTP schemes to match. You can specify one scheme (`['HTTPS']`), both schemes (`['HTTP','HTTPS']`), or all schemes (`['_ALL_']`). This field is optional.", "type": "array", "items": { "description": "An HTTP scheme or `_ALL_` to indicate all schemes.", "example": "HTTPS", "type": "string" }, "example": [ "HTTP", "HTTPS" ], "x-auditable": true }, "firewall_sensitivity": { "description": "The sensitivity of the WAF package.", "type": "string", "default": "high", "enum": [ "high", "medium", "low", "off" ] }, "firewall_status": { "description": "When set to `active`, indicates that the WAF package will be applied to the zone.", "type": "string", "default": "active", "enum": [ "active" ], "readOnly": true }, "firewall_threshold": { "description": "The threshold that will trigger the configured mitigation action. Configure this value along with the `period` property to establish a threshold per period.", "type": "number", "example": 60, "minimum": 1, "x-auditable": true }, "firewall_timeout": { "description": "The time in seconds during which Cloudflare will perform the mitigation action. Must be an integer value greater than or equal to the period.\nNotes: If \"mode\" is \"challenge\", \"managed_challenge\", or \"js_challenge\", Cloudflare will use the zone's Challenge Passage time and you should not provide this value.", "type": "number", "example": 86400, "maximum": 86400, "minimum": 1, "x-auditable": true }, "firewall_ua_configuration": { "type": "object", "properties": { "target": { "description": "The configuration target. You must set the target to `ua` when specifying a user agent in the rule.", "type": "string", "example": "ua", "enum": [ "ua" ] }, "value": { "description": "the user agent to exactly match", "type": "string", "example": "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)", "x-auditable": true } }, "title": "A user agent configuration." }, "firewall_uri_search": { "description": "A single URI to search for in the list of URLs of existing rules.", "type": "string", "example": "/some/path", "x-auditable": true }, "firewall_url": { "description": "The URL pattern to match, composed of a host and a path such as `example.org/path*`. Normalization is applied before the pattern is matched. `*` wildcards are expanded to match applicable traffic. Query strings are not matched. Set the value to `*` to match all traffic to your zone.", "type": "string", "example": "*.example.org/path*", "maxLength": 1024, "x-auditable": true }, "firewall_urls": { "description": "The URLs to include in the current WAF override. You can use wildcards. Each entered URL will be escaped before use, which means you can only use simple wildcard patterns.", "type": "array", "items": { "example": "shop.example.com/*", "type": "string", "x-auditable": true } }, "firewall_waf_action": { "description": "The WAF rule action to apply.", "enum": [ "challenge", "block", "simulate", "disable", "default" ] }, "firewall_waf_rewrite_action": { "description": "The WAF rule action to apply.", "enum": [ "challenge", "block", "simulate", "disable", "default" ], "x-auditable": true }, "firewall_zonelockdown": { "type": "object", "properties": { "configurations": { "$ref": "#/components/schemas/firewall_configurations" }, "created_on": { "$ref": "#/components/schemas/firewall_created_on" }, "description": { "$ref": "#/components/schemas/firewall_lockdowns_components-schemas-description" }, "id": { "$ref": "#/components/schemas/firewall_lockdowns_components-schemas-id" }, "modified_on": { "$ref": "#/components/schemas/firewall_modified_on" }, "paused": { "$ref": "#/components/schemas/firewall_schemas-paused" }, "urls": { "$ref": "#/components/schemas/firewall_schemas-urls" } }, "additionalProperties": false, "required": [ "id", "created_on", "modified_on", "paused", "description", "urls", "configurations" ] }, "firewall_zonelockdown_response_collection": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/firewall_zonelockdown" } } }, "required": [ "result" ], "type": "object" } ] }, "firewall_zonelockdown_response_single": { "allOf": [ { "$ref": "#/components/schemas/firewall_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/firewall_zonelockdown" } }, "required": [ "result" ], "type": "object" } ] }, "flagship_ApiMessage": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "flagship_App": { "type": "object", "properties": { "created_at": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "description": "Email of the actor who last modified the app, or `unknown` when unavailable.", "type": "string" } }, "required": [ "id", "name", "created_at", "updated_at", "updated_by" ] }, "flagship_ChangelogEntry": { "oneOf": [ { "properties": { "after": { "$ref": "#/components/schemas/flagship_Flag" }, "event": { "type": "string", "enum": [ "create" ] }, "flag_key": { "type": "string" } }, "required": [ "flag_key", "event", "after" ], "type": "object" }, { "properties": { "after": { "$ref": "#/components/schemas/flagship_Flag" }, "event": { "type": "string", "enum": [ "delete" ] }, "flag_key": { "type": "string" } }, "required": [ "flag_key", "event", "after" ], "type": "object" }, { "properties": { "after": { "$ref": "#/components/schemas/flagship_Flag" }, "diff": { "type": "object", "additionalProperties": { "properties": { "from": { "$ref": "#/components/schemas/flagship_JsonValue" }, "to": { "$ref": "#/components/schemas/flagship_JsonValue" } }, "type": "object" } }, "event": { "type": "string", "enum": [ "update" ] }, "flag_key": { "type": "string" } }, "required": [ "flag_key", "event", "after", "diff" ], "type": "object" } ] }, "flagship_ChangelogPage": { "type": "array", "items": { "$ref": "#/components/schemas/flagship_ChangelogEntry" } }, "flagship_DeleteAppResult": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "flagship_DeleteFlagResult": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] }, "flagship_Error": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/flagship_ApiMessage" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/flagship_ApiMessage" } }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean" } }, "required": [ "success", "result", "errors", "messages" ] }, "flagship_EvaluationResult": { "type": "object", "properties": { "flagKey": { "type": "string" }, "reason": { "type": "string", "enum": [ "TARGETING_MATCH", "DEFAULT", "DISABLED", "SPLIT" ] }, "value": { "$ref": "#/components/schemas/flagship_JsonValue" }, "variant": { "type": "string" } }, "required": [ "flagKey", "variant", "reason" ] }, "flagship_Flag": { "type": "object", "properties": { "default_variation": { "description": "Variation the API serves when the flag is off, or when it's on but no rule matches the context. Must be a key in `variations`.", "type": "string", "minLength": 1 }, "description": { "type": "string", "maxLength": 512, "nullable": true }, "enabled": { "description": "When false, the flag bypasses all rules and always serves `default_variation`.", "type": "boolean" }, "key": { "description": "Unique identifier for the flag within an app. Used in all evaluation and SDK calls.", "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "rules": { "description": "Targeting rules evaluated in ascending `priority`; the first matching rule wins. An empty array means the flag always serves `default_variation`.", "type": "array", "items": { "additionalProperties": false, "properties": { "conditions": { "description": "Conditions the context must satisfy for this rule to match. An empty array matches all contexts.", "type": "array", "items": { "anyOf": [ { "additionalProperties": false, "properties": { "attribute": { "type": "string", "maxLength": 64, "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "greater_than", "less_than", "greater_than_or_equals", "less_than_or_equals", "contains", "starts_with", "ends_with", "in", "not_in" ] }, "value": { "$ref": "#/components/schemas/flagship_JsonValue" } }, "required": [ "attribute", "operator", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "clauses": { "type": "array", "items": { "anyOf": [ { "additionalProperties": false, "properties": { "attribute": { "type": "string", "maxLength": 64, "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "greater_than", "less_than", "greater_than_or_equals", "less_than_or_equals", "contains", "starts_with", "ends_with", "in", "not_in" ] }, "value": { "$ref": "#/components/schemas/flagship_JsonValue" } }, "required": [ "attribute", "operator", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "clauses": { "type": "array", "items": { "anyOf": [ { "additionalProperties": false, "properties": { "attribute": { "type": "string", "maxLength": 64, "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "greater_than", "less_than", "greater_than_or_equals", "less_than_or_equals", "contains", "starts_with", "ends_with", "in", "not_in" ] }, "value": { "$ref": "#/components/schemas/flagship_JsonValue" } }, "required": [ "attribute", "operator", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "clauses": { "type": "array", "items": { "anyOf": [ { "additionalProperties": false, "properties": { "attribute": { "type": "string", "maxLength": 64, "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "greater_than", "less_than", "greater_than_or_equals", "less_than_or_equals", "contains", "starts_with", "ends_with", "in", "not_in" ] }, "value": { "$ref": "#/components/schemas/flagship_JsonValue" } }, "required": [ "attribute", "operator", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "clauses": { "type": "array", "items": { "anyOf": [ { "additionalProperties": false, "properties": { "attribute": { "type": "string", "maxLength": 64, "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "greater_than", "less_than", "greater_than_or_equals", "less_than_or_equals", "contains", "starts_with", "ends_with", "in", "not_in" ] }, "value": { "$ref": "#/components/schemas/flagship_JsonValue" } }, "required": [ "attribute", "operator", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "clauses": { "type": "array", "items": { "anyOf": [ { "additionalProperties": false, "properties": { "attribute": { "type": "string", "maxLength": 64, "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "greater_than", "less_than", "greater_than_or_equals", "less_than_or_equals", "contains", "starts_with", "ends_with", "in", "not_in" ] }, "value": { "$ref": "#/components/schemas/flagship_JsonValue" } }, "required": [ "attribute", "operator", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "clauses": { "type": "array", "items": { "$ref": "#/components/schemas/flagship_JsonValue" }, "minItems": 1 }, "logical_operator": { "type": "string", "enum": [ "AND", "OR" ] } }, "required": [ "logical_operator", "clauses" ], "type": "object" } ] }, "minItems": 1 }, "logical_operator": { "type": "string", "enum": [ "AND", "OR" ] } }, "required": [ "logical_operator", "clauses" ], "type": "object" } ] }, "minItems": 1 }, "logical_operator": { "type": "string", "enum": [ "AND", "OR" ] } }, "required": [ "logical_operator", "clauses" ], "type": "object" } ] }, "minItems": 1 }, "logical_operator": { "type": "string", "enum": [ "AND", "OR" ] } }, "required": [ "logical_operator", "clauses" ], "type": "object" } ] }, "minItems": 1 }, "logical_operator": { "type": "string", "enum": [ "AND", "OR" ] } }, "required": [ "logical_operator", "clauses" ], "type": "object" } ] }, "minItems": 1 }, "logical_operator": { "type": "string", "enum": [ "AND", "OR" ] } }, "required": [ "logical_operator", "clauses" ], "type": "object" } ] } }, "priority": { "description": "Evaluation order: the API evaluates rules with lower numbers first. Must be unique across the flag's rules.", "type": "integer", "minimum": 1 }, "rollout": { "type": "object", "additionalProperties": false, "properties": { "attribute": { "description": "Context attribute used for sticky bucketing. Defaults to `targetingKey`. If absent at evaluation time, bucketing is random per request.", "type": "string", "minLength": 1 }, "percentage": { "description": "Percentage of matching traffic (0–100) served this variation. For multi-way splits, use cumulative upper bounds across rules (e.g. 30, 70, 100).", "type": "number", "maximum": 100, "minimum": 0 } }, "required": [ "percentage" ] }, "serve_variation": { "description": "Variation the API serves when this rule matches. Must be a key in `variations`.", "type": "string", "minLength": 1 } }, "required": [ "priority", "conditions", "serve_variation" ], "type": "object" } }, "type": { "description": "Server-inferred value type shared by all of the flag's variations.", "type": "string", "enum": [ "boolean", "string", "number", "json" ], "x-stainless-terraform-configurability": "computed_optional" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" }, "variations": { "description": "Map of variation name to value. All values share the same type (boolean, string, number, or JSON object/array), and each serialized value stays within 10KB.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/flagship_JsonValue" } } }, "additionalProperties": false, "required": [ "key", "type", "default_variation", "variations", "rules", "enabled" ] }, "flagship_FlagDefinitions": { "type": "object", "properties": { "flags": { "type": "object", "additionalProperties": { "properties": { "default_variation": { "description": "Variation the API serves when the flag is off, or when it's on but no rule matches the context. Must be a key in `variations`.", "type": "string", "minLength": 1 }, "enabled": { "description": "When false, the flag bypasses all rules and always serves `default_variation`.", "type": "boolean" }, "key": { "description": "Unique identifier for the flag within an app. Used in all evaluation and SDK calls.", "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "rules": { "type": "array", "items": { "additionalProperties": false, "properties": { "conditions": { "description": "Conditions the context must satisfy for this rule to match. An empty array matches all contexts.", "type": "array", "items": { "anyOf": [ { "additionalProperties": false, "properties": { "attribute": { "type": "string", "maxLength": 64, "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "greater_than", "less_than", "greater_than_or_equals", "less_than_or_equals", "contains", "starts_with", "ends_with", "in", "not_in" ] }, "value": { "$ref": "#/components/schemas/flagship_JsonValue" } }, "required": [ "attribute", "operator", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "clauses": { "type": "array", "items": { "anyOf": [ { "additionalProperties": false, "properties": { "attribute": { "type": "string", "maxLength": 64, "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "greater_than", "less_than", "greater_than_or_equals", "less_than_or_equals", "contains", "starts_with", "ends_with", "in", "not_in" ] }, "value": { "$ref": "#/components/schemas/flagship_JsonValue" } }, "required": [ "attribute", "operator", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "clauses": { "type": "array", "items": { "anyOf": [ { "additionalProperties": false, "properties": { "attribute": { "type": "string", "maxLength": 64, "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "greater_than", "less_than", "greater_than_or_equals", "less_than_or_equals", "contains", "starts_with", "ends_with", "in", "not_in" ] }, "value": { "$ref": "#/components/schemas/flagship_JsonValue" } }, "required": [ "attribute", "operator", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "clauses": { "type": "array", "items": { "anyOf": [ { "additionalProperties": false, "properties": { "attribute": { "type": "string", "maxLength": 64, "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "greater_than", "less_than", "greater_than_or_equals", "less_than_or_equals", "contains", "starts_with", "ends_with", "in", "not_in" ] }, "value": { "$ref": "#/components/schemas/flagship_JsonValue" } }, "required": [ "attribute", "operator", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "clauses": { "type": "array", "items": { "anyOf": [ { "additionalProperties": false, "properties": { "attribute": { "type": "string", "maxLength": 64, "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "greater_than", "less_than", "greater_than_or_equals", "less_than_or_equals", "contains", "starts_with", "ends_with", "in", "not_in" ] }, "value": { "$ref": "#/components/schemas/flagship_JsonValue" } }, "required": [ "attribute", "operator", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "clauses": { "type": "array", "items": { "anyOf": [ { "additionalProperties": false, "properties": { "attribute": { "type": "string", "maxLength": 64, "minLength": 1 }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "greater_than", "less_than", "greater_than_or_equals", "less_than_or_equals", "contains", "starts_with", "ends_with", "in", "not_in" ] }, "value": { "$ref": "#/components/schemas/flagship_JsonValue" } }, "required": [ "attribute", "operator", "value" ], "type": "object" }, { "additionalProperties": false, "properties": { "clauses": { "type": "array", "items": { "$ref": "#/components/schemas/flagship_JsonValue" }, "minItems": 1 }, "logical_operator": { "type": "string", "enum": [ "AND", "OR" ] } }, "required": [ "logical_operator", "clauses" ], "type": "object" } ] }, "minItems": 1 }, "logical_operator": { "type": "string", "enum": [ "AND", "OR" ] } }, "required": [ "logical_operator", "clauses" ], "type": "object" } ] }, "minItems": 1 }, "logical_operator": { "type": "string", "enum": [ "AND", "OR" ] } }, "required": [ "logical_operator", "clauses" ], "type": "object" } ] }, "minItems": 1 }, "logical_operator": { "type": "string", "enum": [ "AND", "OR" ] } }, "required": [ "logical_operator", "clauses" ], "type": "object" } ] }, "minItems": 1 }, "logical_operator": { "type": "string", "enum": [ "AND", "OR" ] } }, "required": [ "logical_operator", "clauses" ], "type": "object" } ] }, "minItems": 1 }, "logical_operator": { "type": "string", "enum": [ "AND", "OR" ] } }, "required": [ "logical_operator", "clauses" ], "type": "object" } ] } }, "rollout": { "type": "object", "additionalProperties": false, "properties": { "attribute": { "description": "Context attribute used for sticky bucketing. Defaults to `targetingKey`. If absent at evaluation time, bucketing is random per request.", "type": "string", "minLength": 1 }, "percentage": { "description": "Percentage of matching traffic (0–100) served this variation. For multi-way splits, use cumulative upper bounds across rules (e.g. 30, 70, 100).", "type": "number", "maximum": 100, "minimum": 0 } }, "required": [ "percentage" ] }, "serve_variation": { "description": "Variation the API serves when this rule matches. Must be a key in `variations`.", "type": "string", "minLength": 1 } }, "required": [ "conditions", "serve_variation" ], "type": "object" } }, "variations": { "description": "Map of variation name to value. All values share the same type (boolean, string, number, or JSON object/array), and each serialized value stays within 10KB.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/flagship_JsonValue" } } }, "required": [ "key", "enabled", "default_variation", "variations", "rules" ], "type": "object" } } }, "required": [ "flags" ] }, "flagship_FlagsPage": { "type": "array", "items": { "$ref": "#/components/schemas/flagship_Flag" } }, "flagship_JsonValue": { "oneOf": [ { "nullable": true, "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "additionalProperties": { "$ref": "#/components/schemas/flagship_JsonValue" }, "type": "object" }, { "items": { "$ref": "#/components/schemas/flagship_JsonValue" }, "type": "array" } ] }, "flagship_ResultInfo": { "type": "object", "properties": { "count": { "description": "Number of items returned in this page.", "type": "integer", "minimum": 0 }, "cursor": { "description": "Cursor to pass back to fetch the next page, or null when this is the last page.", "type": "string", "nullable": true } }, "required": [ "count", "cursor" ] }, "fraud_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/fraud_messages" }, "messages": { "$ref": "#/components/schemas/fraud_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "fraud_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/fraud_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/fraud_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "fraud_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/fraud_api-response-common" } ] }, "fraud_auth_criteria": { "description": "A criterion for determining authentication outcome. The `kind` field determines which\nother fields are used for matching.\n", "type": "object", "properties": { "kind": { "description": "The type of criterion. Currently only `status_code` is supported.", "type": "string", "example": "status_code", "enum": [ "status_code" ], "x-auditable": true }, "status_codes": { "description": "HTTP status codes to match against the origin response.\n- Maximum of 10 codes per criterion.\n- Each code must be a valid HTTP status code (100-599).\n- Codes are deduplicated and sorted on save.\n- Omit to leave unchanged on update.\n- Provide an empty array `[]` to clear codes on update.\n", "type": "array", "items": { "maximum": 599, "minimum": 100, "type": "integer" }, "example": [ 200, 201 ], "maxItems": 10, "x-auditable": true } }, "additionalProperties": false, "required": [ "kind" ] }, "fraud_authentication_settings": { "description": "Configuration for classifying login authentication outcomes based on the origin response.\nRequires `user_profiles` to be enabled.\n\n- Success and failure criteria are independently updatable — sending only `success_criteria`\n leaves failure codes untouched, and vice versa.\n- Omit `authentication_settings` entirely to leave both unchanged.\n- Status codes must not overlap between success and failure criteria.\n", "type": "object", "properties": { "failure_criteria": { "description": "Criterion for identifying failed login responses.", "allOf": [ { "$ref": "#/components/schemas/fraud_auth_criteria" } ] }, "success_criteria": { "description": "Criterion for identifying successful login responses.", "allOf": [ { "$ref": "#/components/schemas/fraud_auth_criteria" } ] } }, "additionalProperties": false }, "fraud_fraud_settings": { "type": "object", "properties": { "authentication_settings": { "$ref": "#/components/schemas/fraud_authentication_settings" }, "user_profiles": { "$ref": "#/components/schemas/fraud_user_profiles_status" }, "username_expressions": { "$ref": "#/components/schemas/fraud_username_expressions" } }, "additionalProperties": false }, "fraud_fraud_settings_response_body": { "allOf": [ { "$ref": "#/components/schemas/fraud_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/fraud_fraud_settings" } }, "type": "object" } ] }, "fraud_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "fraud_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "fraud_user_profiles_status": { "description": "Whether Fraud User Profiles is enabled for the zone.", "type": "string", "example": "disabled", "enum": [ "enabled", "disabled" ], "x-auditable": true }, "fraud_username_expressions": { "description": "List of expressions to detect usernames in write HTTP requests.\n\n- Maximum of 10 expressions.\n- Omit or set to null to leave unchanged on update.\n- Provide an empty array `[]` to clear all expressions on update.\n- Invalid expressions will result in a 10400 Bad Request with details in the `messages` array.\n", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "http.request.body.form[\"username\"][0]", "lookup_json_string(http.request.body.raw, \"username\")" ], "maxItems": 10 }, "google-tag-gateway_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/google-tag-gateway_messages" }, "messages": { "$ref": "#/components/schemas/google-tag-gateway_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "google-tag-gateway_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/google-tag-gateway_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/google-tag-gateway_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "google-tag-gateway_google-tag-gateway-config": { "description": "Google Tag Gateway configuration for a zone.", "type": "object", "properties": { "enabled": { "description": "Enables or disables Google Tag Gateway for this zone.", "type": "boolean", "example": true, "x-auditable": true }, "endpoint": { "description": "Specifies the endpoint path for proxying Google Tag Manager requests. Use an absolute path starting with '/', with no nested paths and alphanumeric characters only (e.g. /metrics).", "type": "string", "example": "/metrics", "x-auditable": true }, "hideOriginalIp": { "description": "Hides the original client IP address from Google when enabled.", "type": "boolean", "example": true, "x-auditable": true }, "measurementId": { "description": "Specify the Google Tag Manager container or measurement ID (e.g. GTM-XXXXXXX or G-XXXXXXXXXX).", "type": "string", "example": "GTM-P2F3N47Q", "x-auditable": true }, "setUpTag": { "description": "Set up the associated Google Tag on the zone automatically when enabled.", "type": "boolean", "example": true, "nullable": true, "x-auditable": true } }, "required": [ "enabled", "endpoint", "hideOriginalIp", "measurementId" ], "title": "Google Tag Gateway configuration" }, "google-tag-gateway_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "google-tag-gateway_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "google-tag-gateway_zone-identifier": { "$ref": "#/components/schemas/google-tag-gateway_identifier" }, "healthchecks_address": { "description": "The hostname or IP address of the origin server to run health checks on.", "type": "string", "example": "www.example.com", "x-auditable": true }, "healthchecks_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/healthchecks_api-response-common" }, { "properties": { "result": { "type": "array", "items": {}, "nullable": true }, "result_info": { "$ref": "#/components/schemas/healthchecks_result_info" } } } ] }, "healthchecks_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/healthchecks_messages" }, "messages": { "$ref": "#/components/schemas/healthchecks_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": {}, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "healthchecks_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/healthchecks_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/healthchecks_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "healthchecks_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/healthchecks_api-response-common" }, { "properties": { "result": { "oneOf": [ { "type": "object" }, { "type": "string" } ] } }, "type": "object" } ] }, "healthchecks_check_regions": { "description": "A list of regions from which to run health checks. Null means Cloudflare will pick a default region.", "type": "array", "items": { "description": "WNAM: Western North America, ENAM: Eastern North America, WEU: Western Europe, EEU: Eastern Europe, NSAM: Northern South America, SSAM: Southern South America, OC: Oceania, ME: Middle East, NAF: North Africa, SAF: South Africa, IN: India, SEAS: South East Asia, NEAS: North East Asia, ALL_REGIONS: all regions (BUSINESS and ENTERPRISE customers only).", "enum": [ "WNAM", "ENAM", "WEU", "EEU", "NSAM", "SSAM", "OC", "ME", "NAF", "SAF", "IN", "SEAS", "NEAS", "ALL_REGIONS" ], "type": "string" }, "example": [ "WEU", "ENAM" ], "nullable": true, "x-auditable": true }, "healthchecks_consecutive_fails": { "description": "The number of consecutive fails required from a health check before changing the health to unhealthy.", "type": "integer", "default": 1, "x-auditable": true }, "healthchecks_consecutive_successes": { "description": "The number of consecutive successes required from a health check before changing the health to healthy.", "type": "integer", "default": 1, "x-auditable": true }, "healthchecks_description": { "description": "A human-readable description of the health check.", "type": "string", "example": "Health check for www.example.com", "x-auditable": true }, "healthchecks_failure_reason": { "description": "The current failure reason if status is unhealthy.", "type": "string", "example": "", "readOnly": true, "x-auditable": true }, "healthchecks_healthchecks": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/healthchecks_address" }, "check_regions": { "$ref": "#/components/schemas/healthchecks_check_regions" }, "consecutive_fails": { "$ref": "#/components/schemas/healthchecks_consecutive_fails" }, "consecutive_successes": { "$ref": "#/components/schemas/healthchecks_consecutive_successes" }, "created_on": { "$ref": "#/components/schemas/healthchecks_timestamp" }, "description": { "$ref": "#/components/schemas/healthchecks_description" }, "failure_reason": { "$ref": "#/components/schemas/healthchecks_failure_reason" }, "http_config": { "$ref": "#/components/schemas/healthchecks_http_config" }, "id": { "$ref": "#/components/schemas/healthchecks_identifier" }, "interval": { "$ref": "#/components/schemas/healthchecks_interval" }, "modified_on": { "$ref": "#/components/schemas/healthchecks_timestamp" }, "name": { "$ref": "#/components/schemas/healthchecks_name" }, "retries": { "$ref": "#/components/schemas/healthchecks_retries" }, "status": { "$ref": "#/components/schemas/healthchecks_status" }, "suspended": { "$ref": "#/components/schemas/healthchecks_suspended" }, "tcp_config": { "$ref": "#/components/schemas/healthchecks_tcp_config" }, "timeout": { "$ref": "#/components/schemas/healthchecks_timeout" }, "type": { "$ref": "#/components/schemas/healthchecks_type" } } }, "healthchecks_http_config": { "description": "Parameters specific to an HTTP or HTTPS health check.", "type": "object", "properties": { "allow_insecure": { "description": "Do not validate the certificate when the health check uses HTTPS.", "type": "boolean", "default": false, "x-auditable": true }, "expected_body": { "description": "A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy.", "type": "string", "example": "success", "default": "", "x-auditable": true }, "expected_codes": { "description": "The expected HTTP response codes (e.g. \"200\") or code ranges (e.g. \"2xx\" for all codes starting with 2) of the health check.", "type": "array", "items": { "type": "string" }, "example": [ "2xx", "302" ], "default": "200", "nullable": true, "x-auditable": true }, "follow_redirects": { "description": "Follow redirects if the origin returns a 3xx status code.", "type": "boolean", "default": false, "x-auditable": true }, "header": { "description": "The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden.", "type": "object", "example": { "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] }, "additionalProperties": { "items": { "type": "string", "x-auditable": true }, "type": "array" }, "nullable": true }, "method": { "description": "The HTTP method to use for the health check.", "type": "string", "default": "GET", "enum": [ "GET", "HEAD" ], "x-auditable": true }, "path": { "description": "The endpoint path to health check against.", "type": "string", "example": "/health", "default": "/", "x-auditable": true }, "port": { "description": "Port number to connect to for the health check. Defaults to 80 if type is HTTP or 443 if type is HTTPS.", "type": "integer", "default": 80, "x-auditable": true } }, "nullable": true }, "healthchecks_id_response": { "allOf": [ { "$ref": "#/components/schemas/healthchecks_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/healthchecks_identifier" } } } }, "type": "object" } ] }, "healthchecks_identifier": { "description": "Identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "healthchecks_interval": { "description": "The interval between each health check. Shorter intervals may give quicker notifications if the origin status changes, but will increase load on the origin as we check from multiple locations.", "type": "integer", "default": 60, "x-auditable": true }, "healthchecks_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "healthchecks_name": { "description": "A short name to identify the health check. Only alphanumeric characters, hyphens and underscores are allowed.", "type": "string", "example": "server-1", "x-auditable": true }, "healthchecks_query_healthcheck": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/healthchecks_address" }, "check_regions": { "$ref": "#/components/schemas/healthchecks_check_regions" }, "consecutive_fails": { "$ref": "#/components/schemas/healthchecks_consecutive_fails" }, "consecutive_successes": { "$ref": "#/components/schemas/healthchecks_consecutive_successes" }, "description": { "$ref": "#/components/schemas/healthchecks_description" }, "http_config": { "$ref": "#/components/schemas/healthchecks_http_config" }, "interval": { "$ref": "#/components/schemas/healthchecks_interval" }, "name": { "$ref": "#/components/schemas/healthchecks_name" }, "retries": { "$ref": "#/components/schemas/healthchecks_retries" }, "suspended": { "$ref": "#/components/schemas/healthchecks_suspended" }, "tcp_config": { "$ref": "#/components/schemas/healthchecks_tcp_config" }, "timeout": { "$ref": "#/components/schemas/healthchecks_timeout" }, "type": { "$ref": "#/components/schemas/healthchecks_type" } }, "required": [ "name", "address" ] }, "healthchecks_response_collection": { "allOf": [ { "$ref": "#/components/schemas/healthchecks_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/healthchecks_healthchecks" } } } } ] }, "healthchecks_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters", "type": "number", "example": 2000 } } }, "healthchecks_retries": { "description": "The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately.", "type": "integer", "default": 2, "x-auditable": true }, "healthchecks_single_response": { "allOf": [ { "$ref": "#/components/schemas/healthchecks_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/healthchecks_healthchecks" } }, "type": "object" } ] }, "healthchecks_status": { "description": "The current status of the origin server according to the health check.", "type": "string", "example": "healthy", "enum": [ "unknown", "healthy", "unhealthy", "suspended" ], "readOnly": true, "x-auditable": true }, "healthchecks_suspended": { "description": "If suspended, no health checks are sent to the origin.", "type": "boolean", "default": false, "x-auditable": true }, "healthchecks_tcp_config": { "description": "Parameters specific to TCP health check.", "type": "object", "properties": { "method": { "description": "The TCP connection method to use for the health check.", "type": "string", "default": "connection_established", "enum": [ "connection_established" ], "x-auditable": true }, "port": { "description": "Port number to connect to for the health check. Defaults to 80.", "type": "integer", "default": 80, "x-auditable": true } }, "nullable": true }, "healthchecks_timeout": { "description": "The timeout (in seconds) before marking the health check as failed.", "type": "integer", "default": 5, "x-auditable": true }, "healthchecks_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true, "x-auditable": true }, "healthchecks_type": { "description": "The protocol to use for the health check. Currently supported protocols are 'HTTP', 'HTTPS' and 'TCP'.", "type": "string", "example": "HTTPS", "default": "HTTP", "x-auditable": true }, "hyperdrive_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/hyperdrive_api-response-common" }, { "properties": { "result_info": { "$ref": "#/components/schemas/hyperdrive_result_info" } }, "type": "object" } ] }, "hyperdrive_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/hyperdrive_messages" }, "messages": { "$ref": "#/components/schemas/hyperdrive_messages" }, "result": { "type": "object" }, "success": { "description": "Return the status of the API call success.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "hyperdrive_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/hyperdrive_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/hyperdrive_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Return the status of the API call success.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "hyperdrive_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/hyperdrive_api-response-common" } ] }, "hyperdrive_hyperdrive-caching": { "type": "object", "discriminator": { "mapping": { "false": "#/components/schemas/hyperdrive_hyperdrive-caching-enabled", "true": "#/components/schemas/hyperdrive_hyperdrive-caching-disabled" }, "propertyName": "disabled" }, "oneOf": [ { "$ref": "#/components/schemas/hyperdrive_hyperdrive-caching-disabled" }, { "$ref": "#/components/schemas/hyperdrive_hyperdrive-caching-enabled" } ] }, "hyperdrive_hyperdrive-caching-common": { "type": "object", "properties": { "disabled": { "description": "Set to true to disable caching of SQL responses. Default is false.", "type": "boolean", "x-auditable": true } } }, "hyperdrive_hyperdrive-caching-disabled": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/hyperdrive_hyperdrive-caching-common" } ] }, "hyperdrive_hyperdrive-caching-enabled": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/hyperdrive_hyperdrive-caching-common" }, { "properties": { "max_age": { "description": "Specify the maximum duration (in seconds) items should persist in the cache. Defaults to 60 seconds if not specified.", "type": "integer", "example": 60, "x-auditable": true }, "stale_while_revalidate": { "description": "Specify the number of seconds the cache may serve a stale response. Defaults to 15 seconds if not specified.", "type": "integer", "example": 15, "x-auditable": true } }, "type": "object" } ] }, "hyperdrive_hyperdrive-config": { "type": "object", "properties": { "caching": { "$ref": "#/components/schemas/hyperdrive_hyperdrive-caching" }, "created_on": { "description": "Defines the creation time of the Hyperdrive configuration.", "type": "string", "format": "date-time", "example": "2017-01-01T00:00:00Z", "readOnly": true, "x-auditable": true }, "id": { "$ref": "#/components/schemas/hyperdrive_identifier" }, "modified_on": { "description": "Defines the last modified time of the Hyperdrive configuration.", "type": "string", "format": "date-time", "example": "2017-01-01T00:00:00Z", "readOnly": true, "x-auditable": true }, "mtls": { "$ref": "#/components/schemas/hyperdrive_hyperdrive-mtls" }, "name": { "$ref": "#/components/schemas/hyperdrive_hyperdrive-name" }, "origin": { "type": "object", "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/hyperdrive_hyperdrive-database-full" }, { "$ref": "#/components/schemas/hyperdrive_internet-origin" } ], "title": "Public Database" }, { "allOf": [ { "$ref": "#/components/schemas/hyperdrive_hyperdrive-database-full" }, { "$ref": "#/components/schemas/hyperdrive_over-access-origin" } ], "title": "Access-protected Database behind Cloudflare Tunnel" }, { "allOf": [ { "$ref": "#/components/schemas/hyperdrive_hyperdrive-database-full" }, { "$ref": "#/components/schemas/hyperdrive_vpc-service-origin" } ], "title": "Database reachable through a Workers VPC" } ] }, "origin_connection_limit": { "$ref": "#/components/schemas/hyperdrive_hyperdrive-origin-connection-limit" }, "restarted_on": { "description": "Defines the last time the Hyperdrive connection pool was explicitly restarted via the restart endpoint. Omitted if the pool has never been explicitly restarted.", "type": "string", "format": "date-time", "example": "2017-01-01T00:00:00Z", "nullable": true, "readOnly": true, "x-auditable": true } }, "required": [ "id", "name", "origin" ] }, "hyperdrive_hyperdrive-config-patch": { "type": "object", "properties": { "caching": { "$ref": "#/components/schemas/hyperdrive_hyperdrive-caching" }, "mtls": { "$ref": "#/components/schemas/hyperdrive_hyperdrive-mtls" }, "name": { "$ref": "#/components/schemas/hyperdrive_hyperdrive-name" }, "origin": { "type": "object", "anyOf": [ { "$ref": "#/components/schemas/hyperdrive_hyperdrive-database" }, { "oneOf": [ { "$ref": "#/components/schemas/hyperdrive_internet-origin" }, { "$ref": "#/components/schemas/hyperdrive_over-access-origin" }, { "$ref": "#/components/schemas/hyperdrive_vpc-service-origin" } ], "title": "Origin Database" } ] }, "origin_connection_limit": { "$ref": "#/components/schemas/hyperdrive_hyperdrive-origin-connection-limit" } } }, "hyperdrive_hyperdrive-config-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/hyperdrive_hyperdrive-config" } ], "required": [ "caching" ] }, "hyperdrive_hyperdrive-database": { "type": "object", "properties": { "database": { "description": "Set the name of your origin database.", "type": "string", "example": "postgres", "x-auditable": true }, "password": { "description": "Set the password needed to access your origin database. The API never returns this write-only value.", "type": "string", "writeOnly": true, "x-sensitive": true }, "scheme": { "$ref": "#/components/schemas/hyperdrive_hyperdrive-scheme" }, "user": { "description": "Set the user of your origin database.", "type": "string", "example": "postgres", "x-auditable": true } }, "title": "Connection Options" }, "hyperdrive_hyperdrive-database-full": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/hyperdrive_hyperdrive-database" } ], "required": [ "scheme", "database", "user", "password" ] }, "hyperdrive_hyperdrive-database-signature-response": { "type": "object", "properties": { "account_id": { "description": "The Cloudflare account the signature authorizes. This is the identifier the signature is computed over, and is passed to the integration partner's CLI.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "signature": { "description": "Hex-encoded signature authorizing the database creation.", "type": "string", "example": "9f2b8c1d4e6a7b3c5d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c" }, "timestamp": { "description": "Unix timestamp, in seconds, at which the signature was issued. The integration partner uses it to verify the signature and reject stale authorizations.", "type": "string", "example": "1700000000", "x-auditable": true } }, "required": [ "account_id", "timestamp", "signature" ] }, "hyperdrive_hyperdrive-integration": { "description": "The database integration that bills the new database through Cloudflare.", "type": "string", "example": "planetScale", "enum": [ "planetScale" ], "x-auditable": true }, "hyperdrive_hyperdrive-mtls": { "description": "mTLS configuration for the origin connection. Cannot be used with VPC Service origins; TLS must be managed on the VPC Service.", "type": "object", "properties": { "ca_certificate_id": { "description": "Define CA certificate ID obtained after uploading CA cert.", "type": "string", "example": "00000000-0000-0000-0000-0000000000" }, "mtls_certificate_id": { "description": "Define mTLS certificate ID obtained after uploading client cert.", "type": "string", "example": "00000000-0000-0000-0000-0000000000" }, "sslmode": { "description": "Set SSL mode to 'require', 'verify-ca', or 'verify-full' to verify the CA.", "type": "string", "example": "verify-full" } }, "title": "mTLS" }, "hyperdrive_hyperdrive-name": { "description": "The name of the Hyperdrive configuration. Used to identify the configuration in the Cloudflare dashboard and API.", "type": "string", "example": "example-hyperdrive", "x-auditable": true }, "hyperdrive_hyperdrive-origin": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/hyperdrive_hyperdrive-database" }, { "oneOf": [ { "$ref": "#/components/schemas/hyperdrive_internet-origin" }, { "$ref": "#/components/schemas/hyperdrive_over-access-origin" }, { "$ref": "#/components/schemas/hyperdrive_vpc-service-origin" } ] } ] }, "hyperdrive_hyperdrive-origin-connection-limit": { "description": "The (soft) maximum number of connections the Hyperdrive is allowed to make to the origin database.\n\nMaximum allowed: 20 for free tier accounts, 100 for paid tier accounts.\nIf not specified, defaults to 20 for free tier and 60 for paid tier.\nCertain Cloudflare-managed origins may be permitted a higher limit.\nContact Cloudflare if you need a higher limit.\n", "type": "integer", "example": 60, "minimum": 5, "x-auditable": true }, "hyperdrive_hyperdrive-scheme": { "description": "Specifies the URL scheme used to connect to your origin database.", "type": "string", "enum": [ "postgres", "postgresql", "mysql" ], "x-auditable": true }, "hyperdrive_identifier": { "description": "Define configurations using a unique string identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "hyperdrive_internet-origin": { "type": "object", "properties": { "host": { "description": "Defines the host (hostname or IP) of your origin database.", "type": "string", "example": "database.example.com", "x-auditable": true }, "port": { "description": "Defines the port of your origin database. Defaults to 5432 for PostgreSQL or 3306 for MySQL if not specified.", "type": "integer", "example": 5432, "x-auditable": true } }, "required": [ "host", "port" ], "title": "Public Database" }, "hyperdrive_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "hyperdrive_over-access-origin": { "type": "object", "properties": { "access_client_id": { "description": "Defines the Client ID of the Access token to use when connecting to the origin database.", "type": "string", "example": "0123456789abcdef0123456789abcdef.access", "x-auditable": true }, "access_client_secret": { "description": "Defines the Client Secret of the Access Token to use when connecting to the origin database. The API never returns this write-only value.", "type": "string", "example": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "writeOnly": true, "x-sensitive": true }, "host": { "description": "Defines the host (hostname or IP) of your origin database.", "type": "string", "example": "database.example.com", "x-auditable": true } }, "required": [ "host", "access_client_id", "access_client_secret" ], "title": "Access-protected Database behind Cloudflare Tunnel" }, "hyperdrive_result_info": { "type": "object", "properties": { "count": { "description": "Defines the total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Defines the current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Defines the number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Defines the total results available without any search parameters.", "type": "number", "example": 2000 } } }, "hyperdrive_vpc-service-origin": { "description": "Connect to a database through a Workers VPC Service. TLS settings (mTLS, sslmode) cannot be configured on the Hyperdrive when using a VPC Service origin; TLS must be managed on the VPC Service itself.\n", "type": "object", "properties": { "service_id": { "description": "The identifier of the Workers VPC Service to connect through. Hyperdrive will egress through the specified VPC Service to reach the origin database.", "type": "string", "example": "0123456789abcdef0123456789abcdef", "x-auditable": true } }, "required": [ "service_id" ], "title": "Database reachable through a Workers VPC" }, "iam_access": { "description": "Allow or deny operations against the resources.", "type": "string", "example": "allow", "enum": [ "allow", "deny" ], "x-auditable": true }, "iam_account": { "type": "object", "properties": { "created_on": { "description": "Timestamp for the creation of the account", "type": "string", "format": "date-time", "example": "2014-03-01T12:21:02Z", "readOnly": true, "x-auditable": true }, "id": { "$ref": "#/components/schemas/iam_common_components-schemas-identifier" }, "managed_by": { "description": "Parent container details", "type": "object", "properties": { "parent_org_id": { "description": "ID of the parent Organization, if one exists", "type": "string", "example": "4536bcfad5faccb111b47003c79917fa", "maxLength": 32, "readOnly": true, "x-auditable": true }, "parent_org_name": { "description": "Name of the parent Organization, if one exists", "type": "string", "example": "Demo Parent Organization", "readOnly": true, "x-auditable": true } } }, "name": { "description": "Account name", "type": "string", "example": "Demo Account", "maxLength": 100, "x-auditable": true }, "settings": { "description": "Account settings", "type": "object", "properties": { "abuse_contact_email": { "description": "Sets an abuse contact email to notify for abuse reports.", "type": "string", "x-auditable": true }, "enforce_twofactor": { "description": "Indicates whether membership in this account requires that\nTwo-Factor Authentication is enabled", "type": "boolean", "default": false, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } } }, "type": { "$ref": "#/components/schemas/iam_account-type" } }, "required": [ "id", "name", "type" ] }, "iam_account-type": { "enum": [ "standard", "enterprise" ] }, "iam_account_identifier": { "description": "Account identifier tag.", "allOf": [ { "$ref": "#/components/schemas/iam_common_components-schemas-identifier" } ], "title": "Account Identifier" }, "iam_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/iam_api-response-common" }, { "properties": { "result_info": { "$ref": "#/components/schemas/iam_result_info" } } } ] }, "iam_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/iam_messages-2" }, "messages": { "$ref": "#/components/schemas/iam_messages-2" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "iam_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/iam_messages-2" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/iam_messages-2" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "iam_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/iam_api-response-common" } ] }, "iam_api-response-single-id": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/iam_api-response-common" }, { "properties": { "result": { "type": "object", "nullable": true, "properties": { "id": { "$ref": "#/components/schemas/iam_common_components-schemas-identifier" } }, "required": [ "id" ] } } } ] }, "iam_api_access_enabled": { "description": "Enterprise only. Indicates whether or not API access is enabled specifically for this user on a given account.", "type": "boolean", "example": true, "nullable": true, "x-auditable": true }, "iam_cidr_list": { "description": "List of IPv4/IPv6 CIDR addresses.", "type": "array", "items": { "description": "IPv4/IPv6 CIDR.", "example": "199.27.128.0/21", "type": "string", "x-auditable": true }, "example": [ "199.27.128.0/21", "2400:cb00::/32" ] }, "iam_code": { "description": "The unique activation code for the account membership.", "type": "string", "example": "05dd05cce12bbed97c0d87cd78e89bc2fd41a6cee72f27f6fc84af2e45c0fac0", "maxLength": 64, "readOnly": true }, "iam_collection_member_response_with_policies": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/iam_member_with_policies" } } }, "type": "object" } ], "title": "Members with Policies" }, "iam_collection_membership_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/iam_membership" } } }, "type": "object" } ], "title": "memberships_with_roles" }, "iam_collection_membership_response_with_policies": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/iam_membership-with-policies" } } }, "type": "object" } ], "title": "memberships_with_policies" }, "iam_collection_oauth_client_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/iam_oauth_client" } } }, "type": "object" } ], "title": "List OAuth Clients Response" }, "iam_collection_oauth_scopes_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/iam_oauth_scope" } } }, "type": "object" } ], "title": "List OAuth Scopes Response" }, "iam_collection_organization_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/iam_organization" } } }, "type": "object" } ] }, "iam_collection_permission_groups_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-collection" }, { "properties": { "result": { "$ref": "#/components/schemas/iam_permission_groups" } }, "type": "object" } ], "title": "List of Resource groups" }, "iam_collection_role_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/iam_role" } } }, "type": "object" } ] }, "iam_collection_tokens_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/iam_token_base" } } }, "type": "object" } ], "title": "Response with a list of tokens" }, "iam_common_components-schemas-identifier": { "description": "Identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "minLength": 32, "x-auditable": true }, "iam_components-schemas-account": { "allOf": [ { "$ref": "#/components/schemas/iam_account" } ] }, "iam_components-schemas-status": { "description": "Whether the user is a member of the organization or has an invitation pending.", "type": "string", "example": "member", "enum": [ "member", "invited" ], "x-auditable": true }, "iam_condition": { "type": "object", "properties": { "request_ip": { "$ref": "#/components/schemas/iam_request_ip" } } }, "iam_country": { "description": "The country in which the user lives.", "type": "string", "example": "US", "maxLength": 30, "nullable": true }, "iam_create-account": { "type": "object", "properties": { "name": { "description": "Account name", "type": "string" }, "type": { "$ref": "#/components/schemas/iam_account-type" }, "unit": { "description": "information related to the tenant unit, and optionally, an id of the unit to create the account on. see https://developers.cloudflare.com/tenant/how-to/manage-accounts/", "type": "object", "properties": { "id": { "description": "Tenant unit ID", "type": "string", "example": "f267e341f3dd4697bd3b9f71dd96247f", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "name" ], "title": "Create account" }, "iam_create-member-with-policies": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/iam_email" }, "policies": { "description": "Array of policies associated with this member.", "type": "array", "items": { "$ref": "#/components/schemas/iam_create_member_policy" } }, "status": { "$ref": "#/components/schemas/iam_member-invitation-status" } }, "required": [ "email", "policies" ], "title": "Add Member with Policies" }, "iam_create-member-with-roles": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/iam_email" }, "roles": { "description": "Array of roles associated with this member.", "type": "array", "items": { "$ref": "#/components/schemas/iam_role_components-schemas-identifier" } }, "status": { "$ref": "#/components/schemas/iam_member-invitation-status" } }, "required": [ "email", "roles" ], "title": "Add Member with Account Roles" }, "iam_create-scope": { "description": "A scope is a combination of scope objects which provides additional context.", "type": "object", "properties": { "key": { "$ref": "#/components/schemas/iam_create_resource_group_scope_scope_key" }, "objects": { "description": "A list of scope objects for additional context. The number of Scope objects should not be zero.", "type": "array", "items": { "$ref": "#/components/schemas/iam_create_resource_group_scope_scope_object" } } }, "required": [ "key", "objects" ] }, "iam_create_member_policy": { "properties": { "access": { "$ref": "#/components/schemas/iam_access" }, "id": { "$ref": "#/components/schemas/iam_policy_identifier" }, "permission_groups": { "$ref": "#/components/schemas/iam_member_permission_groups" }, "resource_groups": { "$ref": "#/components/schemas/iam_member_resource_groups" } }, "required": [ "id", "access", "permission_groups", "resource_groups" ], "title": "create_member_policy" }, "iam_create_payload": { "type": "object", "properties": { "condition": { "$ref": "#/components/schemas/iam_condition" }, "expires_on": { "$ref": "#/components/schemas/iam_expires_on" }, "name": { "$ref": "#/components/schemas/iam_name" }, "not_before": { "$ref": "#/components/schemas/iam_not_before" }, "policies": { "$ref": "#/components/schemas/iam_token_policies" } }, "required": [ "name", "policies" ] }, "iam_create_resource_group_scope_scope_key": { "description": "This is a combination of pre-defined resource name and identifier (like Account ID etc.)", "example": "com.cloudflare.api.account.eb78d65290b24279ba6f44721b3ea3c4" }, "iam_create_resource_group_scope_scope_object": { "description": "A scope object represents any resource that can have actions applied against invite.", "type": "object", "properties": { "key": { "$ref": "#/components/schemas/iam_create_resource_group_scope_scope_object_key" } }, "required": [ "key" ] }, "iam_create_resource_group_scope_scope_object_key": { "description": "This is a combination of pre-defined resource name and identifier (like Zone ID etc.)", "example": "com.cloudflare.api.account.zone.23f8d65290b24279ba6f44721b3eaad5" }, "iam_create_user_group_body": { "type": "object", "properties": { "name": { "description": "Name of the User group.", "type": "string", "example": "My New User Group", "x-auditable": true }, "policies": { "description": "Policies attached to the User group", "type": "array", "items": { "$ref": "#/components/schemas/iam_user_group_policy_write_body" }, "title": "User Group Policies" } }, "required": [ "name" ], "title": "Create User group with a set of policies" }, "iam_dns_verification_code": { "description": "DNS verification code. Add this entire string to the DNS TXT record of the email domain to validate ownership.", "type": "string", "example": "cloudflare_dashboard_sso=023e105f4ecef8ad9ca31a8372d0c353" }, "iam_effect": { "description": "Allow or deny operations against the resources.", "type": "string", "example": "allow", "enum": [ "allow", "deny" ], "x-auditable": true }, "iam_email": { "description": "The contact email address of the user.", "type": "string", "example": "user@example.com", "maxLength": 90, "x-auditable": true }, "iam_expires_on": { "description": "The expiration time on or after which the JWT MUST NOT be accepted for processing.", "type": "string", "format": "date-time", "example": "2020-01-01T00:00:00Z", "x-auditable": true }, "iam_first_name": { "description": "User's first name", "type": "string", "example": "John", "maxLength": 60, "nullable": true, "x-auditable": true }, "iam_grants": { "type": "object", "properties": { "read": { "type": "boolean", "example": true, "x-auditable": true }, "write": { "type": "boolean", "example": true, "x-auditable": true } }, "example": { "read": true, "write": false } }, "iam_invite_components-schemas-identifier": { "description": "Invite identifier tag.", "type": "string", "example": "4f5f0c14a2a41d5063dd301b2f829f04", "maxLength": 32, "readOnly": true, "x-auditable": true }, "iam_invited_by": { "description": "The email address of the user who created the invite.", "type": "string", "example": "user@example.com", "maxLength": 90, "x-auditable": true }, "iam_invited_member_email": { "description": "Email address of the user to add to the organization.", "type": "string", "example": "user@example.com", "maxLength": 90, "x-auditable": true }, "iam_invited_on": { "description": "When the invite was sent.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00Z", "readOnly": true, "x-auditable": true }, "iam_issued_on": { "description": "The time on which the token was created.", "type": "string", "format": "date-time", "example": "2018-07-01T05:20:00Z", "readOnly": true, "x-auditable": true }, "iam_last_name": { "description": "User's last name", "type": "string", "example": "Appleseed", "maxLength": 60, "nullable": true, "x-auditable": true }, "iam_last_used_on": { "description": "Last time the token was used.", "type": "string", "format": "date-time", "example": "2020-01-02T12:34:00Z", "readOnly": true, "x-auditable": true }, "iam_list_member_policy": { "properties": { "access": { "$ref": "#/components/schemas/iam_access" }, "id": { "$ref": "#/components/schemas/iam_policy_identifier" }, "permission_groups": { "$ref": "#/components/schemas/iam_permission_groups" }, "resource_groups": { "$ref": "#/components/schemas/iam_resource_groups" } }, "title": "list_member_policy" }, "iam_member-invitation-status": { "description": "Status of the member invitation. If not provided during creation, defaults to 'pending'.\nChanging from 'accepted' back to 'pending' will trigger a replacement of the member resource in Terraform.\n", "type": "string", "enum": [ "accepted", "pending" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "iam_member_permission_group": { "description": "A group of permissions.", "type": "object", "properties": { "id": { "description": "Identifier of the group.", "type": "string", "example": "c8fed203ed3043cba015a93ad1616f1f", "x-auditable": true } }, "required": [ "id" ] }, "iam_member_permission_groups": { "description": "A set of permission groups that are specified to the policy.", "type": "array", "items": { "$ref": "#/components/schemas/iam_member_permission_group" }, "example": [ { "id": "c8fed203ed3043cba015a93ad1616f1f" }, { "id": "82e64a83756745bbbb1c9c2701bf816b" } ] }, "iam_member_resource_group": { "description": "A group of scoped resources.", "type": "object", "properties": { "id": { "description": "Identifier of the group.", "type": "string", "example": "6d7f2f5f5b1d4a0e9081fdc98d432fd1", "x-auditable": true } }, "required": [ "id" ] }, "iam_member_resource_groups": { "description": "A list of resource groups that the policy applies to.", "type": "array", "items": { "$ref": "#/components/schemas/iam_member_resource_group" } }, "iam_member_with_policies": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/iam_email" }, "id": { "$ref": "#/components/schemas/iam_membership_components-schemas-identifier" }, "policies": { "description": "Access policy for the membership", "type": "array", "items": { "$ref": "#/components/schemas/iam_list_member_policy" } }, "roles": { "description": "Roles assigned to this Member.", "type": "array", "items": { "$ref": "#/components/schemas/iam_role" } }, "status": { "description": "A member's status in the account.", "example": "accepted", "enum": [ "accepted", "pending" ], "readOnly": true, "x-auditable": true }, "user": { "description": "Details of the user associated to the membership.", "type": "object", "properties": { "email": { "$ref": "#/components/schemas/iam_email" }, "first_name": { "$ref": "#/components/schemas/iam_first_name" }, "id": { "$ref": "#/components/schemas/iam_common_components-schemas-identifier" }, "last_name": { "$ref": "#/components/schemas/iam_last_name" }, "two_factor_authentication_enabled": { "$ref": "#/components/schemas/iam_two_factor_authentication_enabled" } }, "readOnly": true, "required": [ "email" ] } } }, "iam_membership": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/iam_schemas-account" }, "api_access_enabled": { "$ref": "#/components/schemas/iam_api_access_enabled" }, "id": { "$ref": "#/components/schemas/iam_membership_components-schemas-identifier" }, "permissions": { "description": "All access permissions for the user at the account.", "allOf": [ { "$ref": "#/components/schemas/iam_permissions" } ], "readOnly": true }, "roles": { "$ref": "#/components/schemas/iam_role_names" }, "status": { "$ref": "#/components/schemas/iam_schemas-status" } } }, "iam_membership-with-policies": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/iam_schemas-account" }, "api_access_enabled": { "$ref": "#/components/schemas/iam_api_access_enabled" }, "id": { "$ref": "#/components/schemas/iam_membership_components-schemas-identifier" }, "permissions": { "description": "All access permissions for the user at the account.", "allOf": [ { "$ref": "#/components/schemas/iam_permissions" } ], "readOnly": true }, "policies": { "description": "Access policy for the membership", "type": "array", "items": { "$ref": "#/components/schemas/iam_list_member_policy" } }, "roles": { "$ref": "#/components/schemas/iam_role_names" }, "status": { "$ref": "#/components/schemas/iam_schemas-status" } } }, "iam_membership_components-schemas-identifier": { "description": "Membership identifier tag.", "type": "string", "example": "4536bcfad5faccb111b47003c79917fa", "maxLength": 32, "readOnly": true, "x-auditable": true }, "iam_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "iam_messages-2": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "iam_modified_on": { "description": "Last time the token was modified.", "type": "string", "format": "date-time", "example": "2018-07-02T05:20:00Z", "readOnly": true, "x-auditable": true }, "iam_name": { "description": "Token name.", "type": "string", "example": "readonly token", "maxLength": 120, "x-auditable": true }, "iam_not_before": { "description": "The time before which the token MUST NOT be accepted for processing.", "type": "string", "format": "date-time", "example": "2018-07-01T05:20:00Z", "x-auditable": true }, "iam_oauth_client": { "description": "An OAuth 2.0 client registration.", "allOf": [ { "$ref": "#/components/schemas/iam_oauth_client_common" }, { "properties": { "client_id": { "allOf": [ { "$ref": "#/components/schemas/iam_oauth_client_identifier" } ], "readOnly": true }, "client_uri_verification": { "$ref": "#/components/schemas/iam_oauth_client_uri_verification" }, "created_at": { "description": "Timestamp when the OAuth client was created.", "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z", "readOnly": true, "x-auditable": true }, "has_rotated_secret": { "description": "Indicates whether the client has a rotated secret that has not yet been deleted.", "type": "boolean", "example": false, "readOnly": true }, "promoted_at": { "description": "Timestamp when the OAuth client was promoted to public visibility.", "type": "string", "format": "date-time", "example": "2026-05-13T12:00:00Z", "readOnly": true, "x-auditable": true }, "updated_at": { "description": "Timestamp when the OAuth client was last updated.", "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z", "readOnly": true, "x-auditable": true }, "visibility": { "description": "Visibility of the OAuth client.", "type": "string", "example": "private", "enum": [ "public", "private" ], "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "client_id", "visibility" ], "type": "object" } ], "title": "OAuth Client" }, "iam_oauth_client_common": { "description": "Fields shared by OAuth client responses and create/update requests.", "type": "object", "properties": { "allowed_cors_origins": { "description": "Array of allowed CORS origins.", "type": "array", "items": { "type": "string" }, "example": [ "https://example.com" ], "x-auditable": true }, "client_name": { "description": "Human-readable name of the OAuth client.", "type": "string", "example": "My OAuth App", "x-auditable": true }, "client_uri": { "description": "URL of the home page of the client.", "type": "string", "example": "https://example.com", "x-auditable": true }, "grant_types": { "$ref": "#/components/schemas/iam_oauth_client_grant_types" }, "logo_uri": { "description": "URL of the client's logo.", "type": "string", "example": "https://example.com/logo.png", "x-auditable": true }, "optional_scopes": { "description": "Scopes that the authorizing user may decline during consent. Each value must also appear in `scopes`. The scopes `openid`, `offline`, and `offline_access` cannot be optional.", "type": "array", "items": { "type": "string" }, "example": [ "account.write" ], "x-auditable": true }, "policy_uri": { "description": "URL that points to a privacy policy document.", "type": "string", "example": "https://example.com/privacy", "x-auditable": true }, "post_logout_redirect_uris": { "description": "Array of allowed post-logout redirect URIs.", "type": "array", "items": { "type": "string" }, "example": [ "https://example.com/logout" ], "x-auditable": true }, "redirect_uris": { "description": "Array of allowed redirect URIs for the client.", "type": "array", "items": { "type": "string" }, "example": [ "https://example.com/callback" ], "x-auditable": true }, "response_types": { "$ref": "#/components/schemas/iam_oauth_client_response_types" }, "scopes": { "description": "Array of OAuth scopes the client is allowed to request. Colon-delimited scopes are not accepted. Dot-delimited scopes are validated against available OAuth API scopes; simple identity scopes are allowed. Protocol scopes `offline_access` and `openid` are added or removed automatically based on `grant_types` and `response_types`.", "type": "array", "items": { "type": "string" }, "example": [ "account.read" ], "x-auditable": true }, "token_endpoint_auth_method": { "$ref": "#/components/schemas/iam_oauth_client_token_endpoint_auth_method" }, "tos_uri": { "description": "URL that points to a terms of service document.", "type": "string", "example": "https://example.com/tos", "x-auditable": true } }, "title": "OAuth Client Common Fields" }, "iam_oauth_client_create_request": { "allOf": [ { "$ref": "#/components/schemas/iam_oauth_client_common" }, { "required": [ "client_name", "grant_types", "redirect_uris", "response_types", "scopes", "token_endpoint_auth_method" ], "type": "object" } ], "title": "Create OAuth Client Request" }, "iam_oauth_client_grant_types": { "description": "Array of OAuth grant types the client is allowed to use. `authorization_code` is required; `refresh_token` may be included optionally.", "type": "array", "items": { "enum": [ "authorization_code", "refresh_token" ], "type": "string" }, "example": [ "authorization_code", "refresh_token" ], "x-auditable": true }, "iam_oauth_client_identifier": { "description": "The unique identifier for an OAuth client.", "type": "string", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "title": "OAuth Client Identifier", "x-auditable": true }, "iam_oauth_client_response_types": { "description": "Array of OAuth response types the client is allowed to use.", "type": "array", "items": { "enum": [ "token", "id_token", "code" ], "type": "string" }, "example": [ "code" ], "x-auditable": true }, "iam_oauth_client_rotate_secret_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "client_secret": { "description": "The new client secret.", "type": "string", "example": "cf-oauth-secret-new-example", "readOnly": true, "x-sensitive": true } } } }, "type": "object" } ], "title": "Rotate OAuth Client Secret Response" }, "iam_oauth_client_token_endpoint_auth_method": { "description": "The authentication method the client uses at the token endpoint.", "type": "string", "example": "client_secret_post", "enum": [ "none", "client_secret_basic", "client_secret_post" ], "x-auditable": true }, "iam_oauth_client_update_request": { "description": "Partial update request for an OAuth client. Only include fields you want to update.", "allOf": [ { "$ref": "#/components/schemas/iam_oauth_client_common" }, { "properties": { "visibility": { "description": "Promote the OAuth client from private to public visibility. Only `public` is accepted; demotion to `private` is not supported. Promotion requires a non-empty client name, logo URI, verified client URI host, and at least one non-identity scope.", "type": "string", "example": "public", "enum": [ "public" ] } }, "type": "object" } ], "title": "Update OAuth Client Request" }, "iam_oauth_client_uri_verification": { "description": "Client URI domain control verification state.", "type": "object", "properties": { "status": { "description": "Current verification status for the client URI host.", "type": "string", "example": "in_progress", "enum": [ "pending", "in_progress", "verified", "failed" ] }, "text": { "description": "Exact TXT record value that must be added to DNS to prove ownership of the client URI host.", "type": "string", "example": "cloudflare_oauth_client_publisher=example" } }, "title": "OAuth Client URI Verification" }, "iam_oauth_client_with_secret": { "description": "An OAuth client response that includes the client secret. Only returned on client creation.", "allOf": [ { "$ref": "#/components/schemas/iam_oauth_client" }, { "properties": { "client_secret": { "description": "The client secret. This is the only time the secret is returned in a response.", "type": "string", "example": "cf-oauth-secret-example", "readOnly": true, "x-sensitive": true } }, "type": "object" } ], "title": "OAuth Client with Secret" }, "iam_oauth_scope": { "description": "An available OAuth scope that can be assigned to an OAuth client.", "type": "object", "properties": { "category": { "description": "Category for grouping scopes in the UI.", "type": "string", "example": "account_and_billing" }, "id": { "description": "The scope label to use in the scopes array when creating or updating an OAuth client.", "type": "string", "example": "account.read" }, "name": { "description": "Human-readable name of the OAuth scope.", "type": "string", "example": "Account Read" }, "scopes": { "description": "The underlying resource scopes (Bach scopes) that define which resources this OAuth scope can act upon.", "type": "array", "items": { "type": "string" }, "example": [ "com.cloudflare.api.account" ] } }, "required": [ "name", "id" ], "title": "OAuth Scope" }, "iam_organization": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/iam_common_components-schemas-identifier" }, "name": { "$ref": "#/components/schemas/iam_schemas-name" }, "permissions": { "$ref": "#/components/schemas/iam_schemas-permissions" }, "roles": { "description": "List of roles that a user has within an organization.", "type": "array", "items": { "example": "All Privileges - Super Administrator", "maxLength": 120, "type": "string", "x-auditable": true }, "readOnly": true }, "status": { "$ref": "#/components/schemas/iam_components-schemas-status" } } }, "iam_permission_group": { "description": "A named group of permissions that map to a group of operations against resources.", "type": "object", "properties": { "id": { "description": "Identifier of the permission group.", "type": "string", "example": "6d7f2f5f5b1d4a0e9081fdc98d432fd1", "x-auditable": true }, "meta": { "description": "Attributes associated to the permission group.", "type": "object", "example": { "label": "load_balancer_admin", "scopes": "com.cloudflare.api.account" }, "properties": { "key": { "type": "string", "x-auditable": true }, "value": { "type": "string", "x-auditable": true } } }, "name": { "description": "Name of the permission group.", "type": "string", "example": "Load Balancer", "readOnly": true, "x-auditable": true } }, "required": [ "id" ] }, "iam_permission_group_identifier": { "description": "Permission Group identifier tag.", "allOf": [ { "$ref": "#/components/schemas/iam_common_components-schemas-identifier" } ], "title": "Permission Group Identifier" }, "iam_permission_group_ids": { "description": "A set of permission groups that are specified to the policy.", "type": "array", "items": { "description": "A named group of permissions that map to a group of operations against resources.", "properties": { "id": { "$ref": "#/components/schemas/iam_permission_group_identifier" } }, "required": [ "id" ], "type": "object" }, "example": [ { "id": "c8fed203ed3043cba015a93ad1616f1f" }, { "id": "82e64a83756745bbbb1c9c2701bf816b" } ], "title": "Permission Group IDs" }, "iam_permission_groups": { "description": "A set of permission groups that are specified to the policy.", "type": "array", "items": { "$ref": "#/components/schemas/iam_permission_group" }, "example": [ { "id": "c8fed203ed3043cba015a93ad1616f1f", "meta": { "label": "load_balancer_admin", "scopes": "com.cloudflare.api.account" }, "name": "Zone Read" }, { "id": "82e64a83756745bbbb1c9c2701bf816b", "meta": { "label": "fbm_user", "scopes": "com.cloudflare.api.account" }, "name": "Magic Network Monitoring" } ] }, "iam_permissions": { "type": "object", "properties": { "analytics": { "$ref": "#/components/schemas/iam_grants" }, "billing": { "$ref": "#/components/schemas/iam_grants" }, "cache_purge": { "$ref": "#/components/schemas/iam_grants" }, "dns": { "$ref": "#/components/schemas/iam_grants" }, "dns_records": { "$ref": "#/components/schemas/iam_grants" }, "lb": { "$ref": "#/components/schemas/iam_grants" }, "logs": { "$ref": "#/components/schemas/iam_grants" }, "organization": { "$ref": "#/components/schemas/iam_grants" }, "ssl": { "$ref": "#/components/schemas/iam_grants" }, "waf": { "$ref": "#/components/schemas/iam_grants" }, "zone_settings": { "$ref": "#/components/schemas/iam_grants" }, "zones": { "$ref": "#/components/schemas/iam_grants" } }, "example": { "analytics": { "read": true, "write": false }, "zones": { "read": true, "write": true } } }, "iam_permissions_group_response_collection": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "properties": { "category": { "description": "Product category that this permission group belongs to.", "type": "string", "enum": [ "developer_platform", "ai_and_machine_learning", "dns_and_zones", "app_security", "rules_and_configuration", "cloudflare_one_and_zero_trust", "analytics_and_logs", "network_services", "media", "email_and_messaging", "cache_and_performance", "account_and_billing", "other" ], "x-auditable": true }, "id": { "description": "Public ID.", "type": "string", "x-auditable": true }, "name": { "description": "Permission Group Name", "type": "string", "x-auditable": true }, "scopes": { "description": "Resources to which the Permission Group is scoped", "type": "array", "items": { "enum": [ "com.cloudflare.api.account", "com.cloudflare.api.account.zone", "com.cloudflare.api.user", "com.cloudflare.edge.r2.bucket" ], "type": "string", "x-auditable": true } } }, "type": "object" }, "example": [ { "category": "account_and_billing", "id": "7cf72faf220841aabcfdfab81c43c4f6", "name": "Billing Read", "scopes": [ "com.cloudflare.api.account" ] }, { "category": "network_services", "id": "9d24387c6e8544e2bc4024a03991339f", "name": "Load Balancing: Monitors and Pools Read", "scopes": [ "com.cloudflare.api.account" ] }, { "category": "network_services", "id": "d2a1802cc9a34e30852f8b33869b2f3c", "name": "Load Balancing: Monitors and Pools Write", "scopes": [ "com.cloudflare.api.account" ] }, { "category": "developer_platform", "id": "8b47d2786a534c08a1f94ee8f9f599ef", "name": "Workers KV Storage Read", "scopes": [ "com.cloudflare.api.account" ] }, { "category": "developer_platform", "id": "f7f0eda5697f475c90846e879bab8666", "name": "Workers KV Storage Write", "scopes": [ "com.cloudflare.api.account" ] }, { "category": "developer_platform", "id": "1a71c399035b4950a1bd1466bbe4f420", "name": "Workers Scripts Read", "scopes": [ "com.cloudflare.api.account" ] }, { "category": "developer_platform", "id": "e086da7e2179491d91ee5f35b3ca210a", "name": "Workers Scripts Write", "scopes": [ "com.cloudflare.api.account" ] } ] } }, "type": "object" } ] }, "iam_policy_identifier": { "description": "Policy identifier.", "type": "string", "example": "f267e341f3dd4697bd3b9f71dd96247f", "readOnly": true, "x-auditable": true, "x-stainless-terraform-always-send": true }, "iam_policy_with_permission_groups_and_resources": { "type": "object", "properties": { "effect": { "$ref": "#/components/schemas/iam_effect" }, "id": { "$ref": "#/components/schemas/iam_policy_identifier" }, "permission_groups": { "$ref": "#/components/schemas/iam_permission_groups" }, "resources": { "$ref": "#/components/schemas/iam_resources" } }, "required": [ "id", "effect", "permission_groups", "resources" ], "title": "Policy with Permission Groups and Resources" }, "iam_properties-name": { "description": "Account name", "type": "string", "example": "Demo Account", "maxLength": 100, "x-auditable": true }, "iam_request_create_resource_group": { "type": "object", "properties": { "name": { "description": "Name of the resource group", "type": "string", "example": "NewResourceGroup" }, "scope": { "$ref": "#/components/schemas/iam_create-scope" } }, "required": [ "name", "scope" ], "title": "Create resource group" }, "iam_request_ip": { "description": "Client IP restrictions.", "type": "object", "properties": { "in": { "$ref": "#/components/schemas/iam_cidr_list" }, "not_in": { "$ref": "#/components/schemas/iam_cidr_list" } }, "example": { "in": [ "123.123.123.0/24", "2606:4700::/32" ], "not_in": [ "123.123.123.100/24", "2606:4700:4700::/48" ] } }, "iam_request_update_resource_group": { "type": "object", "properties": { "name": { "description": "Name of the resource group", "type": "string", "example": "UpdatedResourceGroup" }, "scope": { "$ref": "#/components/schemas/iam_create-scope" } }, "title": "Update resource group" }, "iam_resource_group": { "description": "A group of scoped resources.", "type": "object", "properties": { "id": { "description": "Identifier of the resource group.", "type": "string", "example": "6d7f2f5f5b1d4a0e9081fdc98d432fd1", "readOnly": true, "x-auditable": true }, "meta": { "description": "Attributes associated to the resource group.", "type": "object", "example": { "editable": "false" }, "properties": { "key": { "type": "string" }, "value": { "type": "string" } } }, "name": { "description": "Name of the resource group.", "type": "string", "example": "com.cloudflare.api.account.eb78d65290b24279ba6f44721b3ea3c4", "readOnly": true, "x-auditable": true }, "scope": { "$ref": "#/components/schemas/iam_scope" } }, "required": [ "id", "scope" ] }, "iam_resource_group_identifier": { "description": "Resource Group identifier tag.", "allOf": [ { "$ref": "#/components/schemas/iam_common_components-schemas-identifier" } ], "title": "Resource Group Identifier" }, "iam_resource_group_ids": { "description": "A set of resource groups that are specified to the policy.", "type": "array", "items": { "description": "A group of scoped resources.", "properties": { "id": { "$ref": "#/components/schemas/iam_resource_group_identifier" } }, "required": [ "id" ], "type": "object" }, "example": [ { "id": "6d7f2f5f5b1d4a0e9081fdc98d432fd1" } ], "title": "Resource Group IDs" }, "iam_resource_groups": { "description": "A list of resource groups that the policy applies to.", "type": "array", "items": { "$ref": "#/components/schemas/iam_resource_group" } }, "iam_resources": { "description": "A list of resource names that the policy applies to.", "example": { "object": { "summary": "Nested object value", "value": { "com.cloudflare.api.account.eb78d65290b24279ba6f44721b3ea3c4": { "com.cloudflare.api.account.zone.*": "*" } } }, "string": { "summary": "Single string value", "value": { "com.cloudflare.api.account.zone.22b1de5f1c0e4b3ea97bb1e963b06a43": "*" } } }, "oneOf": [ { "$ref": "#/components/schemas/iam_resources_type_object_string" }, { "$ref": "#/components/schemas/iam_resources_type_object_nested" } ], "x-auditable": true }, "iam_resources_type_object_nested": { "description": "Map of nested resource permissions", "type": "object", "additionalProperties": { "additionalProperties": { "type": "string" }, "description": "Nested permission object", "type": "object" } }, "iam_resources_type_object_string": { "description": "Map of simple string resource permissions", "type": "object", "additionalProperties": { "description": "Simple permission string like \"*\"", "type": "string" } }, "iam_response_collection": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "type": "object" } } }, "type": "object" } ] }, "iam_response_collection_accounts": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/iam_account" } } }, "type": "object" } ], "title": "Response with a list of accounts" }, "iam_response_create": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "allOf": [ { "type": "object" }, { "properties": { "value": { "$ref": "#/components/schemas/iam_value" } }, "type": "object" } ] } }, "type": "object" } ] }, "iam_response_single": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "type": "object" } }, "type": "object" } ] }, "iam_response_single_account": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/iam_account" } }, "type": "object" } ], "title": "Response with a single account" }, "iam_response_single_value": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/iam_value" } }, "type": "object" } ] }, "iam_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters", "type": "number", "example": 2000 } } }, "iam_role": { "type": "object", "properties": { "description": { "description": "Description of role's permissions.", "type": "string", "example": "Administrative access to the entire Account", "readOnly": true, "x-auditable": true }, "id": { "$ref": "#/components/schemas/iam_role_components-schemas-identifier" }, "name": { "description": "Role name.", "type": "string", "example": "Account Administrator", "maxLength": 120, "readOnly": true, "x-auditable": true }, "permissions": { "allOf": [ { "$ref": "#/components/schemas/iam_permissions" }, { "readOnly": true } ] } }, "required": [ "id", "name", "description", "permissions" ] }, "iam_role_components-schemas-identifier": { "description": "Role identifier tag.", "type": "string", "example": "3536bcfad5faccb999b47003c79917fb", "maxLength": 32, "x-auditable": true }, "iam_role_names": { "description": "List of role names the membership has for this account.", "type": "array", "items": { "example": "Account Administrator", "maxLength": 120, "type": "string", "x-auditable": true }, "readOnly": true }, "iam_schemas-account": { "allOf": [ { "$ref": "#/components/schemas/iam_account" } ], "readOnly": true }, "iam_schemas-collection_invite_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/iam_user_invite" } } }, "type": "object" } ] }, "iam_schemas-expires_on": { "description": "When the invite is no longer active.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00Z", "readOnly": true, "x-auditable": true }, "iam_schemas-name": { "description": "Organization name.", "type": "string", "example": "Cloudflare, Inc.", "maxLength": 100, "x-auditable": true }, "iam_schemas-permissions": { "description": "Access permissions for this User.", "type": "array", "items": { "example": "#zones:read", "maxLength": 160, "type": "string", "x-auditable": true }, "readOnly": true }, "iam_schemas-status": { "description": "Status of this membership.", "type": "string", "example": "accepted", "enum": [ "accepted", "pending", "rejected" ], "x-auditable": true }, "iam_scim_authentication_scheme": { "description": "An authentication method supported by the SCIM service.", "type": "object", "properties": { "description": { "description": "A description of the authentication scheme.", "type": "string", "example": "Authentication via OAuth 2.0 Bearer Token" }, "documentationUri": { "description": "An HTTP-addressable URL pointing to the authentication scheme documentation.", "type": "string" }, "name": { "description": "The common authentication scheme name.", "type": "string", "example": "OAuth Bearer Token" }, "primary": { "description": "Indicates if this is the primary authentication scheme.", "type": "boolean", "example": true }, "specUri": { "description": "An HTTP-addressable URL pointing to the authentication scheme specification.", "type": "string", "example": "http://www.rfc-editor.org/info/rfc6750" }, "type": { "description": "The authentication scheme type.", "type": "string", "example": "oauthbearertoken" } }, "required": [ "type", "name", "description" ], "title": "SCIM Authentication Scheme" }, "iam_scim_bulk_feature": { "description": "Configuration for SCIM bulk operations.", "type": "object", "properties": { "maxOperations": { "description": "The maximum number of operations in a bulk request.", "type": "integer", "example": 0 }, "maxPayloadSize": { "description": "The maximum payload size in bytes for a bulk request.", "type": "integer", "example": 0 }, "supported": { "description": "Whether bulk operations are supported.", "type": "boolean", "example": false } }, "required": [ "supported", "maxOperations", "maxPayloadSize" ], "title": "SCIM Bulk Feature" }, "iam_scim_error_response": { "description": "SCIM error envelope (RFC 7644 Section 3.12). Returned on all 4XX and 5XX responses from SCIM endpoints.\n", "type": "object", "properties": { "detail": { "description": "A human-readable message describing the error.", "type": "string", "example": "Invalid SCIM request: userName is required" }, "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:api:messages:2.0:Error" ] }, "scimType": { "description": "A SCIM detail error keyword (RFC 7644 Section 3.12). Only present for specific error conditions (e.g. `uniqueness` for duplicate member).\n", "type": "string", "example": "uniqueness" }, "status": { "description": "The HTTP status code as a string.", "type": "string", "example": "400" } }, "required": [ "schemas", "status" ], "title": "SCIM Error Response" }, "iam_scim_feature": { "description": "Represents a simple supported/unsupported SCIM feature.", "type": "object", "properties": { "supported": { "description": "Whether the feature is supported.", "type": "boolean", "example": true } }, "required": [ "supported" ], "title": "SCIM Feature" }, "iam_scim_filter_feature": { "description": "Configuration for SCIM filtering operations.", "type": "object", "properties": { "maxResults": { "description": "The maximum number of filter results per page.", "type": "integer", "example": 100 }, "supported": { "description": "Whether filtering is supported.", "type": "boolean", "example": true } }, "required": [ "supported", "maxResults" ], "title": "SCIM Filter Feature" }, "iam_scim_group": { "description": "A SCIM 2.0 Group resource representing an account user group (RFC 7643 Section 4.2). May be a system group (backed by a Cloudflare permission group, read-only except for member management) or a custom user group (full CRUD).", "type": "object", "properties": { "displayName": { "description": "A human-readable name for the Group.", "type": "string", "example": "Administrators", "x-auditable": true }, "externalId": { "description": "Identifier for the Group as defined by the provisioning client (IdP).", "type": "string", "example": "idp-group-456", "x-auditable": true }, "id": { "description": "Unique identifier for the Group, assigned by Cloudflare. System groups are prefixed `cloudflare-v1-`; custom groups use a UUID-style tag.", "type": "string", "example": "cloudflare-v1-023e105f4ecef8ad9ca31a8372d0c353", "readOnly": true, "x-auditable": true }, "members": { "description": "A list of members of the Group. Only populated for custom (Phase 2) groups on individual GET requests. Each member object contains a `value` (user tag) and optional `display` (email).", "type": "array", "items": { "properties": { "display": { "description": "The display name (email) of the group member.", "type": "string", "example": "user@example.com" }, "value": { "description": "The user tag identifier of the group member.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" } }, "type": "object" }, "example": [ { "display": "user@example.com", "value": "023e105f4ecef8ad9ca31a8372d0c353" } ], "readOnly": true }, "meta": { "$ref": "#/components/schemas/iam_scim_group_meta" }, "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ] } }, "required": [ "schemas", "id", "displayName" ], "title": "SCIM Group" }, "iam_scim_group_create_request": { "description": "Request body for creating a SCIM Group. The `displayName` must not be empty and must not begin with `CF` (reserved for system groups).\n", "type": "object", "properties": { "displayName": { "description": "A human-readable name for the Group. REQUIRED. Must not start with `CF` (reserved prefix for Cloudflare-managed virtual groups).\n", "type": "string", "example": "My IdP Group", "x-auditable": true }, "externalId": { "description": "Identifier for the Group as defined by the provisioning client (IdP).", "type": "string", "example": "idp-group-456", "x-auditable": true } }, "required": [ "displayName" ], "title": "SCIM Group Create Request" }, "iam_scim_group_identifier": { "description": "The group identifier for a SCIM Group resource. For system groups this is prefixed `cloudflare-v1-`; for custom user groups this is a UUID-style tag.\n", "type": "string", "example": "cloudflare-v1-023e105f4ecef8ad9ca31a8372d0c353", "title": "SCIM Group Identifier" }, "iam_scim_group_list_response": { "description": "SCIM ListResponse envelope for Group resources (RFC 7644 Section 3.4.2).\n", "type": "object", "properties": { "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/iam_scim_group_summary" } }, "itemsPerPage": { "description": "The number of resources returned in this page.", "type": "integer", "example": 5 }, "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] }, "startIndex": { "description": "The 1-based index of the first result in this set.", "type": "integer", "example": 1 }, "totalResults": { "description": "The total number of results matching the query.", "type": "integer", "example": 5 } }, "required": [ "schemas", "totalResults", "Resources" ], "title": "SCIM Group List Response" }, "iam_scim_group_meta": { "description": "Resource metadata for a SCIM Group.", "type": "object", "properties": { "resourceType": { "description": "The name of the resource type.", "type": "string", "example": "Group" } }, "readOnly": true, "title": "SCIM Group Meta" }, "iam_scim_group_patch_member_value": { "description": "A member value object used in Group PATCH operations.", "type": "object", "properties": { "value": { "description": "The user tag of the member to add or remove.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "x-auditable": true } }, "title": "SCIM Group Patch Member Value" }, "iam_scim_group_patch_op_request": { "description": "Request body for a SCIM PATCH operation on a Group resource (RFC 7644 Section 3.5.2).\n", "type": "object", "properties": { "Operations": { "description": "List of PATCH operations to apply.", "type": "array", "items": { "$ref": "#/components/schemas/iam_scim_group_patch_operation" }, "example": [ { "op": "add", "path": "members", "value": [ { "value": "023e105f4ecef8ad9ca31a8372d0c353" } ] } ] }, "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ] } }, "required": [ "schemas", "Operations" ], "title": "SCIM PatchOp Request (Groups)" }, "iam_scim_group_patch_operation": { "description": "A single PATCH operation for a Group resource. Supports `add`, `remove`, and `replace` on `members`, `displayName`, and `externalId`.\n", "type": "object", "properties": { "op": { "description": "The operation to perform.", "type": "string", "example": "add", "enum": [ "add", "remove", "replace" ], "x-auditable": true }, "path": { "description": "Attribute path targeted by this operation. Use `members` to modify group membership. May also include a filter expression to target specific members, e.g. `members[value eq \"userTag\"]`.\n", "type": "string", "example": "members", "x-auditable": true }, "value": { "description": "The value(s) for the operation. For member add/replace operations, an array of member value objects. For `displayName` or `externalId` updates, a string value.\n", "example": [ { "value": "023e105f4ecef8ad9ca31a8372d0c353" } ], "oneOf": [ { "items": { "$ref": "#/components/schemas/iam_scim_group_patch_member_value" }, "type": "array" }, { "type": "string" } ] } }, "required": [ "op" ], "title": "SCIM Group Patch Operation" }, "iam_scim_group_summary": { "description": "A SCIM 2.0 Group resource as returned in list responses. Does not include members; use the individual GET endpoint to retrieve members.", "type": "object", "properties": { "displayName": { "description": "A human-readable name for the Group.", "type": "string", "example": "Administrators", "x-auditable": true }, "externalId": { "description": "Identifier for the Group as defined by the provisioning client (IdP).", "type": "string", "example": "idp-group-456", "x-auditable": true }, "id": { "description": "Unique identifier for the Group, assigned by Cloudflare. System groups are prefixed `cloudflare-v1-`; custom groups use a UUID-style tag.", "type": "string", "example": "cloudflare-v1-023e105f4ecef8ad9ca31a8372d0c353", "readOnly": true, "x-auditable": true }, "meta": { "$ref": "#/components/schemas/iam_scim_group_meta" }, "schemas": { "description": "Must contain `urn:ietf:params:scim:schemas:core:2.0:Group`.", "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ] } }, "required": [ "schemas", "id", "displayName" ], "title": "SCIM Group Summary" }, "iam_scim_patch_op_request": { "description": "Request body for a SCIM PATCH operation on a User resource (RFC 7644 Section 3.5.2).\n", "type": "object", "properties": { "Operations": { "description": "List of PATCH operations to apply.", "type": "array", "items": { "$ref": "#/components/schemas/iam_scim_patch_operation" }, "example": [ { "op": "replace", "value": { "active": false } } ] }, "schemas": { "description": "Must contain `urn:ietf:params:scim:api:messages:2.0:PatchOp`.", "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ] } }, "required": [ "schemas", "Operations" ], "title": "SCIM PatchOp Request (Users)" }, "iam_scim_patch_operation": { "description": "A single PATCH operation (RFC 7644 Section 3.5.2).", "type": "object", "properties": { "op": { "description": "The operation to perform. Only `replace` is currently supported; `add` and `remove` are accepted without error but have no effect. Matched case-insensitively.\n", "type": "string", "example": "replace", "enum": [ "add", "remove", "replace" ], "x-auditable": true }, "path": { "description": "Attribute path targeted by this operation. When absent, `value` must be a singular complex attribute.\n", "type": "string", "example": "active", "x-auditable": true }, "value": { "description": "The value(s) for the operation. For `replace` without a path, this should be an object of attribute name/value pairs. For member path operations, this should be an array of member value objects.\n", "example": { "active": false } } }, "required": [ "op" ], "title": "SCIM Patch Operation" }, "iam_scim_resource_type": { "description": "A SCIM ResourceType resource (RFC 7643 Section 6). Describes a category of SCIM resource (e.g. User, Group) and its associated schema.\n", "type": "object", "properties": { "description": { "description": "The resource type's human-readable description.", "type": "string", "example": "User Account" }, "endpoint": { "description": "The resource type's HTTP-addressable endpoint relative to the base URL.", "type": "string", "example": "/Users" }, "id": { "description": "The resource type's server unique id.", "type": "string", "example": "User" }, "meta": { "$ref": "#/components/schemas/iam_scim_resource_type_meta" }, "name": { "description": "The resource type name.", "type": "string", "example": "User" }, "schema": { "description": "The resource type's primary/base schema URI.", "type": "string", "example": "urn:ietf:params:scim:schemas:core:2.0:User" }, "schemaExtensions": { "description": "A list of URIs of the resource type's schema extensions.", "type": "array", "items": { "$ref": "#/components/schemas/iam_scim_schema_extension" } }, "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:schemas:core:2.0:ResourceType" ] } }, "required": [ "schemas", "id", "name", "endpoint", "schema" ], "title": "SCIM Resource Type" }, "iam_scim_resource_type_list_response": { "description": "SCIM ListResponse envelope for ResourceType resources (RFC 7644 Section 4).\n", "type": "object", "properties": { "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/iam_scim_resource_type" } }, "itemsPerPage": { "type": "integer", "example": 2 }, "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] }, "startIndex": { "type": "integer", "example": 1 }, "totalResults": { "type": "integer", "example": 2 } }, "required": [ "schemas", "totalResults", "Resources" ], "title": "SCIM Resource Type List Response" }, "iam_scim_resource_type_meta": { "description": "Metadata for a SCIM ResourceType resource.", "type": "object", "properties": { "location": { "description": "The URI of the resource being returned.", "type": "string", "example": "https://api.cloudflare.com/accounts/023e105f4ecef8ad9ca31a8372d0c353/scim/v2/ResourceTypes/User" }, "resourceType": { "description": "The name of the resource type of the resource.", "type": "string", "example": "ResourceType" } }, "title": "SCIM Resource Type Meta" }, "iam_scim_schema": { "description": "A SCIM Schema resource (RFC 7643 Section 7). Defines the attributes of a SCIM resource type (e.g. User or Group).\n", "type": "object", "properties": { "attributes": { "description": "A complex attribute that includes the attributes of a schema.", "type": "array", "items": { "$ref": "#/components/schemas/iam_scim_schema_attr" } }, "description": { "description": "The schema's human-readable description.", "type": "string", "example": "User Account" }, "id": { "description": "The unique URI of the schema.", "type": "string", "example": "urn:ietf:params:scim:schemas:core:2.0:User" }, "meta": { "$ref": "#/components/schemas/iam_scim_schema_meta" }, "name": { "description": "The schema's human-readable name.", "type": "string", "example": "User" }, "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:schemas:core:2.0:Schema" ] } }, "required": [ "schemas", "id", "name", "attributes" ], "title": "SCIM Schema" }, "iam_scim_schema_attr": { "description": "An attribute definition within a SCIM schema (RFC 7643 Section 7).", "type": "object", "properties": { "canonicalValues": { "description": "A collection of canonical values for the attribute.", "type": "array", "items": { "type": "string" } }, "caseExact": { "description": "Indicates if the string attribute is case-sensitive.", "type": "boolean", "example": false }, "description": { "description": "A human-readable description of the attribute.", "type": "string" }, "multiValued": { "description": "Indicates if the attribute is multi-valued.", "type": "boolean", "example": false }, "mutability": { "description": "Indicates the circumstances under which the value of the attribute can be defined or redefined.", "type": "string", "example": "readWrite", "enum": [ "readOnly", "readWrite", "immutable", "writeOnly" ] }, "name": { "description": "The attribute's name.", "type": "string", "example": "userName" }, "referenceTypes": { "description": "A multi-valued attribute that indicates the SCIM resource types that may be referenced.", "type": "array", "items": { "type": "string" } }, "required": { "description": "Indicates if the attribute is required.", "type": "boolean", "example": false }, "returned": { "description": "Indicates when an attribute and associated values are returned in response to a GET request or in response to a PUT, POST, or PATCH request.", "type": "string", "example": "default", "enum": [ "always", "never", "default", "request" ] }, "subAttributes": { "description": "Defines a set of sub-attributes when the attribute type is `complex`.", "type": "array", "items": { "$ref": "#/components/schemas/iam_scim_schema_attr" } }, "type": { "description": "The attribute's data type.", "type": "string", "example": "string", "enum": [ "string", "boolean", "decimal", "integer", "dateTime", "reference", "complex" ] }, "uniqueness": { "description": "Indicates how the service provider enforces uniqueness of attribute values.", "type": "string", "example": "none", "enum": [ "none", "server", "global" ] } }, "required": [ "name", "type", "multiValued", "description", "required", "caseExact", "mutability", "returned", "uniqueness" ], "title": "SCIM Schema Attribute" }, "iam_scim_schema_extension": { "description": "An extension schema associated with a resource type.", "type": "object", "properties": { "required": { "description": "Whether the extension is required.", "type": "boolean" }, "schema": { "description": "The URI of the extension schema.", "type": "string" } }, "required": [ "schema", "required" ], "title": "SCIM Schema Extension" }, "iam_scim_schema_list_response": { "description": "SCIM ListResponse envelope for Schema resources (RFC 7644 Section 4).\n", "type": "object", "properties": { "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/iam_scim_schema" } }, "itemsPerPage": { "type": "integer", "example": 2 }, "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] }, "startIndex": { "type": "integer", "example": 1 }, "totalResults": { "type": "integer", "example": 2 } }, "required": [ "schemas", "totalResults", "Resources" ], "title": "SCIM Schema List Response" }, "iam_scim_schema_meta": { "description": "Metadata for a SCIM Schema resource.", "type": "object", "properties": { "location": { "description": "The URI of the resource being returned.", "type": "string", "example": "https://api.cloudflare.com/accounts/023e105f4ecef8ad9ca31a8372d0c353/scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User" }, "resourceType": { "description": "The name of the resource type of the resource.", "type": "string", "example": "Schema" } }, "title": "SCIM Schema Meta" }, "iam_scim_service_provider_config": { "description": "The SCIM 2.0 Service Provider configuration (RFC 7643 Section 5). Describes which optional SCIM features Cloudflare supports. IdPs use this to auto-configure their SCIM integration.\n", "type": "object", "properties": { "authenticationSchemes": { "type": "array", "items": { "$ref": "#/components/schemas/iam_scim_authentication_scheme" } }, "bulk": { "$ref": "#/components/schemas/iam_scim_bulk_feature" }, "changePassword": { "$ref": "#/components/schemas/iam_scim_feature" }, "documentationUri": { "description": "An HTTP-addressable URL pointing to the service provider's human-consumable help documentation.", "type": "string", "example": "https://developers.cloudflare.com/fundamentals/account/account-security/scim-setup/" }, "etag": { "$ref": "#/components/schemas/iam_scim_feature" }, "filter": { "$ref": "#/components/schemas/iam_scim_filter_feature" }, "patch": { "$ref": "#/components/schemas/iam_scim_feature" }, "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig" ] }, "sort": { "$ref": "#/components/schemas/iam_scim_feature" } }, "required": [ "schemas", "patch", "bulk", "filter", "changePassword", "sort", "etag", "authenticationSchemes" ], "title": "SCIM Service Provider Config" }, "iam_scim_user": { "description": "A SCIM 2.0 User resource representing an account member (RFC 7643 Section 4.1).\n", "type": "object", "properties": { "active": { "description": "A Boolean value indicating the user's administrative status. Set to `false` to deprovision the user, removing their membership from the account.", "type": "boolean", "example": true, "x-auditable": true }, "displayName": { "description": "The display name shown for the user. Falls back to formatted name or userName if not set.", "type": "string", "example": "Jane Smith", "x-auditable": true }, "emails": { "description": "Always contains a single primary work email matching `userName`.", "type": "array", "items": { "$ref": "#/components/schemas/iam_scim_user_email_object" } }, "externalId": { "description": "An identifier for the user as defined by the provisioning client (IdP). This value is stored and returned but not interpreted by Cloudflare.", "type": "string", "example": "idp-user-abc123", "x-auditable": true }, "groups": { "description": "A list of group identifiers to which the user belongs. Includes both system group tags (prefixed `cloudflare-v1-`) and custom user group tags.", "type": "array", "items": { "type": "string" }, "example": [ "cloudflare-v1-023e105f4ecef8ad9ca31a8372d0c353" ], "readOnly": true }, "id": { "description": "Unique identifier for the user, assigned by Cloudflare (user tag).", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "readOnly": true, "x-auditable": true }, "meta": { "description": "Resource metadata for a SCIM User.", "type": "object", "properties": { "resourceType": { "description": "The name of the resource type.", "type": "string", "example": "User" } }, "readOnly": true }, "name": { "$ref": "#/components/schemas/iam_scim_user_name_object" }, "schemas": { "description": "Must contain `urn:ietf:params:scim:schemas:core:2.0:User`.", "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:schemas:core:2.0:User" ] }, "userName": { "description": "Unique identifier for the user, equal to the user's email address.", "type": "string", "format": "email", "example": "user@example.com", "x-auditable": true } }, "required": [ "schemas", "id", "userName", "active" ], "title": "SCIM User" }, "iam_scim_user_create_request": { "description": "Request body for creating a SCIM User (POST). The `emails` field is required with a primary email matching `userName`, and `active` must be `true`.\n", "type": "object", "properties": { "active": { "description": "A Boolean value indicating the user's administrative status. Must be `true` for user creation.", "type": "boolean", "example": true, "x-auditable": true }, "displayName": { "description": "The name of the user, suitable for display to end-users. If not explicitly set, falls back to the formatted name or userName.", "type": "string", "example": "Jane Smith", "x-auditable": true }, "emails": { "description": "Email addresses for the user. The primary email must match `userName`.", "type": "array", "items": { "$ref": "#/components/schemas/iam_scim_user_email_object" } }, "externalId": { "description": "An identifier for the user as defined by the provisioning client (IdP). This value is stored and returned but not interpreted by Cloudflare.", "type": "string", "example": "idp-user-abc123", "x-auditable": true }, "name": { "$ref": "#/components/schemas/iam_scim_user_name_object" }, "schemas": { "description": "Must contain `urn:ietf:params:scim:schemas:core:2.0:User`.", "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:schemas:core:2.0:User" ] }, "userName": { "description": "Unique identifier for the user, equal to the user's email address.", "type": "string", "format": "email", "example": "user@example.com", "x-auditable": true } }, "required": [ "schemas", "userName", "emails", "active" ], "title": "SCIM User Create Request" }, "iam_scim_user_email_object": { "description": "An email address entry for a SCIM User.", "type": "object", "properties": { "primary": { "description": "A Boolean value indicating the preferred email address.", "type": "boolean", "example": true }, "type": { "description": "A label indicating the attribute's function, e.g., \"work\" or \"home\".", "type": "string", "example": "work" }, "value": { "description": "The email address value.", "type": "string", "format": "email", "example": "user@example.com" } }, "required": [ "value" ], "title": "SCIM User Email" }, "iam_scim_user_identifier": { "description": "The user tag identifying a SCIM User resource (account member).", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "title": "SCIM User Identifier" }, "iam_scim_user_list_response": { "description": "SCIM ListResponse envelope for User resources (RFC 7644 Section 3.4.2).\n", "type": "object", "properties": { "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/iam_scim_user" } }, "itemsPerPage": { "description": "The number of resources returned in this page.", "type": "integer", "example": 3 }, "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] }, "startIndex": { "description": "The 1-based index of the first result in this set.", "type": "integer", "example": 1 }, "totalResults": { "description": "The total number of results matching the query.", "type": "integer", "example": 3 } }, "required": [ "schemas", "totalResults", "Resources" ], "title": "SCIM User List Response" }, "iam_scim_user_name_object": { "description": "The components of the user's real name.", "type": "object", "properties": { "familyName": { "description": "The family name (last name) of the user.", "type": "string", "example": "Smith", "x-auditable": true }, "formatted": { "description": "The full name, including all middle names, titles, and suffixes as appropriate, formatted for display.", "type": "string", "example": "Jane Smith", "readOnly": true }, "givenName": { "description": "The given name (first name) of the user.", "type": "string", "example": "Jane", "x-auditable": true } }, "title": "SCIM User Name" }, "iam_scim_user_replace_request": { "description": "Request body for replacing a SCIM User (PUT). Only `schemas` and `userName` are required; other fields are optional.\n", "type": "object", "properties": { "active": { "description": "A Boolean value indicating the user's administrative status. Optional; if omitted, the current value is preserved. Set to `false` to deprovision the user, removing their membership from the account.", "type": "boolean", "example": true, "x-auditable": true }, "displayName": { "description": "The name of the user, suitable for display to end-users. If not explicitly set, falls back to the formatted name or userName.", "type": "string", "example": "Jane Smith", "x-auditable": true }, "emails": { "description": "Email addresses for the user. If a primary email is provided, it must match `userName`.", "type": "array", "items": { "$ref": "#/components/schemas/iam_scim_user_email_object" } }, "externalId": { "description": "An identifier for the user as defined by the provisioning client (IdP). This value is stored and returned but not interpreted by Cloudflare.", "type": "string", "example": "idp-user-abc123", "x-auditable": true }, "name": { "$ref": "#/components/schemas/iam_scim_user_name_object" }, "schemas": { "description": "Must contain `urn:ietf:params:scim:schemas:core:2.0:User`.", "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:schemas:core:2.0:User" ] }, "userName": { "description": "Unique identifier for the user, equal to the user's email address.", "type": "string", "format": "email", "example": "user@example.com", "x-auditable": true } }, "required": [ "schemas", "userName" ], "title": "SCIM User Replace Request" }, "iam_scope": { "description": "A scope is a combination of scope objects which provides additional context.", "type": "object", "properties": { "key": { "$ref": "#/components/schemas/iam_scope_key" }, "objects": { "description": "A list of scope objects for additional context.", "type": "array", "items": { "$ref": "#/components/schemas/iam_scope_object" } } }, "required": [ "key", "objects" ] }, "iam_scope_key": { "description": "This is a combination of pre-defined resource name and identifier (like Account ID etc.)", "example": "com.cloudflare.api.account.eb78d65290b24279ba6f44721b3ea3c4", "readOnly": true, "x-auditable": true }, "iam_scope_object": { "description": "A scope object represents any resource that can have actions applied against invite.", "type": "object", "properties": { "key": { "$ref": "#/components/schemas/iam_scope_object_key" } }, "required": [ "key" ] }, "iam_scope_object_key": { "description": "This is a combination of pre-defined resource name and identifier (like Zone ID etc.)", "example": "com.cloudflare.api.account.zone.23f8d65290b24279ba6f44721b3eaad5", "readOnly": true, "x-auditable": true }, "iam_single_invite_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/iam_user_invite" } }, "type": "object" } ] }, "iam_single_member_response_with_policies": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/iam_member_with_policies" } }, "type": "object" } ], "title": "Response with Policies" }, "iam_single_membership_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/iam_membership" } }, "type": "object" } ], "title": "response_with_roles" }, "iam_single_membership_response_with_policies": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/iam_membership-with-policies" } }, "type": "object" } ], "title": "response_with_policies" }, "iam_single_oauth_client_create_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/iam_oauth_client_with_secret" } }, "type": "object" } ], "title": "Create OAuth Client Response" }, "iam_single_oauth_client_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/iam_oauth_client" } }, "type": "object" } ], "title": "Single OAuth Client Response" }, "iam_single_organization_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "type": "object" } }, "type": "object" } ] }, "iam_single_permission_groups_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/iam_permission_group" } }, "type": "object" } ], "title": "Response with Permission Groups" }, "iam_single_role_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/iam_role" } }, "type": "object" } ] }, "iam_single_token_create_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/iam_token_with_value" } }, "type": "object" } ], "title": "Response of a create request with a single token" }, "iam_single_token_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/iam_token_base" } }, "type": "object" } ], "title": "Response with a single token" }, "iam_single_user_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "betas": { "description": "Lists the betas that the user is participating in.", "type": "array", "items": { "description": "User feature flag", "example": "zone_level_access_beta", "type": "string" }, "readOnly": true }, "country": { "$ref": "#/components/schemas/iam_country" }, "email": { "description": "Current email address of the user.", "type": "string", "format": "email", "example": "alice@example.com", "readOnly": true }, "first_name": { "$ref": "#/components/schemas/iam_first_name" }, "has_business_zones": { "description": "Indicates whether user has any business zones", "type": "boolean", "default": false, "readOnly": true }, "has_enterprise_zones": { "description": "Indicates whether user has any enterprise zones", "type": "boolean", "default": false, "readOnly": true }, "has_pro_zones": { "description": "Indicates whether user has any pro zones", "type": "boolean", "default": false, "readOnly": true }, "id": { "description": "Identifier of the user.", "type": "string", "example": "6d7f2f5f5b1d4a0e9081fdc98d432fd1", "readOnly": true }, "last_name": { "$ref": "#/components/schemas/iam_last_name" }, "organizations": { "type": "array", "items": { "$ref": "#/components/schemas/iam_organization" } }, "suspended": { "description": "Indicates whether user has been suspended", "type": "boolean", "default": false, "readOnly": true }, "telephone": { "$ref": "#/components/schemas/iam_telephone" }, "two_factor_authentication_enabled": { "$ref": "#/components/schemas/iam_two_factor_authentication_enabled" }, "two_factor_authentication_locked": { "$ref": "#/components/schemas/iam_two_factor_authentication_locked" }, "zipcode": { "$ref": "#/components/schemas/iam_zipcode" } }, "required": [ "id", "email" ] } }, "type": "object" } ] }, "iam_sso_connector": { "type": "object", "properties": { "created_on": { "description": "Timestamp for the creation of the SSO connector", "type": "string", "format": "date-time", "example": "2025-01-01T12:21:02Z" }, "email_domain": { "type": "string", "example": "example.com" }, "enabled": { "type": "boolean", "example": false }, "id": { "$ref": "#/components/schemas/iam_sso_connector_identifier" }, "updated_on": { "description": "Timestamp for the last update of the SSO connector", "type": "string", "format": "date-time", "example": "2025-01-01T12:21:02Z" }, "use_fedramp_language": { "$ref": "#/components/schemas/iam_use_fedramp_language" }, "verification": { "$ref": "#/components/schemas/iam_sso_connector_verification_info" } } }, "iam_sso_connector_collection_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/iam_sso_connector" } } }, "type": "object" } ], "title": "Response of initializing a new sso connector" }, "iam_sso_connector_identifier": { "description": "SSO Connector identifier tag.", "allOf": [ { "$ref": "#/components/schemas/iam_common_components-schemas-identifier" } ], "title": "SSO Connector Identifier" }, "iam_sso_connector_response": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/iam_sso_connector" } }, "type": "object" } ], "title": "Response of initializing a new sso connector" }, "iam_sso_connector_verification_info": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/iam_dns_verification_code" }, "status": { "description": "The status of the verification code from the verification process.", "type": "string", "example": "pending", "enum": [ "awaiting", "pending", "failed", "verified" ] } } }, "iam_telephone": { "description": "User's telephone number", "type": "string", "example": "+1 123-123-1234", "maxLength": 20, "nullable": true }, "iam_token_base": { "type": "object", "properties": { "condition": { "$ref": "#/components/schemas/iam_condition" }, "expires_on": { "$ref": "#/components/schemas/iam_expires_on" }, "id": { "$ref": "#/components/schemas/iam_token_identifier" }, "issued_on": { "$ref": "#/components/schemas/iam_issued_on" }, "last_used_on": { "$ref": "#/components/schemas/iam_last_used_on" }, "modified_on": { "$ref": "#/components/schemas/iam_modified_on" }, "name": { "$ref": "#/components/schemas/iam_name" }, "not_before": { "$ref": "#/components/schemas/iam_not_before" }, "policies": { "$ref": "#/components/schemas/iam_token_policies" }, "status": { "$ref": "#/components/schemas/iam_token_status" } } }, "iam_token_body": { "allOf": [ { "$ref": "#/components/schemas/iam_token_base" }, { "type": "object" }, { "required": [ "name", "policies" ] } ], "title": "Token defined in a request body" }, "iam_token_identifier": { "description": "Token identifier tag.", "type": "string", "example": "ed17574386854bf78a67040be0a770b0", "maxLength": 32, "readOnly": true, "x-auditable": true }, "iam_token_policies": { "description": "List of access policies assigned to the token.", "type": "array", "items": { "$ref": "#/components/schemas/iam_policy_with_permission_groups_and_resources" } }, "iam_token_status": { "description": "Status of the token.", "type": "string", "example": "active", "enum": [ "active", "disabled", "expired" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "iam_token_verify_response_single_segment": { "allOf": [ { "$ref": "#/components/schemas/iam_api-response-single" }, { "properties": { "result": { "properties": { "expires_on": { "$ref": "#/components/schemas/iam_expires_on" }, "id": { "$ref": "#/components/schemas/iam_token_identifier" }, "not_before": { "$ref": "#/components/schemas/iam_not_before" }, "status": { "$ref": "#/components/schemas/iam_token_status" } }, "required": [ "id", "status" ] } }, "type": "object" } ] }, "iam_token_with_value": { "allOf": [ { "$ref": "#/components/schemas/iam_token_base" }, { "properties": { "value": { "$ref": "#/components/schemas/iam_value" } } } ], "title": "Create token response, with the token value" }, "iam_two_factor_authentication_enabled": { "description": "Indicates whether two-factor authentication is enabled for the user account. Does not apply to API authentication.", "type": "boolean", "default": false, "readOnly": true }, "iam_two_factor_authentication_locked": { "description": "Indicates whether two-factor authentication is required by one of the accounts that the user is a member of.", "type": "boolean", "default": false, "readOnly": true }, "iam_unit-identifier": { "description": "Tenant unit identifier.", "type": "string", "example": "f267e341f3dd4697bd3b9f71dd96247f", "readOnly": true, "x-auditable": true }, "iam_update-member-with-policies": { "type": "object", "properties": { "policies": { "description": "Array of policies associated with this member.", "type": "array", "items": { "$ref": "#/components/schemas/iam_create_member_policy" } } }, "required": [ "policies" ], "title": "Update Member with Policies" }, "iam_update-member-with-roles": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/iam_membership_components-schemas-identifier" }, "roles": { "description": "Roles assigned to this member.", "type": "array", "items": { "$ref": "#/components/schemas/iam_role" } }, "status": { "description": "A member's status in the account.", "example": "accepted", "enum": [ "accepted", "pending" ], "readOnly": true, "x-auditable": true }, "user": { "description": "Details of the user associated to the membership.", "type": "object", "properties": { "email": { "$ref": "#/components/schemas/iam_email" }, "first_name": { "$ref": "#/components/schemas/iam_first_name" }, "id": { "$ref": "#/components/schemas/iam_common_components-schemas-identifier" }, "last_name": { "$ref": "#/components/schemas/iam_last_name" }, "two_factor_authentication_enabled": { "$ref": "#/components/schemas/iam_two_factor_authentication_enabled" } }, "readOnly": true, "required": [ "email" ] } }, "title": "Update Member with Account Roles" }, "iam_update_user_group_body": { "type": "object", "properties": { "name": { "description": "Name of the User group.", "type": "string", "example": "My New User Group" }, "policies": { "description": "Policies attached to the User group", "type": "array", "items": { "allOf": [ { "properties": { "id": { "description": "Policy identifier.", "type": "string", "example": "f267e341f3dd4697bd3b9f71dd96247f" } }, "required": [ "id" ], "type": "object" }, { "$ref": "#/components/schemas/iam_user_group_policy_write_body" } ] }, "title": "User Group Policies" } }, "title": "Create User group with a set of policies" }, "iam_use_fedramp_language": { "description": "Controls the display of FedRAMP language to the user during SSO login", "type": "boolean", "example": false, "default": false, "x-stainless-terraform-configurability": "computed_optional" }, "iam_user_group": { "description": "A group of policies resources.", "type": "object", "properties": { "created_on": { "description": "Timestamp for the creation of the user group", "type": "string", "format": "date-time", "example": "2024-03-01T12:21:02Z", "readOnly": true, "x-auditable": true }, "id": { "$ref": "#/components/schemas/iam_user_group_identifier" }, "modified_on": { "description": "Last time the user group was modified.", "type": "string", "format": "date-time", "example": "2024-03-01T12:21:02Z", "readOnly": true, "x-auditable": true }, "name": { "description": "Name of the user group.", "type": "string", "example": "My New User Group", "readOnly": true, "x-auditable": true }, "policies": { "description": "Policies attached to the User group", "type": "array", "items": { "description": "Policy", "properties": { "access": { "$ref": "#/components/schemas/iam_access" }, "id": { "$ref": "#/components/schemas/iam_policy_identifier" }, "permission_groups": { "$ref": "#/components/schemas/iam_permission_groups" }, "resource_groups": { "$ref": "#/components/schemas/iam_resource_groups" } }, "title": "Authorization Policy" }, "title": "User Group Policies" } }, "required": [ "id", "name", "created_on", "modified_on" ] }, "iam_user_group_identifier": { "description": "User Group identifier tag.", "allOf": [ { "$ref": "#/components/schemas/iam_common_components-schemas-identifier" } ], "title": "User Group Identifier" }, "iam_user_group_member": { "description": "Member attached to a User Group.", "type": "object", "properties": { "email": { "$ref": "#/components/schemas/iam_email" }, "id": { "description": "Account member identifier.", "type": "string", "example": "4f5f0c14a2a41d5063dd301b2f829f04", "readOnly": true }, "status": { "description": "The member's status in the account.", "example": "accepted", "enum": [ "accepted", "pending" ], "readOnly": true } }, "required": [ "id" ] }, "iam_user_group_member_detailed": { "description": "Detailed member information for a User Group member.", "type": "object", "properties": { "created_at": { "description": "When the member was added to the user group.", "type": "string", "format": "date-time", "example": "2026-01-15T10:30:00Z", "readOnly": true }, "email": { "$ref": "#/components/schemas/iam_email" }, "id": { "description": "Account member identifier.", "type": "string", "example": "4f5f0c14a2a41d5063dd301b2f829f04", "readOnly": true }, "status": { "description": "The member's status in the account.", "example": "accepted", "enum": [ "accepted", "pending" ], "readOnly": true }, "user": { "description": "Details of the user associated with this membership.", "type": "object", "properties": { "email": { "$ref": "#/components/schemas/iam_email" }, "first_name": { "description": "User's first name.", "type": "string", "example": "Alice", "readOnly": true }, "id": { "description": "User identifier tag.", "type": "string", "example": "7c5dae5552338874e5053f2534d2767a", "readOnly": true }, "last_name": { "description": "User's last name.", "type": "string", "example": "Smith", "readOnly": true } }, "readOnly": true } }, "required": [ "id" ] }, "iam_user_group_member_identifier": { "description": "The identifier of an existing account Member.", "allOf": [ { "$ref": "#/components/schemas/iam_common_components-schemas-identifier" } ], "title": "User Group Member Identifier" }, "iam_user_group_policy_write_body": { "properties": { "access": { "$ref": "#/components/schemas/iam_access" }, "permission_groups": { "$ref": "#/components/schemas/iam_permission_group_ids" }, "resource_groups": { "$ref": "#/components/schemas/iam_resource_group_ids" } }, "required": [ "access", "permission_groups", "resource_groups" ] }, "iam_user_groups": { "description": "A list of user groups for the account.", "type": "array", "items": { "$ref": "#/components/schemas/iam_user_group" }, "title": "User Groups" }, "iam_user_invite": { "type": "object", "properties": { "expires_on": { "$ref": "#/components/schemas/iam_schemas-expires_on" }, "id": { "$ref": "#/components/schemas/iam_invite_components-schemas-identifier" }, "invited_by": { "$ref": "#/components/schemas/iam_invited_by" }, "invited_member_email": { "$ref": "#/components/schemas/iam_invited_member_email" }, "invited_member_id": { "description": "ID of the user to add to the organization.", "type": "string", "example": "5a7805061c76ada191ed06f989cc3dac", "maxLength": 32, "nullable": true, "readOnly": true, "x-auditable": true }, "invited_on": { "$ref": "#/components/schemas/iam_invited_on" }, "organization_id": { "description": "ID of the organization the user will be added to.", "type": "string", "example": "5a7805061c76ada191ed06f989cc3dac", "maxLength": 32, "readOnly": true, "x-auditable": true }, "organization_is_enforcing_twofactor": { "type": "boolean", "example": true, "x-auditable": true }, "organization_name": { "description": "Organization name.", "type": "string", "example": "Cloudflare, Inc.", "maxLength": 100, "readOnly": true, "x-auditable": true }, "roles": { "$ref": "#/components/schemas/iam_role_names" }, "status": { "description": "Current status of the invitation.", "example": "accepted", "enum": [ "pending", "accepted", "rejected", "expired" ], "x-auditable": true } }, "required": [ "invited_member_id", "organization_id" ] }, "iam_value": { "description": "The token value.", "type": "string", "example": "8M7wS6hCpXVc-DoRnPPY_UCWPgy8aea4Wy6kCe5T", "maxLength": 80, "minLength": 40, "readOnly": true, "x-sensitive": true }, "iam_zipcode": { "description": "The zipcode or postal code where the user lives.", "type": "string", "example": "12345", "maxLength": 20, "nullable": true }, "images_account_identifier": { "description": "Account identifier tag.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "images_api-response-collection-v2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/images_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "continuation_token": { "$ref": "#/components/schemas/images_images_list_continuation_token" } } } }, "type": "object" } ] }, "images_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/images_messages" }, "messages": { "$ref": "#/components/schemas/images_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": { "type": "object" }, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ], "x-auditable": true } }, "required": [ "success", "errors", "messages", "result" ] }, "images_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/images_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/images_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": false, "enum": [ false ], "x-auditable": true } }, "required": [ "success", "errors", "messages", "result" ] }, "images_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/images_api-response-common" }, { "properties": { "result": { "anyOf": [ { "type": "object" }, { "type": "string" } ] } }, "type": "object" } ] }, "images_deleted_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-single" }, { "properties": { "result": { "type": "object", "example": {} } }, "type": "object" } ] }, "images_image": { "type": "object", "properties": { "creator": { "$ref": "#/components/schemas/images_image_creator" }, "filename": { "$ref": "#/components/schemas/images_image_filename" }, "id": { "$ref": "#/components/schemas/images_image_identifier" }, "meta": { "$ref": "#/components/schemas/images_image_metadata" }, "requireSignedURLs": { "$ref": "#/components/schemas/images_image_requireSignedURLs" }, "uploaded": { "$ref": "#/components/schemas/images_image_uploaded" }, "variants": { "$ref": "#/components/schemas/images_image_variants" } } }, "images_image_basic_upload": { "type": "object", "properties": { "creator": { "description": "Can set the creator field with an internal user ID.", "type": "string", "maxLength": 1024 }, "file": { "description": "An image binary data. Only needed when type is uploading a file.", "type": "string", "format": "binary", "x-auditable": true }, "id": { "description": "An optional custom unique identifier for your image.", "type": "string", "x-auditable": true }, "metadata": { "description": "User modifiable key-value store. Can use used for keeping references to another system of record for managing images.", "type": "object" }, "requireSignedURLs": { "description": "Indicates whether the image requires a signature token for the access.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "url": { "description": "A URL to fetch an image from origin. Only needed when type is uploading from a URL.", "type": "string", "example": "https://example.com/path/to/logo.png", "x-auditable": true } } }, "images_image_creator": { "description": "Can set the creator field with an internal user ID.", "type": "string", "example": "107b9558-dd06-4bbd-5fef-9c2c16bb7900", "maxLength": 1024, "nullable": true, "x-auditable": true }, "images_image_direct_upload_request_v1": { "type": "object", "properties": { "expiry": { "description": "The date after which the upload will not be accepted. Minimum: Now + 2 minutes. Maximum: Now + 6 hours.", "type": "string", "format": "date-time", "example": "2021-01-02T02:20:00Z" } } }, "images_image_direct_upload_request_v2": { "type": "object", "properties": { "creator": { "description": "Can set the creator field with an internal user ID.", "type": "string" }, "expiry": { "description": "The date after which the upload will not be accepted. Minimum: Now + 2 minutes. Maximum: Now + 6 hours.", "type": "string", "format": "date-time", "example": "2021-01-02T02:20:00Z", "default": "Now + 30 minutes", "x-auditable": true }, "id": { "description": "Optional Image Custom ID. Up to 1024 chars. Can include any number of subpaths, and utf8 characters. Cannot start nor end with a / (forward slash). Cannot be a UUID.", "type": "string", "example": "this/is/my-customid", "maxLength": 1024, "x-auditable": true }, "metadata": { "description": "User modifiable key-value store. Can be used for keeping references to another system of record, for managing images.", "type": "object" }, "requireSignedURLs": { "description": "Indicates whether the image requires a signature token to be accessed.", "type": "boolean", "example": true, "default": false, "x-auditable": true } } }, "images_image_direct_upload_response_v1": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "description": "Image unique identifier.", "type": "string", "example": "e22e9e6b-c02b-42fd-c405-6c32af5fe600", "readOnly": true }, "uploadURL": { "description": "The URL the unauthenticated upload can be performed to using a single HTTP POST (multipart/form-data) request.", "type": "string", "example": "https://upload.imagedelivery.net/FxUufywByo0m2v3xhKSiU8/e22e9e6b-c02b-42fd-c405-6c32af5fe600" } } } }, "type": "object" } ] }, "images_image_direct_upload_response_v2": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "description": "Image unique identifier.", "type": "string", "example": "e22e9e6b-c02b-42fd-c405-6c32af5fe600", "maxLength": 32, "readOnly": true, "x-auditable": true }, "uploadURL": { "description": "The URL the unauthenticated upload can be performed to using a single HTTP POST (multipart/form-data) request.", "type": "string", "example": "https://upload.imagedelivery.net/FxUufywByo0m2v3xhKSiU8/e22e9e6b-c02b-42fd-c405-6c32af5fe600", "x-auditable": true } } } }, "type": "object" } ] }, "images_image_filename": { "description": "Image file name.", "type": "string", "example": "logo.png", "maxLength": 255, "readOnly": true, "x-auditable": true }, "images_image_hero_url": { "description": "URI to hero variant for an image.", "type": "string", "format": "uri", "example": "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/hero", "readOnly": true, "x-auditable": true }, "images_image_identifier": { "description": "Image unique identifier.", "type": "string", "example": "107b9558-dd06-4bbd-5fef-9c2c16bb7900", "maxLength": 32, "readOnly": true, "x-auditable": true }, "images_image_key_name": { "description": "Key name.", "type": "string", "example": "default", "readOnly": true, "x-auditable": true }, "images_image_key_response_collection": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/images_image_keys_response" } }, "type": "object" } ] }, "images_image_key_value": { "description": "Key value.", "type": "string", "example": "Oix0bbNaT8Rge9PuyxUBrjI6zrgnsyJ5=", "readOnly": true, "x-auditable": true }, "images_image_keys": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/images_image_key_name" }, "value": { "$ref": "#/components/schemas/images_image_key_value" } } }, "images_image_keys_response": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/images_image_keys" } } } }, "images_image_metadata": { "description": "User modifiable key-value store. Can be used for keeping references to another system of record for managing images. Metadata must not exceed 1024 bytes.", "type": "object", "example": { "key": "value" } }, "images_image_original_url": { "description": "URI to original variant for an image.", "type": "string", "format": "uri", "example": "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/original", "readOnly": true, "x-auditable": true }, "images_image_patch_request": { "type": "object", "properties": { "creator": { "description": "Can set the creator field with an internal user ID.", "type": "string" }, "metadata": { "description": "User modifiable key-value store. Can be used for keeping references to another system of record for managing images. No change if not specified.", "type": "object" }, "requireSignedURLs": { "description": "Indicates whether the image can be accessed using only its UID. If set to `true`, a signed token needs to be generated with a signing key to view the image. Returns a new UID on a change. No change if not specified.", "type": "boolean", "example": true, "x-auditable": true } } }, "images_image_requireSignedURLs": { "description": "Indicates whether the image can be a accessed only using it's UID. If set to true, a signed token needs to be generated with a signing key to view the image.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "images_image_response_blob": { "example": "", "anyOf": [ { "type": "string" }, { "type": "object" } ] }, "images_image_response_single": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/images_image" } }, "type": "object" } ] }, "images_image_thumbnail_url": { "description": "URI to thumbnail variant for an image.", "type": "string", "format": "uri", "example": "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/thumbnail", "readOnly": true, "x-auditable": true }, "images_image_uploaded": { "description": "When the media item was uploaded.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00.123Z", "readOnly": true, "x-auditable": true }, "images_image_variant_definition": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/images_image_variant_identifier" }, "neverRequireSignedURLs": { "$ref": "#/components/schemas/images_image_variant_neverRequireSignedURLs" }, "options": { "$ref": "#/components/schemas/images_image_variant_options" } }, "required": [ "id", "options" ] }, "images_image_variant_fit": { "description": "The fit property describes how the width and height dimensions should be interpreted.", "type": "string", "example": "scale-down", "enum": [ "scale-down", "contain", "cover", "crop", "pad" ], "x-auditable": true }, "images_image_variant_flat_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/images_image_variant_definition" } }, "type": "object" } ] }, "images_image_variant_height": { "description": "Maximum height in image pixels.", "type": "number", "example": 768, "minimum": 1, "x-auditable": true }, "images_image_variant_identifier": { "type": "string", "example": "hero", "maxLength": 99, "pattern": "^[a-zA-Z0-9]$", "x-auditable": true }, "images_image_variant_list_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/images_image_variants_response" } }, "type": "object" } ] }, "images_image_variant_neverRequireSignedURLs": { "description": "Indicates whether the variant can access an image without a signature, regardless of image access control.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "images_image_variant_options": { "description": "Allows you to define image resizing sizes for different use cases.", "type": "object", "properties": { "fit": { "$ref": "#/components/schemas/images_image_variant_fit" }, "height": { "$ref": "#/components/schemas/images_image_variant_height" }, "metadata": { "$ref": "#/components/schemas/images_image_variant_schemas_metadata" }, "width": { "$ref": "#/components/schemas/images_image_variant_width" } }, "required": [ "fit", "metadata", "width", "height" ] }, "images_image_variant_patch_request": { "type": "object", "properties": { "neverRequireSignedURLs": { "$ref": "#/components/schemas/images_image_variant_neverRequireSignedURLs" }, "options": { "$ref": "#/components/schemas/images_image_variant_options" } }, "required": [ "options" ] }, "images_image_variant_public_request": { "type": "object", "properties": { "hero": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/images_image_variant_identifier" }, "neverRequireSignedURLs": { "$ref": "#/components/schemas/images_image_variant_neverRequireSignedURLs" }, "options": { "$ref": "#/components/schemas/images_image_variant_options" } }, "required": [ "id", "options" ] } } }, "images_image_variant_response": { "type": "object", "properties": { "variant": { "$ref": "#/components/schemas/images_image_variant_definition" } } }, "images_image_variant_schemas_metadata": { "description": "What EXIF data should be preserved in the output image.", "type": "string", "example": "none", "enum": [ "keep", "copyright", "none" ], "x-auditable": true }, "images_image_variant_simple_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/images_image_variant_response" } }, "type": "object" } ] }, "images_image_variant_width": { "description": "Maximum width in image pixels.", "type": "number", "example": 1366, "minimum": 1, "x-auditable": true }, "images_image_variants": { "description": "Object specifying available variants for an image.", "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/images_image_thumbnail_url" }, { "$ref": "#/components/schemas/images_image_hero_url" }, { "$ref": "#/components/schemas/images_image_original_url" } ] }, "example": [ "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/thumbnail", "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/hero", "https://imagedelivery.net/MTt4OTd0b0w5aj/107b9558-dd06-4bbd-5fef-9c2c16bb7900/original" ], "readOnly": true }, "images_image_variants_response": { "type": "object", "properties": { "variants": { "$ref": "#/components/schemas/images_image_variant_public_request" } } }, "images_images_list_continuation_token": { "description": "Continuation token to fetch next page. Passed as a query param when requesting List V2 api endpoint.", "type": "string", "example": "iD0bxlWFSVUWsDHbzIqvDkgBW4otifAAuGXLz1n8BQA", "maxLength": 32, "nullable": true, "readOnly": true, "x-auditable": true }, "images_images_list_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "images": { "type": "array", "items": { "$ref": "#/components/schemas/images_image" } } } } }, "type": "object" } ] }, "images_images_list_response_v2": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-collection-v2" }, { "properties": { "result": { "type": "object", "properties": { "images": { "type": "array", "items": { "$ref": "#/components/schemas/images_image" } } } } }, "type": "object" } ] }, "images_images_stats": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/images_images_stats_count" } } }, "images_images_stats_allowed": { "description": "Cloudflare Images allowed usage.", "type": "number", "example": 100000, "readOnly": true, "x-auditable": true }, "images_images_stats_count": { "type": "object", "properties": { "allowed": { "$ref": "#/components/schemas/images_images_stats_allowed" }, "current": { "$ref": "#/components/schemas/images_images_stats_current" } } }, "images_images_stats_current": { "description": "Cloudflare Images current usage.", "type": "number", "example": 1000, "readOnly": true, "x-auditable": true }, "images_images_stats_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/images_images_stats" } }, "type": "object" } ] }, "images_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000, "x-auditable": true }, "message": { "type": "string", "x-auditable": true } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "images_metadata_keys_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "keys": { "type": "array", "items": { "maxLength": 100, "type": "string" }, "maxItems": 1000 }, "truncated": { "type": "boolean" } }, "required": [ "keys", "truncated" ] } }, "type": "object" } ] }, "images_signing_key_identifier": { "type": "string", "example": "someKey", "maxLength": 20, "pattern": "^[a-zA-Z0-9]$", "x-auditable": true }, "images_sourcingkit_acceptable_content_type": { "description": "A MIME type that can be excluded from migration.", "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "image/gif", "image/avif", "image/heic", "image/svg+xml" ] }, "images_sourcingkit_conflict_behaviour": { "description": "How to handle objects that already exist at the destination.", "type": "string", "default": "skip", "enum": [ "skip", "overwrite" ] }, "images_sourcingkit_connectivity_check_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "code": { "description": "Machine-readable error code if connectivity failed.", "type": "string", "nullable": true }, "connectivityStatus": { "description": "Whether the connectivity check succeeded.", "type": "string", "enum": [ "ok", "error" ] }, "reason": { "description": "Human-readable error description if connectivity failed.", "type": "string", "nullable": true } } } }, "type": "object" } ] }, "images_sourcingkit_connectivity_precheck_request": { "type": "object", "properties": { "account": { "description": "Account identifier for the bucket (required for R2 vendor).", "type": "string" }, "bucket": { "description": "The name of the storage bucket.", "type": "string", "maxLength": 128, "minLength": 1 }, "region": { "description": "The region hint for the bucket (S3 only).", "type": "string", "nullable": true }, "secret": { "description": "Storage credentials for accessing the bucket.", "type": "object", "writeOnly": true }, "vendor": { "$ref": "#/components/schemas/images_sourcingkit_vendor" } }, "required": [ "bucket", "vendor", "secret" ] }, "images_sourcingkit_identifier": { "description": "Sourcing kit resource identifier.", "type": "string", "format": "uuid", "example": "5ca167e6-4e40-4ced-a209-ca1b9dd6a265" }, "images_sourcingkit_migration": { "type": "object", "properties": { "conflictBehaviour": { "$ref": "#/components/schemas/images_sourcingkit_conflict_behaviour" }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "endedAt": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "excludedContentTypes": { "description": "Content types to skip during migration.", "type": "array", "items": { "$ref": "#/components/schemas/images_sourcingkit_acceptable_content_type" }, "nullable": true }, "id": { "description": "Migration unique identifier.", "type": "string", "format": "uuid", "readOnly": true }, "imagesPathPrefix": { "description": "Alias for pathPrefix (deprecated).", "type": "string", "nullable": true }, "logStopped": { "description": "Whether logging was stopped due to excessive log volume.", "type": "boolean", "readOnly": true }, "pathPrefix": { "description": "Prefix to prepend to image custom IDs.", "type": "string", "nullable": true }, "rootDirectory": { "description": "Only import objects under this prefix in the source bucket.", "type": "string", "nullable": true }, "sourceId": { "description": "The source this migration imports from.", "type": "string", "format": "uuid", "nullable": true }, "startedAt": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "status": { "$ref": "#/components/schemas/images_sourcingkit_migration_status" } } }, "images_sourcingkit_migration_create_request": { "type": "object", "properties": { "conflictBehaviour": { "$ref": "#/components/schemas/images_sourcingkit_conflict_behaviour" }, "excludedContentTypes": { "description": "Content types to skip during migration.", "type": "array", "items": { "$ref": "#/components/schemas/images_sourcingkit_acceptable_content_type" } }, "pathPrefix": { "description": "Prefix to prepend to image custom IDs.", "type": "string", "maxLength": 128, "minLength": 1 }, "rootDirectory": { "description": "Only import objects under this prefix in the source bucket.", "type": "string", "maxLength": 128, "minLength": 1 }, "sourceId": { "description": "The identifier of the source to migrate from.", "type": "string", "format": "uuid" } }, "required": [ "sourceId" ] }, "images_sourcingkit_migration_create_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/images_sourcingkit_migration" } }, "type": "object" } ] }, "images_sourcingkit_migration_list_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "migrations": { "type": "array", "items": { "$ref": "#/components/schemas/images_sourcingkit_migration" } } } } }, "type": "object" } ] }, "images_sourcingkit_migration_log": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "logType": { "$ref": "#/components/schemas/images_sourcingkit_migration_log_type" }, "msg": { "description": "Log message detail.", "type": "string", "nullable": true } } }, "images_sourcingkit_migration_log_list_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "logs": { "type": "array", "items": { "$ref": "#/components/schemas/images_sourcingkit_migration_log" } } } } }, "type": "object" } ] }, "images_sourcingkit_migration_log_type": { "description": "The type of log entry.", "type": "string", "enum": [ "default", "importSkippedUnsupportedContentType", "importSkippedExcludedContentType", "importSkippedInvalidMedia", "importErrorRetryExhaustion", "importSkippedOversized", "migrationErrorFailedContinuation", "migrationStart", "migrationAbort", "migrationError", "migrationComplete", "importSkippedStorageClass" ] }, "images_sourcingkit_migration_progress_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "endedAt": { "type": "string", "format": "date-time", "nullable": true }, "importErrorsCount": { "description": "Objects that failed to import.", "type": "integer" }, "importSuccessCount": { "description": "Objects successfully imported.", "type": "integer" }, "isAccurate": { "description": "Whether the counts are accurate or estimated.", "type": "boolean" }, "scannedCount": { "description": "Total number of objects scanned in the source.", "type": "integer" }, "skippedConflictCount": { "description": "Objects skipped due to existing images at destination.", "type": "integer" }, "skippedExcludedContentTypeCount": { "description": "Objects skipped because their content type was excluded.", "type": "integer" }, "skippedInvalidMediaCount": { "description": "Objects skipped because the media could not be decoded.", "type": "integer" }, "skippedInvalidNameCount": { "description": "Objects skipped because their name is not valid.", "type": "integer" }, "skippedOversizeCount": { "description": "Objects skipped because they exceed the size limit.", "type": "integer" }, "skippedStorageClassCount": { "description": "Objects skipped due to unsupported storage class.", "type": "integer" }, "skippedUnsupportedContentTypeCount": { "description": "Objects skipped because their content type is not supported.", "type": "integer" }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "status": { "$ref": "#/components/schemas/images_sourcingkit_migration_status" } } } }, "type": "object" } ] }, "images_sourcingkit_migration_single_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/images_sourcingkit_migration" } }, "type": "object" } ] }, "images_sourcingkit_migration_status": { "description": "Current status of the migration.", "type": "string", "enum": [ "pending", "processing", "success", "error", "aborted" ] }, "images_sourcingkit_source": { "type": "object", "properties": { "bucket": { "description": "The name of the storage bucket.", "type": "string", "example": "my-images-bucket" }, "createdAt": { "description": "When the source was created.", "type": "string", "format": "date-time", "readOnly": true }, "id": { "description": "Source unique identifier.", "type": "string", "format": "uuid", "example": "5ca167e6-4e40-4ced-a209-ca1b9dd6a265", "readOnly": true }, "name": { "description": "A human-readable name for the source.", "type": "string", "example": "my-s3-bucket" }, "region": { "description": "The region of the storage bucket (S3 sources only).", "type": "string", "example": "us-east-1", "nullable": true }, "updatedAt": { "description": "When the source was last updated.", "type": "string", "format": "date-time", "readOnly": true }, "vendor": { "$ref": "#/components/schemas/images_sourcingkit_vendor" } } }, "images_sourcingkit_source_create_request": { "type": "object", "properties": { "account": { "description": "Account identifier for the bucket (required for R2 vendor).", "type": "string" }, "bucket": { "description": "The name of the storage bucket.", "type": "string", "example": "my-images-bucket", "maxLength": 128, "minLength": 1 }, "name": { "description": "A human-readable name for the source.", "type": "string", "example": "my-s3-bucket", "maxLength": 128, "minLength": 1 }, "secret": { "description": "Storage credentials for accessing the bucket. Shape depends on vendor.", "type": "object", "writeOnly": true }, "vendor": { "$ref": "#/components/schemas/images_sourcingkit_vendor" } }, "required": [ "name", "bucket", "vendor", "secret" ] }, "images_sourcingkit_source_create_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/images_sourcingkit_source" } }, "type": "object" } ] }, "images_sourcingkit_source_list_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/images_sourcingkit_source" } } } } }, "type": "object" } ] }, "images_sourcingkit_source_single_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/images_sourcingkit_source" } }, "type": "object" } ] }, "images_sourcingkit_source_update_request": { "type": "object", "properties": { "name": { "description": "Updated name for the source.", "type": "string", "example": "my-renamed-bucket", "maxLength": 128, "minLength": 1 } }, "required": [ "name" ] }, "images_sourcingkit_source_update_response": { "allOf": [ { "$ref": "#/components/schemas/images_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/images_sourcingkit_source" } }, "type": "object" } ] }, "images_sourcingkit_vendor": { "description": "The cloud storage vendor of the source bucket.", "type": "string", "example": "s3", "enum": [ "s3", "r2" ] }, "infra_AccountTag": { "description": "Account identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "title": "account_id" }, "infra_ApiTlsSettings": { "description": "TLS settings for a connectivity service.\n\nIf omitted, the default mode (`verify_full`) is used.", "type": "object", "properties": { "cert_verification_mode": { "description": "TLS certificate verification mode for the connection to the origin.\n\n- `\"verify_full\"` — verify certificate chain and hostname (default)\n- `\"verify_ca\"` — verify certificate chain only, skip hostname check\n- `\"disabled\"` — do not verify the server certificate at all", "type": "string", "example": "verify_full" } }, "required": [ "cert_verification_mode" ] }, "infra_BatchReplaceTargetTagsItem": { "type": "object", "properties": { "tags": { "type": "object", "additionalProperties": { "type": "string" } }, "target_id": { "$ref": "#/components/schemas/infra_TargetId" } }, "required": [ "target_id", "tags" ] }, "infra_ConnectivityServiceArray": { "type": "array", "items": { "$ref": "#/components/schemas/infra_ServiceConfig" } }, "infra_DualStackHost": { "type": "object", "properties": { "ipv4": { "type": "string", "example": "10.0.0.1" }, "ipv6": { "type": "string", "example": "fe80::1" }, "network": { "$ref": "#/components/schemas/infra_Network" } }, "example": { "ipv4": "10.0.0.1", "ipv6": "fe80::1", "network": { "tunnel_id": "0191dce4-9ab4-7fce-b660-8e5dec5172da" } }, "required": [ "ipv4", "ipv6", "network" ] }, "infra_HostnameHost": { "type": "object", "properties": { "hostname": { "type": "string", "example": "example.com" }, "resolver_network": { "$ref": "#/components/schemas/infra_ResolverNetwork" } }, "example": { "hostname": "example.com", "resolver_network": { "resolver_ips": [ "10.0.0.1" ], "tunnel_id": "0191dce4-9ab4-7fce-b660-8e5dec5172da" } }, "required": [ "hostname", "resolver_network" ] }, "infra_HttpServiceConfig": { "example": { "host": { "ipv4": "10.0.0.1", "network": { "tunnel_id": "0191dce4-9ab4-7fce-b660-8e5dec5172da" } }, "http_port": 8080, "https_port": 8443, "name": "web-app", "type": "http" }, "allOf": [ { "$ref": "#/components/schemas/infra_ServiceCommon" }, { "properties": { "http_port": { "type": "integer", "format": "int32", "example": 8080, "minimum": 1, "nullable": true }, "https_port": { "type": "integer", "format": "int32", "example": 8443, "minimum": 1, "nullable": true } }, "type": "object" } ] }, "infra_IPInfo": { "description": "The IPv4/IPv6 address that identifies where to reach a target", "type": "object", "properties": { "ipv4": { "description": "The target's IPv4 address", "type": "object", "properties": { "ip_addr": { "description": "IP address of the target", "type": "string", "example": "187.26.29.249", "x-auditable": true }, "virtual_network_id": { "description": "(optional) Private virtual network identifier for the target. If omitted, the default virtual network ID will be used.", "type": "string", "format": "uuid", "example": "c77b744e-acc8-428f-9257-6878c046ed55", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } } }, "ipv6": { "description": "The target's IPv6 address", "type": "object", "properties": { "ip_addr": { "description": "IP address of the target", "type": "string", "example": "64c0:64e8:f0b4:8dbf:7104:72b0:ec8f:f5e0", "x-auditable": true }, "virtual_network_id": { "description": "(optional) Private virtual network identifier for the target. If omitted, the default virtual network ID will be used.", "type": "string", "format": "uuid", "example": "c77b744e-acc8-428f-9257-6878c046ed55", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } } } } }, "infra_IPv4Host": { "type": "object", "properties": { "ipv4": { "type": "string", "example": "10.0.0.1" }, "network": { "$ref": "#/components/schemas/infra_Network" } }, "example": { "ipv4": "10.0.0.1", "network": { "tunnel_id": "0191dce4-9ab4-7fce-b660-8e5dec5172da" } }, "required": [ "ipv4", "network" ] }, "infra_IPv6Host": { "type": "object", "properties": { "ipv6": { "type": "string", "example": "fe80::1" }, "network": { "$ref": "#/components/schemas/infra_Network" } }, "example": { "ipv6": "fe80::1", "network": { "tunnel_id": "0191dce4-9ab4-7fce-b660-8e5dec5172da" } }, "required": [ "ipv6", "network" ] }, "infra_Network": { "type": "object", "properties": { "tunnel_id": { "type": "string", "format": "uuid", "example": "0191dce4-9ab4-7fce-b660-8e5dec5172da" } }, "required": [ "tunnel_id" ] }, "infra_ResolverNetwork": { "type": "object", "properties": { "resolver_ips": { "type": "array", "items": { "type": "string" }, "nullable": true }, "tunnel_id": { "type": "string", "format": "uuid", "example": "0191dce4-9ab4-7fce-b660-8e5dec5172da" } }, "required": [ "tunnel_id" ] }, "infra_ServiceCommon": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "example": "2024-01-15T09:30:00Z", "readOnly": true }, "host": { "$ref": "#/components/schemas/infra_ServiceHost" }, "name": { "type": "string", "example": "web-server" }, "service_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "readOnly": true }, "tls_settings": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/infra_ApiTlsSettings" } ], "nullable": true }, "type": { "$ref": "#/components/schemas/infra_ServiceType" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-01-15T10:45:00Z", "readOnly": true } }, "required": [ "name", "type", "host" ] }, "infra_ServiceConfig": { "discriminator": { "mapping": { "http": "#/components/schemas/infra_HttpServiceConfig", "tcp": "#/components/schemas/infra_TcpServiceConfig" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/infra_HttpServiceConfig" }, { "$ref": "#/components/schemas/infra_TcpServiceConfig" } ] }, "infra_ServiceHost": { "oneOf": [ { "$ref": "#/components/schemas/infra_IPv4Host" }, { "$ref": "#/components/schemas/infra_IPv6Host" }, { "$ref": "#/components/schemas/infra_DualStackHost" }, { "$ref": "#/components/schemas/infra_HostnameHost" } ] }, "infra_ServiceType": { "type": "string", "enum": [ "tcp", "http" ] }, "infra_SortingDirection": { "type": "string", "enum": [ "asc", "desc" ] }, "infra_Target": { "type": "object", "properties": { "created_at": { "description": "Date and time at which the target was created", "type": "string", "format": "date-time", "example": "2019-08-24T14:15:22Z" }, "hostname": { "description": "A non-unique field that refers to a target", "type": "string", "example": "infra-access-target" }, "id": { "$ref": "#/components/schemas/infra_TargetId" }, "ip": { "$ref": "#/components/schemas/infra_IPInfo" }, "modified_at": { "description": "Date and time at which the target was modified", "type": "string", "format": "date-time", "example": "2019-08-24T14:15:22Z" }, "tags": { "description": "Tags assigned to the target. Empty when no tags are assigned.", "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "id", "hostname", "ip", "created_at", "modified_at" ] }, "infra_TargetArray": { "type": "array", "items": { "$ref": "#/components/schemas/infra_Target" } }, "infra_TargetId": { "description": "Target identifier", "type": "string", "format": "uuid", "example": "0191dce4-9ab4-7fce-b660-8e5dec5172da", "maxLength": 36, "title": "target_id", "x-auditable": true }, "infra_TcpServiceConfig": { "example": { "host": { "ipv4": "10.0.0.1", "network": { "tunnel_id": "0191dce4-9ab4-7fce-b660-8e5dec5172da" } }, "name": "postgres-db", "tcp_port": 5432, "type": "tcp" }, "allOf": [ { "$ref": "#/components/schemas/infra_ServiceCommon" }, { "properties": { "app_protocol": { "type": "string", "example": "postgresql", "enum": [ "postgresql", "mysql" ], "nullable": true }, "tcp_port": { "type": "integer", "format": "int32", "example": 5432, "minimum": 1, "nullable": true } }, "type": "object" } ] }, "infra_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/infra_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "infra_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/infra_messages" }, "messages": { "$ref": "#/components/schemas/infra_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "infra_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/infra_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/infra_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "infra_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/infra_api-response-common" } ] }, "infra_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "intel-sinkholes_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/intel-sinkholes_messages" }, "messages": { "$ref": "#/components/schemas/intel-sinkholes_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "intel-sinkholes_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/intel-sinkholes_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/intel-sinkholes_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "intel-sinkholes_api_response_common_failure": { "allOf": [ { "$ref": "#/components/schemas/intel-sinkholes_api-response-common-failure" } ] }, "intel-sinkholes_api_response_single_empty": { "allOf": [ { "$ref": "#/components/schemas/intel-sinkholes_api-response-common" }, { "properties": { "result": { "type": "object" } } } ] }, "intel-sinkholes_identifier": { "description": "An identifier for the resource.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "intel-sinkholes_ingress_collection_response": { "allOf": [ { "$ref": "#/components/schemas/intel-sinkholes_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/intel-sinkholes_ingress_item" } } } } ] }, "intel-sinkholes_ingress_create_params": { "type": "object", "properties": { "cidr": { "description": "The CIDR block for the ingress rule in IPv4 or IPv6 notation (e.g., 192.0.2.0/24). Provide a Cloudflare BYOIP CIDR that your account owns.", "type": "string" } }, "required": [ "cidr" ] }, "intel-sinkholes_ingress_item": { "type": "object", "properties": { "cidr": { "description": "The CIDR block for the ingress rule.", "type": "string" }, "created_on": { "description": "The date and time when the ingress rule was created.", "type": "string", "format": "date-time" }, "id": { "description": "The unique identifier for the ingress rule.", "type": "string" }, "modified_on": { "description": "The date and time when the ingress rule was last modified.", "type": "string", "format": "date-time" }, "sinkhole_id": { "description": "The sinkhole this ingress rule belongs to.", "type": "string" }, "zone_tag": { "description": "The zone tag associated with this ingress rule.", "type": "string" } }, "example": { "cidr": "192.0.2.0/24", "created_on": "2023-06-01T10:00:00Z", "id": "de32ae5203724ed08dcc26e971a4d22f", "modified_on": "2023-06-15T14:30:00Z", "sinkhole_id": "93defa6e909e464e8c89a85859f36d3c", "zone_tag": "4c961e9d94f40aa922775483b9ee18cf" } }, "intel-sinkholes_ingress_single_response": { "allOf": [ { "$ref": "#/components/schemas/intel-sinkholes_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/intel-sinkholes_ingress_item" } } } ] }, "intel-sinkholes_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "intel-sinkholes_sinkhole_collection_response": { "allOf": [ { "$ref": "#/components/schemas/intel-sinkholes_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/intel-sinkholes_sinkhole_item" } } } } ] }, "intel-sinkholes_sinkhole_create_params": { "type": "object", "properties": { "name": { "description": "The name of the sinkhole.", "type": "string" }, "r2_bucket": { "description": "The name of the R2 bucket to store results. Required if you want to store large request bodies in R2.", "type": "string" }, "r2_id": { "description": "The id of the R2 instance. Required if you want to store large request bodies in R2.", "type": "string" }, "r2_secret": { "description": "The secret key for the R2 API token. Required if you want to store large request bodies in R2.", "type": "string", "writeOnly": true } }, "required": [ "name" ] }, "intel-sinkholes_sinkhole_item": { "type": "object", "properties": { "account_tag": { "description": "The account tag that owns this sinkhole.", "type": "string" }, "created_on": { "description": "The date and time when the sinkhole was created.", "type": "string", "format": "date-time" }, "id": { "description": "The unique identifier for the sinkhole.", "type": "string" }, "modified_on": { "description": "The date and time when the sinkhole was last modified.", "type": "string", "format": "date-time" }, "name": { "description": "The name of the sinkhole.", "type": "string" }, "r2_bucket": { "description": "The name of the R2 bucket to store results.", "type": "string" }, "r2_id": { "description": "The id of the R2 instance.", "type": "string" } }, "example": { "account_tag": "233f45e61fd1f7e21e1e154ede4q2859", "created_on": "2023-05-12T12:21:56.777653Z", "id": "93defa6e909e464e8c89a85859f36d3c", "modified_on": "2023-06-18T03:13:34.123321Z", "name": "my_sinkhole", "r2_bucket": "my_bucket", "r2_id": "example_r2_id" } }, "intel-sinkholes_sinkhole_single_response": { "allOf": [ { "$ref": "#/components/schemas/intel-sinkholes_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/intel-sinkholes_sinkhole_item" } } } ] }, "intel_additional_information": { "description": "Additional information related to the host name.", "type": "object", "properties": { "suspected_malware_family": { "description": "Suspected DGA malware family.", "type": "string", "example": "", "x-auditable": true } } }, "intel_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/intel_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "nullable": true }, "result_info": { "$ref": "#/components/schemas/intel_result_info" } }, "type": "object" } ] }, "intel_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/intel_messages" }, "messages": { "$ref": "#/components/schemas/intel_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "intel_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/intel_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/intel_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false } }, "required": [ "success", "errors", "messages", "result" ] }, "intel_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/intel_schemas-api-response-common" } ] }, "intel_application": { "description": "Application that the hostname belongs to.", "type": "object", "properties": { "id": { "type": "integer", "x-auditable": true }, "name": { "type": "string", "example": "CLOUDFLARE", "x-auditable": true } } }, "intel_asn": { "type": "integer", "x-auditable": true }, "intel_asn_components-schemas-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/intel_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/intel_asn" } }, "type": "object" } ] }, "intel_asn_country": { "type": "string", "example": "US", "x-auditable": true }, "intel_asn_description": { "type": "string", "example": "CLOUDFLARENET", "x-auditable": true }, "intel_asn_type": { "description": "Infrastructure type of this ASN.", "type": "string", "example": "hosting_provider", "enum": [ "hosting_provider", "isp", "organization" ], "x-auditable": true }, "intel_categories_with_super_category_ids_example_empty": { "type": "array", "items": { "$ref": "#/components/schemas/intel_category_with_super_category_id" }, "example": [] }, "intel_category_with_super_category_id": { "type": "object", "properties": { "id": { "type": "integer", "x-auditable": true }, "name": { "type": "string", "x-auditable": true }, "super_category_id": { "type": "integer", "x-auditable": true } } }, "intel_collection_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/intel_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "properties": { "additional_information": { "$ref": "#/components/schemas/intel_additional_information" }, "application": { "$ref": "#/components/schemas/intel_application" }, "content_categories": { "$ref": "#/components/schemas/intel_content_categories" }, "domain": { "$ref": "#/components/schemas/intel_domain_name" }, "inherited_content_categories": { "$ref": "#/components/schemas/intel_categories_with_super_category_ids_example_empty" }, "inherited_from": { "$ref": "#/components/schemas/intel_inherited_from" }, "inherited_risk_types": { "$ref": "#/components/schemas/intel_categories_with_super_category_ids_example_empty" }, "popularity_rank": { "$ref": "#/components/schemas/intel_popularity_rank" }, "risk_score": { "$ref": "#/components/schemas/intel_risk_score" }, "risk_types": { "$ref": "#/components/schemas/intel_categories_with_super_category_ids_example_empty" } }, "type": "object" } } }, "type": "object" } ] }, "intel_components-schemas-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/intel_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/intel_ip-list" } } }, "type": "object" } ] }, "intel_components-schemas-single_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/intel_schemas-api-response-collection" }, { "properties": { "result": { "$ref": "#/components/schemas/intel_passive-dns-by-ip" } }, "type": "object" } ] }, "intel_content_categories": { "type": "array", "items": { "description": "Current content categories.", "properties": { "id": { "type": "integer", "x-auditable": true }, "name": { "type": "string", "x-auditable": true }, "super_category_id": { "type": "integer", "x-auditable": true } }, "type": "object" }, "example": [ { "id": 155, "name": "Technology", "super_category_id": 26 } ] }, "intel_count": { "description": "Total results returned based on your search parameters.", "type": "number", "example": 1 }, "intel_domain": { "type": "object", "properties": { "additional_information": { "$ref": "#/components/schemas/intel_additional_information" }, "application": { "$ref": "#/components/schemas/intel_application" }, "content_categories": { "$ref": "#/components/schemas/intel_content_categories" }, "domain": { "$ref": "#/components/schemas/intel_domain_name" }, "inherited_content_categories": { "$ref": "#/components/schemas/intel_categories_with_super_category_ids_example_empty" }, "inherited_from": { "$ref": "#/components/schemas/intel_inherited_from" }, "inherited_risk_types": { "$ref": "#/components/schemas/intel_categories_with_super_category_ids_example_empty" }, "popularity_rank": { "$ref": "#/components/schemas/intel_popularity_rank" }, "resolves_to_refs": { "$ref": "#/components/schemas/intel_resolves_to_refs" }, "risk_score": { "$ref": "#/components/schemas/intel_risk_score" }, "risk_types": { "$ref": "#/components/schemas/intel_categories_with_super_category_ids_example_empty" } } }, "intel_domain-history": { "type": "object", "properties": { "categorizations": { "type": "array", "items": { "properties": { "categories": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 155 }, "name": { "type": "string", "example": "Technology" } }, "type": "object" }, "example": [ { "id": 155, "name": "Technology" } ] }, "end": { "type": "string", "format": "date", "example": "2021-04-30", "x-auditable": true }, "start": { "type": "string", "format": "date", "example": "2021-04-01", "x-auditable": true } }, "type": "object" } }, "domain": { "$ref": "#/components/schemas/intel_domain_name" } } }, "intel_domain_name": { "type": "string", "example": "cloudflare.com", "x-auditable": true }, "intel_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "intel_inherited_content_categories": { "$ref": "#/components/schemas/intel_categories_with_super_category_ids_example_empty" }, "intel_inherited_from": { "description": "Domain from which `inherited_content_categories` and `inherited_risk_types` are inherited, if applicable.", "type": "string", "x-auditable": true }, "intel_inherited_risk_types": { "$ref": "#/components/schemas/intel_categories_with_super_category_ids_example_empty" }, "intel_ip": { "type": "string", "anyOf": [ { "$ref": "#/components/schemas/intel_ipv4" }, { "$ref": "#/components/schemas/intel_ipv6" } ], "x-auditable": true }, "intel_ip-list": { "type": "object", "properties": { "description": { "type": "string", "x-auditable": true }, "id": { "type": "integer", "x-auditable": true }, "name": { "type": "string", "example": "Malware", "x-auditable": true } } }, "intel_ipv4": { "type": "string", "format": "ipv4", "example": "192.0.2.0", "x-auditable": true }, "intel_ipv6": { "type": "string", "format": "ipv6", "example": "2001:0DB8::", "x-auditable": true }, "intel_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "intel_miscategorization": { "type": "object", "properties": { "content_adds": { "description": "Content category IDs to add.", "type": "array", "items": { "type": "integer", "x-auditable": true }, "example": [ 82 ] }, "content_removes": { "description": "Content category IDs to remove.", "type": "array", "items": { "type": "integer", "x-auditable": true }, "example": [ 155 ] }, "indicator_type": { "type": "string", "example": "domain", "enum": [ "domain", "ipv4", "ipv6", "url" ], "x-auditable": true }, "ip": { "description": "Provide only if indicator_type is `ipv4` or `ipv6`.", "type": "string", "nullable": true, "x-auditable": true }, "security_adds": { "description": "Security category IDs to add.", "type": "array", "items": { "type": "integer", "x-auditable": true }, "example": [ 117, 131 ] }, "security_removes": { "description": "Security category IDs to remove.", "type": "array", "items": { "type": "integer", "x-auditable": true }, "example": [ 83 ] }, "url": { "description": "Provide only if indicator_type is `domain` or `url`. Example if indicator_type is `domain`: `example.com`. Example if indicator_type is `url`: `https://example.com/news/`.", "type": "string", "x-auditable": true } } }, "intel_page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "intel_passive-dns-by-ip": { "type": "object", "properties": { "count": { "description": "Total results returned based on your search parameters.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "reverse_records": { "description": "Reverse DNS look-ups observed during the time period.", "type": "array", "items": { "properties": { "first_seen": { "description": "First seen date of the DNS record during the time period.", "type": "string", "format": "date", "example": "2021-04-01", "x-auditable": true }, "hostname": { "description": "Hostname that the IP was observed resolving to.", "type": "string", "x-auditable": true }, "last_seen": { "description": "Last seen date of the DNS record during the time period.", "type": "string", "format": "date", "example": "2021-04-30", "x-auditable": true } }, "type": "object" } } } }, "intel_per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "intel_phishing-url-info": { "type": "object", "properties": { "categorizations": { "description": "List of categorizations applied to this submission.", "type": "array", "items": { "properties": { "category": { "description": "Name of the category applied.", "type": "string", "example": "PHISHING", "x-auditable": true }, "verification_status": { "description": "Result of human review for this categorization.", "type": "string", "example": "confirmed", "x-auditable": true } }, "type": "object" } }, "model_results": { "description": "List of model results for completed scans.", "type": "array", "items": { "properties": { "model_name": { "description": "Name of the model.", "type": "string", "example": "MACHINE_LEARNING_v2", "x-auditable": true }, "model_score": { "description": "This is the score that is outputted by the model for this submission.", "type": "number", "example": 0.024 } }, "type": "object" } }, "rule_matches": { "description": "List of signatures that matched against site content found when crawling the URL.", "type": "array", "items": { "properties": { "banning": { "description": "For internal use.", "type": "boolean" }, "blocking": { "description": "For internal use.", "type": "boolean" }, "description": { "description": "Description of the signature that matched.", "type": "string", "example": "Match frequently used social followers phishing kit", "x-auditable": true }, "name": { "description": "Name of the signature that matched.", "type": "string", "example": "phishkit.social_followers", "x-auditable": true } }, "type": "object" } }, "scan_status": { "description": "Status of the most recent scan found.", "type": "object", "properties": { "last_processed": { "description": "Timestamp of when the submission was processed.", "type": "string", "example": "Wed, 26 Oct 2022 16:04:51 GMT", "x-auditable": true }, "scan_complete": { "description": "For internal use.", "type": "boolean" }, "status_code": { "description": "Status code that the crawler received when loading the submitted URL.", "type": "integer", "x-auditable": true }, "submission_id": { "description": "ID of the most recent submission.", "type": "integer", "x-auditable": true } } }, "screenshot_download_signature": { "description": "For internal use.", "type": "string" }, "screenshot_path": { "description": "For internal use.", "type": "string" }, "url": { "description": "URL that was submitted.", "type": "string", "example": "https://www.cloudflare.com", "x-auditable": true } } }, "intel_phishing-url-info_components-schemas-single_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/intel_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/intel_phishing-url-info" } }, "type": "object" } ] }, "intel_phishing-url-submit": { "type": "object", "properties": { "excluded_urls": { "description": "URLs that were excluded from scanning because their domain is in our no-scan list.", "type": "array", "items": { "properties": { "url": { "description": "URL that was excluded.", "type": "string", "example": "https://developers.cloudflare.com", "x-auditable": true } }, "type": "object" } }, "skipped_urls": { "description": "URLs that were skipped because the same URL is currently being scanned.", "type": "array", "items": { "properties": { "url": { "description": "URL that was skipped.", "type": "string", "example": "https://www.cloudflare.com/developer-week/", "x-auditable": true }, "url_id": { "description": "ID of the submission of that URL that is currently scanning.", "type": "integer", "example": 2, "x-auditable": true } }, "type": "object" } }, "submitted_urls": { "description": "URLs that were successfully submitted for scanning.", "type": "array", "items": { "properties": { "url": { "description": "URL that was submitted.", "type": "string", "example": "https://www.cloudflare.com", "x-auditable": true }, "url_id": { "description": "ID assigned to this URL submission. Used to retrieve scanning results.", "type": "integer", "example": 1, "x-auditable": true } }, "type": "object" } } } }, "intel_phishing-url-submit_components-schemas-single_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/intel_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/intel_phishing-url-submit" } }, "type": "object" } ] }, "intel_popularity_rank": { "description": "Global Cloudflare 100k ranking for the last 30 days, if available for the hostname. The top ranked domain is 1, the lowest ranked domain is 100,000.", "type": "integer", "x-auditable": true }, "intel_resolves_to_ref": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/intel_stix_identifier" }, "value": { "description": "IP address or domain name.", "type": "string", "example": "192.0.2.0", "x-auditable": true } } }, "intel_resolves_to_refs": { "description": "Specifies a list of references to one or more IP addresses or domain names that the domain name currently resolves to.", "type": "array", "items": { "$ref": "#/components/schemas/intel_resolves_to_ref" } }, "intel_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/intel_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/intel_domain-history" } } }, "type": "object" } ] }, "intel_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 } } }, "intel_risk_score": { "description": "Hostname risk score, which is a value between 0 (lowest risk) to 1 (highest risk).", "type": "number" }, "intel_risk_types": { "$ref": "#/components/schemas/intel_categories_with_super_category_ids_example_empty" }, "intel_schemas-api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/intel_schemas-api-response-common" }, { "properties": { "result_info": { "$ref": "#/components/schemas/intel_schemas-result_info" } }, "type": "object" } ] }, "intel_schemas-api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/intel_schemas-messages" }, "messages": { "$ref": "#/components/schemas/intel_schemas-messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "intel_schemas-asn": { "type": "object", "properties": { "asn": { "$ref": "#/components/schemas/intel_asn" }, "country": { "$ref": "#/components/schemas/intel_asn_country" }, "description": { "$ref": "#/components/schemas/intel_asn_description" }, "domain_count": { "type": "integer", "x-auditable": true }, "top_domains": { "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "example.com" ] }, "type": { "$ref": "#/components/schemas/intel_asn_type" } } }, "intel_schemas-ip": { "type": "object", "properties": { "belongs_to_ref": { "description": "Specifies a reference to the autonomous systems (AS) that the IP address belongs to.", "type": "object", "properties": { "country": { "type": "string", "example": "US", "x-auditable": true }, "description": { "type": "string", "example": "CLOUDFLARENET", "x-auditable": true }, "id": { "type": "string", "example": "autonomous-system--2fa28d71-3549-5a38-af05-770b79ad6ea8", "x-auditable": true }, "type": { "description": "Infrastructure type of this ASN.", "type": "string", "example": "hosting_provider", "enum": [ "hosting_provider", "isp", "organization" ], "x-auditable": true }, "value": { "type": "string", "x-auditable": true } } }, "ip": { "$ref": "#/components/schemas/intel_ip" }, "risk_types": { "type": "array", "items": { "properties": { "id": { "type": "number" }, "name": { "type": "string", "x-auditable": true }, "super_category_id": { "type": "number" } }, "type": "object" }, "example": [ { "id": 131, "name": "Phishing", "super_category_id": 21 } ] } } }, "intel_schemas-messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "intel_schemas-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/intel_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/intel_schemas-ip" } } }, "type": "object" } ] }, "intel_schemas-result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 } } }, "intel_schemas-single_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/intel_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/intel_whois" } }, "type": "object" } ] }, "intel_single_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/intel_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/intel_domain" } }, "type": "object" } ] }, "intel_start_end_params": { "type": "object", "properties": { "end": { "description": "Defaults to the current date.", "type": "string", "format": "date", "example": "2021-04-30", "x-auditable": true }, "start": { "description": "Defaults to 30 days before the end parameter value.", "type": "string", "format": "date", "example": "2021-04-01", "x-auditable": true } } }, "intel_stix_identifier": { "description": "STIX 2.1 identifier: https://docs.oasis-open.org/cti/stix/v2.1/cs02/stix-v2.1-cs02.html#_64yvzeku5a5c.", "type": "string", "example": "ipv4-addr--baa568ec-6efe-5902-be55-0663833db537", "x-auditable": true }, "intel_url": { "description": "URL(s) to filter submissions results by.", "type": "string", "format": "uri", "example": "https://www.cloudflare.com", "x-auditable": true }, "intel_url_intelligence": { "type": "object", "properties": { "content_categories": { "description": "Content categories associated with this URL.", "type": "array", "items": { "$ref": "#/components/schemas/intel_url_intelligence_category_with_source" }, "example": [ { "id": 155, "name": "Technology", "source_id": 1, "super_category_id": 26 } ] }, "full_url": { "description": "The full URL that was looked up.", "type": "string", "example": "https://example.com/path", "x-auditable": true }, "hostname": { "description": "The hostname of the URL.", "type": "string", "example": "example.com", "x-auditable": true }, "risk_type": { "description": "Security risk types associated with this URL.", "type": "array", "items": { "$ref": "#/components/schemas/intel_url_intelligence_category_with_source" }, "example": [] }, "url_path": { "description": "The path component of the URL.", "type": "string", "example": "/path", "x-auditable": true } }, "required": [ "full_url", "hostname", "url_path", "risk_type", "content_categories" ] }, "intel_url_intelligence_category_with_source": { "type": "object", "properties": { "id": { "type": "integer", "x-auditable": true }, "name": { "type": "string", "x-auditable": true }, "source_id": { "type": "integer", "x-auditable": true }, "super_category_id": { "type": "integer", "x-auditable": true } } }, "intel_url_intelligence_single_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/intel_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/intel_url_intelligence" } }, "type": "object" } ] }, "intel_url_param": { "type": "object", "properties": { "url": { "$ref": "#/components/schemas/intel_url" } } }, "intel_whois": { "type": "object", "properties": { "created_date": { "type": "string", "format": "date", "example": "2009-02-17", "x-auditable": true }, "domain": { "$ref": "#/components/schemas/intel_domain_name" }, "nameservers": { "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "ns3.cloudflare.com", "ns4.cloudflare.com", "ns5.cloudflare.com", "ns6.cloudflare.com", "ns7.cloudflare.com" ] }, "registrant": { "type": "string", "example": "DATA REDACTED", "x-auditable": true }, "registrant_country": { "type": "string", "example": "United States", "x-auditable": true }, "registrant_email": { "type": "string", "example": "https://domaincontact.cloudflareregistrar.com/cloudflare.com", "x-auditable": true }, "registrant_org": { "type": "string", "example": "DATA REDACTED", "x-auditable": true }, "registrar": { "type": "string", "example": "Cloudflare, Inc.", "x-auditable": true }, "updated_date": { "type": "string", "format": "date", "example": "2017-05-24", "x-auditable": true } } }, "kamino_environment": { "type": "object", "properties": { "expression": { "type": "string" }, "http_application_id": { "type": "string", "nullable": true }, "locked_on_deployment": { "type": "boolean", "nullable": true }, "name": { "type": "string" }, "position": { "$ref": "#/components/schemas/kamino_environment_position" }, "ref": { "type": "string" }, "version": { "type": "integer", "format": "int64", "nullable": true } }, "required": [ "name", "ref", "version", "expression", "locked_on_deployment", "position" ] }, "kamino_environment_position": { "type": "object", "properties": { "after": { "type": "string" }, "before": { "type": "string" } } }, "kamino_environments_request": { "type": "object", "properties": { "environments": { "type": "array", "items": { "$ref": "#/components/schemas/kamino_environment" } } }, "required": [ "environments" ] }, "kamino_environments_response": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/kamino_message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/kamino_message" } }, "result": { "$ref": "#/components/schemas/kamino_environments_result" }, "success": { "type": "boolean" } }, "required": [ "result", "success", "errors", "messages" ] }, "kamino_environments_result": { "type": "object", "properties": { "environments": { "type": "array", "items": { "$ref": "#/components/schemas/kamino_environment" } } }, "required": [ "environments" ] }, "kamino_error_response": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/kamino_message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/kamino_message" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean" } }, "required": [ "result", "success", "errors", "messages" ] }, "kamino_message": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "lex_AvailableDestination": { "description": "A dataset type that the account or zone can create.", "type": "object", "properties": { "dataset": { "description": "Dataset type name (e.g. `http_requests`).", "type": "string" }, "object_type": { "description": "Whether this dataset type is account-scoped or zone-scoped.", "type": "string", "enum": [ "account", "zone" ] }, "schema": { "description": "JSON Schema that describes the fields this dataset exposes.", "type": "object", "properties": { "properties": { "type": "object", "additionalProperties": true }, "required": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "object" ] } } }, "timestamp_field": { "description": "The primary timestamp field name for this dataset.", "type": "string" } }, "required": [ "dataset", "timestamp_field", "schema", "object_type" ] }, "lex_AvailableDestinationListResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/lex_V4Error-2" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/lex_AvailableDestination" }, "nullable": true }, "success": { "type": "boolean" } }, "required": [ "success", "errors", "messages" ] }, "lex_CreateDatasetRequest": { "type": "object", "properties": { "dataset": { "description": "Dataset type name to create (e.g. `http_requests`).", "type": "string", "x-auditable": true }, "fields": { "description": "Controls which fields the API ingests. Defaults to all available\nfields when absent.\n", "type": "array", "items": { "$ref": "#/components/schemas/lex_LogField" }, "x-stainless-terraform-configurability": "computed_optional" }, "filter": { "description": "Optional Logpush filter predicate to restrict which events are ingested.\nIf provided, replaces the dataset's default filter entirely.\nSee [Logpush filters](https://developers.cloudflare.com/logs/reference/filters/)\nfor syntax and examples.\n", "type": "string", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "dataset" ] }, "lex_DatasetDetailResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/lex_V4Error-2" } }, "messages": { "type": "array", "items": { "type": "string", "x-auditable": true } }, "result": { "$ref": "#/components/schemas/lex_DatasetResponse" }, "success": { "type": "boolean", "x-auditable": true } }, "required": [ "success", "errors", "messages" ] }, "lex_DatasetResponse": { "allOf": [ { "$ref": "#/components/schemas/lex_DatasetSummary" }, { "properties": { "fields": { "description": "The field configuration for this dataset.\n", "type": "array", "items": { "$ref": "#/components/schemas/lex_LogField" }, "x-stainless-terraform-configurability": "computed_optional" }, "filter": { "description": "The Logpush filter predicate applied to this dataset. Omitted\nwhen no filter is set.\n", "type": "string", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "fields" ], "type": "object" } ] }, "lex_DatasetSummary": { "description": "A Log Explorer dataset summary. List endpoints return this type and omit\nfield configuration; use the single-dataset endpoint to retrieve it.\n", "type": "object", "properties": { "created_at": { "description": "RFC3339 timestamp recording when the API created this dataset.", "type": "string", "format": "date-time", "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "dataset": { "description": "Dataset type name (e.g. `http_requests`).", "type": "string", "x-auditable": true }, "dataset_id": { "description": "Unique dataset ID.", "type": "string", "pattern": "^[a-f0-9]{32}$", "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "deletion_protection": { "description": "Whether deletion is blocked. Set to `false` before deleting the dataset.", "type": "boolean", "default": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "enabled": { "description": "Whether log ingest is currently active for this dataset.", "type": "boolean", "default": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "object_id": { "description": "Public ID of the account or zone that owns this dataset.", "type": "string", "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "object_type": { "description": "Whether this dataset belongs to an account or a zone.", "type": "string", "enum": [ "account", "zone" ], "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "updated_at": { "description": "RFC3339 timestamp recording when the API last updated this dataset.", "type": "string", "format": "date-time", "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" } }, "required": [ "dataset", "object_type", "object_id", "created_at", "updated_at", "dataset_id", "enabled", "deletion_protection" ] }, "lex_DatasetSummaryListResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/lex_V4Error-2" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/lex_DatasetSummary" }, "nullable": true }, "success": { "type": "boolean" } }, "required": [ "success", "errors", "messages" ] }, "lex_ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/lex_V4Error" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "additionalProperties": true, "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] }, "lex_ErrorResponse-2": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/lex_V4Error-2" } }, "messages": { "type": "array", "items": { "type": "string", "x-auditable": true } }, "result": { "type": "object", "additionalProperties": true, "nullable": true, "x-auditable": true }, "success": { "type": "boolean", "enum": [ false ], "x-auditable": true } }, "required": [ "result", "success", "errors", "messages" ] }, "lex_LogField": { "type": "object", "properties": { "enabled": { "description": "Whether the API includes this field in log ingest.", "type": "boolean", "x-auditable": true }, "name": { "description": "Field name in lowercase.", "type": "string", "x-auditable": true } }, "required": [ "name", "enabled" ] }, "lex_QueryResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/lex_V4Error" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/lex_QueryRow" }, "nullable": true }, "success": { "type": "boolean" } }, "required": [ "success", "errors", "messages" ] }, "lex_QueryRow": { "type": "object", "additionalProperties": true }, "lex_UpdateDatasetRequest": { "type": "object", "properties": { "deletion_protection": { "description": "Set to `false` to allow deletion of this dataset.", "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "enabled": { "description": "Whether to enable or disable log ingest for this dataset.", "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "fields": { "description": "Controls which fields the API ingests after the update. Defaults\nto all available fields when absent.\n", "type": "array", "items": { "$ref": "#/components/schemas/lex_LogField" }, "x-stainless-terraform-configurability": "computed_optional" }, "filter": { "description": "Optional Logpush filter predicate to restrict which events are\ningested. If omitted, the existing filter is left unchanged. Set\nto an empty string (`\"\"`) to clear the filter. Otherwise,\nreplaces the dataset's filter entirely.\nSee [Logpush filters](https://developers.cloudflare.com/logs/reference/filters/)\nfor syntax and examples.\n", "type": "string", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "enabled" ] }, "lex_V4Error": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "lex_V4Error-2": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32", "x-auditable": true }, "message": { "type": "string", "x-auditable": true } }, "required": [ "code", "message" ] }, "lists_account_id": { "description": "The Account ID for this resource.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "minLength": 32, "readOnly": true, "x-auditable": true }, "lists_api-response-collection": { "type": "object", "allOf": [ { "properties": { "result": { "type": "array", "items": { "type": "object" }, "nullable": true } }, "type": "object" }, { "$ref": "#/components/schemas/lists_api-response-common" } ] }, "lists_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/lists_messages" }, "messages": { "$ref": "#/components/schemas/lists_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": { "type": "object" }, "type": "array" } ] }, "success": { "description": "Defines whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "lists_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/lists_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/lists_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Defines whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "lists_bulk-operation-response-single": { "allOf": [ { "properties": { "result": { "$ref": "#/components/schemas/lists_operation" } }, "type": "object" }, { "$ref": "#/components/schemas/lists_api-response-common" } ] }, "lists_bulk_operation_completed": { "type": "object", "properties": { "completed": { "$ref": "#/components/schemas/lists_completed" }, "id": { "$ref": "#/components/schemas/lists_operation_id" }, "status": { "description": "The current status of the asynchronous operation.", "type": "string", "example": "completed", "enum": [ "completed" ], "readOnly": true, "x-auditable": true } }, "required": [ "id", "status", "completed" ] }, "lists_bulk_operation_failed": { "type": "object", "properties": { "completed": { "$ref": "#/components/schemas/lists_completed" }, "error": { "description": "A message describing the error when the status is `failed`.", "type": "string", "example": "This list is at the maximum number of items", "readOnly": true, "x-auditable": true }, "id": { "$ref": "#/components/schemas/lists_operation_id" }, "status": { "description": "The current status of the asynchronous operation.", "type": "string", "example": "failed", "enum": [ "failed" ], "readOnly": true, "x-auditable": true } }, "required": [ "id", "status", "error", "completed" ] }, "lists_bulk_operation_pending_or_running": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/lists_operation_id" }, "status": { "description": "The current status of the asynchronous operation.", "type": "string", "example": "pending", "enum": [ "pending", "running" ], "readOnly": true, "x-auditable": true } }, "required": [ "id", "status" ] }, "lists_completed": { "description": "The RFC 3339 timestamp of when the operation was completed.", "type": "string", "example": "2020-01-01T08:00:00Z", "readOnly": true, "x-auditable": true }, "lists_created_on": { "description": "The RFC 3339 timestamp of when the list was created.", "type": "string", "example": "2020-01-01T08:00:00Z", "readOnly": true, "x-auditable": true }, "lists_description": { "description": "An informative summary of the list.", "type": "string", "example": "This is a note", "maxLength": 500, "x-auditable": true }, "lists_item": { "oneOf": [ { "$ref": "#/components/schemas/lists_list_item_ip_full" }, { "$ref": "#/components/schemas/lists_list_item_hostname_full" }, { "$ref": "#/components/schemas/lists_list_item_redirect_full" }, { "$ref": "#/components/schemas/lists_list_item_asn_full" } ] }, "lists_item-response-single": { "allOf": [ { "properties": { "result": { "$ref": "#/components/schemas/lists_item" } }, "type": "object" }, { "$ref": "#/components/schemas/lists_api-response-common" } ] }, "lists_item_asn": { "description": "Defines a non-negative 32 bit integer.", "type": "integer", "example": 5567, "x-auditable": true }, "lists_item_base": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/lists_item_comment" }, "created_on": { "$ref": "#/components/schemas/lists_created_on" }, "id": { "$ref": "#/components/schemas/lists_item_id" }, "modified_on": { "$ref": "#/components/schemas/lists_modified_on" } }, "example": { "comment": "Private IP address", "created_on": "2020-01-01T08:00:00Z", "id": "2c0fc9fa937b11eaa1b71c4d701ab86e", "modified_on": "2020-01-10T14:00:00Z" }, "required": [ "id", "created_on", "modified_on" ] }, "lists_item_comment": { "description": "Defines an informative summary of the list item.", "type": "string", "example": "Private IP address", "x-auditable": true }, "lists_item_comment_object": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/lists_item_comment" } } }, "lists_item_hostname": { "description": "Hostnames support ASCII(7) letters from a to z, the digits from 0 to 9, wildcards (*), and the hyphen (-).", "properties": { "exclude_exact_hostname": { "description": "Only applies to wildcard hostnames (e.g., *.example.com). When true (default), the rule blocks only subdomains. When false, the rule blocks both the root domain and subdomains.", "type": "boolean", "example": true }, "url_hostname": { "type": "string", "example": "example.com", "x-auditable": true } }, "required": [ "url_hostname" ] }, "lists_item_id": { "description": "Defines the unique ID of the item in the List.", "type": "string", "example": "34b12448945f11eaa1b71c4d701ab86e", "maxLength": 32, "minLength": 32, "readOnly": true, "x-auditable": true }, "lists_item_ip": { "description": "An IPv4 address, an IPv4 CIDR, an IPv6 address, or an IPv6 CIDR.", "type": "string", "example": "10.0.0.1", "x-auditable": true }, "lists_item_redirect": { "description": "The definition of the redirect.", "properties": { "include_subdomains": { "type": "boolean", "default": false, "x-auditable": true }, "preserve_path_suffix": { "type": "boolean", "default": false, "x-auditable": true }, "preserve_query_string": { "type": "boolean", "default": false, "x-auditable": true }, "source_url": { "type": "string", "example": "example.com/arch", "x-auditable": true }, "status_code": { "type": "integer", "default": 301, "enum": [ 301, 302, 307, 308 ], "x-auditable": true }, "subpath_matching": { "type": "boolean", "default": false, "x-auditable": true }, "target_url": { "type": "string", "example": "https://archlinux.org/", "x-auditable": true } }, "required": [ "source_url", "target_url" ] }, "lists_items": { "type": "array", "items": { "$ref": "#/components/schemas/lists_item" } }, "lists_items-list-response-collection": { "allOf": [ { "properties": { "result": { "$ref": "#/components/schemas/lists_items" }, "result_info": { "type": "object", "properties": { "cursors": { "type": "object", "properties": { "after": { "type": "string", "example": "yyy", "x-auditable": true }, "before": { "type": "string", "example": "xxx", "x-auditable": true } } } } } }, "type": "object" }, { "$ref": "#/components/schemas/lists_api-response-collection" } ] }, "lists_items-update-request-collection": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/lists_list_item_ip_comment" }, { "$ref": "#/components/schemas/lists_list_item_redirect_comment" }, { "$ref": "#/components/schemas/lists_list_item_hostname_comment" }, { "$ref": "#/components/schemas/lists_list_item_asn_comment" } ] } }, "lists_kind": { "description": "The type of the list. Each type supports specific list items (IP addresses, ASNs, hostnames or redirects).", "example": "ip", "enum": [ "ip", "redirect", "hostname", "asn" ] }, "lists_list": { "type": "object", "properties": { "created_on": { "$ref": "#/components/schemas/lists_created_on" }, "description": { "$ref": "#/components/schemas/lists_description" }, "id": { "$ref": "#/components/schemas/lists_list_id" }, "kind": { "$ref": "#/components/schemas/lists_kind" }, "modified_on": { "$ref": "#/components/schemas/lists_modified_on" }, "name": { "$ref": "#/components/schemas/lists_name" }, "num_items": { "$ref": "#/components/schemas/lists_num_items" }, "num_referencing_filters": { "$ref": "#/components/schemas/lists_num_referencing_filters" } }, "required": [ "id", "name", "kind", "num_items", "num_referencing_filters", "created_on", "modified_on" ] }, "lists_list-delete-response-collection": { "type": "object", "allOf": [ { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/lists_list_id" } }, "required": [ "id" ] } }, "type": "object" }, { "$ref": "#/components/schemas/lists_api-response-common" } ] }, "lists_list-response-collection": { "type": "object", "allOf": [ { "properties": { "result": { "$ref": "#/components/schemas/lists_list" } }, "type": "object" }, { "$ref": "#/components/schemas/lists_api-response-common" } ] }, "lists_list_id": { "description": "The unique ID of the list.", "type": "string", "example": "2c0fc9fa937b11eaa1b71c4d701ab86e", "maxLength": 32, "minLength": 32, "readOnly": true, "x-auditable": true }, "lists_list_item_asn_comment": { "allOf": [ { "$ref": "#/components/schemas/lists_list_item_asn_object" }, { "$ref": "#/components/schemas/lists_item_comment_object" } ] }, "lists_list_item_asn_full": { "allOf": [ { "$ref": "#/components/schemas/lists_list_item_asn_object" }, { "$ref": "#/components/schemas/lists_item_base" } ] }, "lists_list_item_asn_object": { "type": "object", "properties": { "asn": { "$ref": "#/components/schemas/lists_item_asn" } }, "required": [ "asn" ] }, "lists_list_item_hostname_comment": { "allOf": [ { "$ref": "#/components/schemas/lists_list_item_hostname_object" }, { "$ref": "#/components/schemas/lists_item_comment_object" } ] }, "lists_list_item_hostname_full": { "allOf": [ { "$ref": "#/components/schemas/lists_list_item_hostname_object" }, { "$ref": "#/components/schemas/lists_item_base" } ] }, "lists_list_item_hostname_object": { "type": "object", "properties": { "hostname": { "$ref": "#/components/schemas/lists_item_hostname" } }, "required": [ "hostname" ] }, "lists_list_item_ip_comment": { "allOf": [ { "$ref": "#/components/schemas/lists_list_item_ip_object" }, { "$ref": "#/components/schemas/lists_item_comment_object" } ] }, "lists_list_item_ip_full": { "allOf": [ { "$ref": "#/components/schemas/lists_list_item_ip_object" }, { "$ref": "#/components/schemas/lists_item_base" } ] }, "lists_list_item_ip_object": { "type": "object", "properties": { "ip": { "$ref": "#/components/schemas/lists_item_ip" } }, "required": [ "ip" ] }, "lists_list_item_redirect_comment": { "allOf": [ { "$ref": "#/components/schemas/lists_list_item_redirect_object" }, { "$ref": "#/components/schemas/lists_item_comment_object" } ] }, "lists_list_item_redirect_full": { "allOf": [ { "$ref": "#/components/schemas/lists_list_item_redirect_object" }, { "$ref": "#/components/schemas/lists_item_base" } ] }, "lists_list_item_redirect_object": { "type": "object", "properties": { "redirect": { "$ref": "#/components/schemas/lists_item_redirect" } }, "required": [ "redirect" ] }, "lists_lists-async-response": { "allOf": [ { "properties": { "result": { "type": "object", "properties": { "operation_id": { "$ref": "#/components/schemas/lists_operation_id" } }, "required": [ "operation_id" ] } }, "type": "object" }, { "$ref": "#/components/schemas/lists_api-response-collection" } ] }, "lists_lists-response-collection": { "type": "object", "allOf": [ { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/lists_list" } } }, "type": "object" }, { "$ref": "#/components/schemas/lists_api-response-collection" } ] }, "lists_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "lists_modified_on": { "description": "The RFC 3339 timestamp of when the list was last modified.", "type": "string", "example": "2020-01-10T14:00:00Z", "readOnly": true, "x-auditable": true }, "lists_name": { "description": "An informative name for the list. Use this name in filter and rule expressions.", "type": "string", "example": "list1", "maxLength": 50, "pattern": "^[a-zA-Z0-9_]+$", "x-auditable": true }, "lists_num_items": { "description": "The number of items in the list.", "type": "number", "example": 10, "readOnly": true, "x-auditable": true }, "lists_num_referencing_filters": { "description": "The number of [filters](/api/resources/filters/) referencing the list.", "type": "number", "example": 2, "readOnly": true, "x-auditable": true }, "lists_operation": { "oneOf": [ { "$ref": "#/components/schemas/lists_bulk_operation_pending_or_running" }, { "$ref": "#/components/schemas/lists_bulk_operation_completed" }, { "$ref": "#/components/schemas/lists_bulk_operation_failed" } ] }, "lists_operation_id": { "description": "The unique operation ID of the asynchronous action.", "type": "string", "example": "4da8780eeb215e6cb7f48dd981c4ea02", "readOnly": true, "x-auditable": true }, "load-balancing_Host": { "description": "The 'Host' header allows to override the hostname set in the HTTP request. Current support is 1 'Host' header override per origin.", "type": "array", "items": { "example": "example.com", "type": "string", "x-auditable": true } }, "load-balancing_adaptive_routing": { "description": "Controls features that modify the routing of requests to pools and origins in response to dynamic conditions, such as during the interval between active health monitoring requests. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin.", "type": "object", "properties": { "failover_across_pools": { "description": "Extends zero-downtime failover of requests to healthy origins from alternate pools, when no healthy alternate exists in the same pool, according to the failover order defined by traffic and origin steering. When set false (the default) zero-downtime failover will only occur between origins within the same pool. See `session_affinity_attributes` for control over when sessions are broken or reassigned.", "type": "boolean", "example": true, "default": false, "x-auditable": true } } }, "load-balancing_address": { "description": "The IP address (IPv4 or IPv6) of the origin, or its publicly addressable hostname. Hostnames entered here should resolve directly to the origin, and not be a hostname proxied by Cloudflare. To set an internal/reserved address, virtual_network_id must also be set.", "type": "string", "example": "0.0.0.0", "x-auditable": true }, "load-balancing_allow_insecure": { "description": "Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "load-balancing_analytics": { "type": "object", "properties": { "id": { "type": "integer", "default": 1 }, "origins": { "type": "array", "items": { "$ref": "#/components/schemas/load-balancing_origin-analytics" }, "example": [ { "address": "198.51.100.4", "changed": true, "enabled": true, "failure_reason": "No failures", "healthy": true, "ip": "198.51.100.4", "name": "some-origin" } ] }, "pool": { "type": "object", "example": { "changed": true, "healthy": true, "id": "74bc6a8b9b0dda3d651707a2928bad0c", "minimum_origins": 1, "name": "some-pool" } }, "timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z" } } }, "load-balancing_api-paginated-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-common" }, { "properties": { "result_info": { "$ref": "#/components/schemas/load-balancing_result_info" } }, "type": "object" } ], "required": [ "result_info" ] }, "load-balancing_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/load-balancing_messages" }, "messages": { "$ref": "#/components/schemas/load-balancing_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "load-balancing_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/load-balancing_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/load-balancing_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "load-balancing_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-common" }, { "properties": { "result": { "anyOf": [ { "nullable": true, "type": "object" }, { "nullable": true, "type": "string" } ] } }, "type": "object" } ] }, "load-balancing_check_regions": { "description": "A list of regions from which to run health checks. Null means every Cloudflare data center.", "type": "array", "items": { "description": "WNAM: Western North America, ENAM: Eastern North America, WEU: Western Europe, EEU: Eastern Europe, NSAM: Northern South America, SSAM: Southern South America, OC: Oceania, ME: Middle East, NAF: North Africa, SAF: South Africa, SAS: Southern Asia, SEAS: South East Asia, NEAS: North East Asia, CHINA: China (ENTERPRISE customers only), ALL_REGIONS: all regions (ENTERPRISE customers only).", "enum": [ "WNAM", "ENAM", "WEU", "EEU", "NSAM", "SSAM", "OC", "ME", "NAF", "SAF", "SAS", "SEAS", "NEAS", "CHINA", "ALL_REGIONS" ], "type": "string", "x-auditable": true }, "example": [ "WEU", "ENAM" ], "nullable": true }, "load-balancing_components-schemas-description": { "description": "Object description.", "type": "string", "example": "Load Balancer for www.example.com", "x-auditable": true }, "load-balancing_components-schemas-enabled": { "description": "Whether to enable (the default) this load balancer.", "type": "boolean", "example": true, "default": true, "x-auditable": true }, "load-balancing_components-schemas-id_response": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-identifier" } } } }, "type": "object" } ] }, "load-balancing_components-schemas-identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "load-balancing_components-schemas-name": { "description": "The DNS hostname to associate with your Load Balancer. If this hostname already exists as a DNS record in Cloudflare's DNS, the Load Balancer will take precedence and the DNS record will not be used.", "type": "string", "example": "www.example.com", "x-auditable": true }, "load-balancing_components-schemas-response_collection": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-paginated-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/load-balancing_analytics" } } }, "type": "object" } ] }, "load-balancing_components-schemas-single_response": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-single" }, { "properties": { "result": { "description": "A list of countries and subdivisions mapped to a region.", "type": "object", "example": { "iso_standard": "Country and subdivision codes follow ISO 3166-1 alpha-2 and ISO 3166-2", "regions": [ { "countries": [ { "country_code_a2": "CA", "country_name": "Canada", "country_subdivisions": [ { "subdivision_code_a2": "AB", "subdivision_name": "Alberta" }, { "subdivision_code_a2": "BC", "subdivision_name": "British Columbia" } ] }, { "country_code_a2": "HT", "country_name": "Haiti" }, { "country_code_a2": "MX", "country_name": "Mexico" }, { "country_code_a2": "US", "country_name": "United States", "country_subdivisions": [ { "subdivision_code_a2": "AZ", "subdivision_name": "Arizona" }, { "subdivision_code_a2": "CA", "subdivision_name": "California" }, { "subdivision_code_a2": "CO", "subdivision_name": "Colorado" }, { "subdivision_code_a2": "HI", "subdivision_name": "Hawaii" }, { "subdivision_code_a2": "MN", "subdivision_name": "Minnesota" }, { "subdivision_code_a2": "MO", "subdivision_name": "Missouri" }, { "subdivision_code_a2": "NV", "subdivision_name": "Nevada" }, { "subdivision_code_a2": "OR", "subdivision_name": "Oregon" }, { "subdivision_code_a2": "TX", "subdivision_name": "Texas" }, { "subdivision_code_a2": "UT", "subdivision_name": "Utah" }, { "subdivision_code_a2": "WA", "subdivision_name": "Washington" } ] } ], "region_code": "WNAM" } ] } } }, "type": "object" } ] }, "load-balancing_components-schemas-zone-name": { "type": "string", "example": "example.com", "x-auditable": true }, "load-balancing_consecutive_down": { "description": "To be marked unhealthy the monitored origin must fail this healthcheck N consecutive times.", "type": "integer", "x-auditable": true }, "load-balancing_consecutive_up": { "description": "To be marked healthy the monitored origin must pass this healthcheck N consecutive times.", "type": "integer", "x-auditable": true }, "load-balancing_country_pools": { "description": "A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools.", "type": "object", "example": { "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ], "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ] }, "additionalProperties": { "description": "A `string:[string]` object of key-values. Country code maps to list of pool IDs.", "items": { "type": "string", "x-auditable": true }, "type": "array" } }, "load-balancing_default_pools": { "description": "A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region.", "type": "array", "items": { "description": "A pool ID.", "type": "string" }, "example": [ "17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194" ] }, "load-balancing_description": { "description": "Object description.", "type": "string", "example": "Login page monitor", "default": "", "x-auditable": true }, "load-balancing_disabled_at": { "description": "This field shows up only if the origin is disabled. This field is set with the time the origin was disabled.", "type": "string", "format": "date-time", "readOnly": true, "x-auditable": true }, "load-balancing_enabled": { "description": "Whether to enable (the default) or disable this pool. Disabled pools will not receive traffic and are excluded from health checks. Disabling a pool will cause any load balancers using it to failover to the next pool (if any).", "type": "boolean", "example": false, "default": true, "x-auditable": true }, "load-balancing_expected_body": { "description": "A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors.", "type": "string", "example": "alive", "default": "", "x-auditable": true }, "load-balancing_expected_codes": { "description": "The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors.", "type": "string", "example": "2xx", "default": "", "x-auditable": true }, "load-balancing_fallback_pool": { "description": "The pool ID to use when all other pools are detected as unhealthy.", "type": "string", "x-auditable": true }, "load-balancing_filter_options": { "description": "Filter options for a particular resource type (pool or origin). Use null to reset.", "type": "object", "properties": { "disable": { "description": "If set true, disable notifications for this type of resource (pool or origin).", "type": "boolean", "default": false, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "optional" }, "healthy": { "description": "If present, send notifications only for this health status (e.g. false for only DOWN events). Use null to reset (all events).", "type": "boolean", "nullable": true, "x-auditable": true } }, "nullable": true }, "load-balancing_fixed_response": { "description": "A collection of fields used to directly respond to the client instead of routing to a pool. When supplied on a rule, that rule stops further rule evaluation.", "type": "object", "properties": { "content_type": { "description": "The http 'Content-Type' header to include in the response.", "type": "string", "example": "application/json", "maxLength": 32, "x-auditable": true }, "location": { "description": "The http 'Location' header to include in the response.", "type": "string", "example": "www.example.com", "maxLength": 2048, "x-auditable": true }, "message_body": { "description": "Text to include as the http body.", "type": "string", "example": "Testing Hello", "maxLength": 1024, "x-auditable": true }, "status_code": { "description": "The http status code to respond with.", "type": "integer", "x-auditable": true } } }, "load-balancing_follow_redirects": { "description": "Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "load-balancing_header": { "description": "The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors.", "type": "object", "example": { "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] }, "additionalProperties": { "items": { "type": "string", "x-auditable": true }, "type": "array" } }, "load-balancing_health_details": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-single" }, { "properties": { "result": { "description": "A list of regions from which to run health checks. Null means every Cloudflare data center.", "type": "object", "example": { "pool_id": "17b5962d775c646f3f9725cbc7a53df4", "pop_health": { "Amsterdam, NL": { "healthy": true, "origins": [ { "2001:DB8::5": { "failure_reason": "No failures", "healthy": true, "response_code": 401, "rtt": "12.1ms" } } ] } } }, "properties": { "pool_id": { "description": "Pool ID.", "type": "string", "example": "17b5962d775c646f3f9725cbc7a53df4", "x-auditable": true }, "pop_health": { "description": "List of regions and associated health status.", "type": "object", "properties": { "healthy": { "description": "Whether health check in region is healthy.", "type": "boolean", "example": true, "x-auditable": true }, "origins": { "type": "array", "items": { "$ref": "#/components/schemas/load-balancing_origin-health" } } } } } } }, "type": "object" } ] }, "load-balancing_health_sources": { "description": "A list of health sources, ordered from highest to lowest priority, used to evaluate individual origin health and overall pool health. The load balancer uses the first source that has data and falls back to the next. Currently accepted values are null or the exact array [\"regional\", \"global\"]; any other combination is rejected. Null (the default) behaves like [\"local\", \"global\"]. [\"regional\", \"global\"] makes each region steer on its own health, falling back to the global decision when a region has no fresh data. Setting regional requires at least one region in check_regions.", "type": "array", "items": { "description": "The scope a health decision is aggregated over. local: the result from the single data center running the health check; only available when health checks run from every data center (check_regions is ALL_DATACENTERS). regional: a separate decision per region, each aggregated from the data centers within that region, so regions steer independently; requires at least one region configured in check_regions. global: one worldwide decision aggregated across all configured regions, used as the fallback.", "enum": [ "local", "regional", "global" ], "type": "string", "x-auditable": true }, "example": [ "regional", "global" ], "nullable": true }, "load-balancing_id_response": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/load-balancing_identifier" } } } }, "type": "object" } ] }, "load-balancing_identifier": { "type": "string", "example": "f1aba936b94213e5b8dca0c0dbf1f9cc", "x-auditable": true }, "load-balancing_interval": { "description": "The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations.", "type": "integer", "default": 60, "x-auditable": true }, "load-balancing_latitude": { "description": "The latitude of the data center containing the origins used in this pool in decimal degrees. If this is set, longitude must also be set.", "type": "number", "x-auditable": true }, "load-balancing_load-balancer": { "type": "object", "properties": { "adaptive_routing": { "$ref": "#/components/schemas/load-balancing_adaptive_routing" }, "country_pools": { "$ref": "#/components/schemas/load-balancing_country_pools" }, "created_on": { "$ref": "#/components/schemas/load-balancing_timestamp" }, "default_pools": { "$ref": "#/components/schemas/load-balancing_default_pools" }, "description": { "$ref": "#/components/schemas/load-balancing_components-schemas-description" }, "enabled": { "$ref": "#/components/schemas/load-balancing_components-schemas-enabled" }, "fallback_pool": { "$ref": "#/components/schemas/load-balancing_fallback_pool" }, "id": { "$ref": "#/components/schemas/load-balancing_load-balancer_components-schemas-identifier" }, "location_strategy": { "$ref": "#/components/schemas/load-balancing_location_strategy" }, "modified_on": { "$ref": "#/components/schemas/load-balancing_timestamp" }, "name": { "$ref": "#/components/schemas/load-balancing_components-schemas-name" }, "networks": { "$ref": "#/components/schemas/load-balancing_networks" }, "pool_sets": { "$ref": "#/components/schemas/load-balancing_pool_sets" }, "pop_pools": { "$ref": "#/components/schemas/load-balancing_pop_pools" }, "proxied": { "$ref": "#/components/schemas/load-balancing_proxied" }, "random_steering": { "$ref": "#/components/schemas/load-balancing_random_steering" }, "region_pools": { "$ref": "#/components/schemas/load-balancing_region_pools" }, "rules": { "$ref": "#/components/schemas/load-balancing_rules" }, "session_affinity": { "$ref": "#/components/schemas/load-balancing_session_affinity" }, "session_affinity_attributes": { "$ref": "#/components/schemas/load-balancing_session_affinity_attributes" }, "session_affinity_ttl": { "$ref": "#/components/schemas/load-balancing_session_affinity_ttl" }, "steering_policy": { "$ref": "#/components/schemas/load-balancing_steering_policy" }, "ttl": { "$ref": "#/components/schemas/load-balancing_ttl" }, "zone_name": { "$ref": "#/components/schemas/load-balancing_components-schemas-zone-name" } } }, "load-balancing_load-balancer-editable": { "description": "The editable properties shared by load balancer create, update, and patch requests. Operations layer their own `required` constraints on top via `allOf`.", "type": "object", "properties": { "adaptive_routing": { "$ref": "#/components/schemas/load-balancing_adaptive_routing" }, "country_pools": { "$ref": "#/components/schemas/load-balancing_country_pools" }, "default_pools": { "$ref": "#/components/schemas/load-balancing_default_pools" }, "description": { "$ref": "#/components/schemas/load-balancing_components-schemas-description" }, "enabled": { "$ref": "#/components/schemas/load-balancing_components-schemas-enabled" }, "fallback_pool": { "$ref": "#/components/schemas/load-balancing_fallback_pool" }, "location_strategy": { "$ref": "#/components/schemas/load-balancing_location_strategy" }, "name": { "$ref": "#/components/schemas/load-balancing_components-schemas-name" }, "networks": { "$ref": "#/components/schemas/load-balancing_networks" }, "pop_pools": { "$ref": "#/components/schemas/load-balancing_pop_pools" }, "proxied": { "$ref": "#/components/schemas/load-balancing_proxied" }, "random_steering": { "$ref": "#/components/schemas/load-balancing_random_steering" }, "region_pools": { "$ref": "#/components/schemas/load-balancing_region_pools" }, "rules": { "$ref": "#/components/schemas/load-balancing_rules" }, "session_affinity": { "$ref": "#/components/schemas/load-balancing_session_affinity" }, "session_affinity_attributes": { "$ref": "#/components/schemas/load-balancing_session_affinity_attributes" }, "session_affinity_ttl": { "$ref": "#/components/schemas/load-balancing_session_affinity_ttl" }, "steering_policy": { "$ref": "#/components/schemas/load-balancing_steering_policy" }, "ttl": { "$ref": "#/components/schemas/load-balancing_ttl" } } }, "load-balancing_load-balancer_components-schemas-identifier": { "type": "string", "example": "699d98642c564d2e855e9661899b7252", "x-auditable": true }, "load-balancing_load-balancer_components-schemas-response_collection": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-paginated-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/load-balancing_load-balancer" } } }, "type": "object" } ] }, "load-balancing_load-balancer_components-schemas-single_response": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/load-balancing_load-balancer" } }, "type": "object" } ] }, "load-balancing_load-balancer_components-schemas-usage_response": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-single" }, { "properties": { "result": { "description": "Load balancer usage counts for an account.", "type": "object", "properties": { "load_balancers": { "description": "The number of configured load balancers.", "type": "integer", "format": "int64", "example": 5 }, "max_origins_per_pool": { "description": "The largest number of origins in any single pool.", "type": "integer", "format": "int64", "example": 5 }, "minimum_monitor_interval": { "description": "The smallest monitor interval (in seconds) configured across all monitors.", "type": "integer", "format": "int64", "example": 60 }, "monitors": { "description": "The number of configured monitors.", "type": "integer", "format": "int64", "example": 3 }, "origins": { "description": "The number of configured origins across all pools.", "type": "integer", "format": "int64", "example": 12 }, "pools": { "description": "The number of configured pools.", "type": "integer", "format": "int64", "example": 4 } }, "required": [ "load_balancers", "monitors", "origins", "pools", "max_origins_per_pool", "minimum_monitor_interval" ] } }, "type": "object" } ] }, "load-balancing_load_shedding": { "description": "Configures load shedding policies and percentages for the pool.", "type": "object", "properties": { "default_percent": { "description": "The percent of traffic to shed from the pool, according to the default policy. Applies to new sessions and traffic without session affinity.", "type": "number", "default": 0, "maximum": 100, "minimum": 0, "x-auditable": true }, "default_policy": { "description": "The default policy to use when load shedding. A random policy randomly sheds a given percent of requests. A hash policy computes a hash over the CF-Connecting-IP address and sheds all requests originating from a percent of IPs.", "type": "string", "default": "random", "enum": [ "random", "hash" ], "x-auditable": true }, "session_percent": { "description": "The percent of existing sessions to shed from the pool, according to the session policy.", "type": "number", "default": 0, "maximum": 100, "minimum": 0, "x-auditable": true }, "session_policy": { "description": "Only the hash policy is supported for existing sessions (to avoid exponential decay).", "type": "string", "default": "hash", "enum": [ "hash" ], "x-auditable": true } }, "nullable": true, "x-stainless-terraform-configurability": "computed_optional" }, "load-balancing_location_strategy": { "description": "Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected.", "type": "object", "properties": { "mode": { "description": "Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful.\n- `\"pop\"`: Use the Cloudflare PoP location.\n- `\"resolver_ip\"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location.", "type": "string", "example": "resolver_ip", "default": "pop", "enum": [ "pop", "resolver_ip" ], "x-auditable": true }, "prefer_ecs": { "description": "Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location.\n- `\"always\"`: Always prefer ECS.\n- `\"never\"`: Never prefer ECS.\n- `\"proximity\"`: Prefer ECS only when `steering_policy=\"proximity\"`.\n- `\"geo\"`: Prefer ECS only when `steering_policy=\"geo\"`.", "type": "string", "example": "always", "default": "proximity", "enum": [ "always", "never", "proximity", "geo" ], "x-auditable": true } } }, "load-balancing_longitude": { "description": "The longitude of the data center containing the origins used in this pool in decimal degrees. If this is set, latitude must also be set.", "type": "number", "x-auditable": true }, "load-balancing_match": { "description": "Determines which requests a pool set applies to. Set `topology` to match by location or `default: true` to match all requests; the two are mutually exclusive. A pool set with no `match` matches all requests.", "type": "object", "properties": { "default": { "description": "When true, matches every request. Cannot be combined with `topology`.", "type": "boolean", "default": false, "x-auditable": true }, "topology": { "$ref": "#/components/schemas/load-balancing_topology_match" } }, "x-stainless-terraform-configurability": "computed_optional" }, "load-balancing_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "load-balancing_method": { "description": "The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks.", "type": "string", "example": "GET", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "load-balancing_minimum_origins": { "description": "The minimum number of origins that must be healthy for this pool to serve traffic. If the number of healthy origins falls below this number, the pool will be marked unhealthy and will failover to the next available pool.", "type": "integer", "default": 1, "x-auditable": true }, "load-balancing_monitor": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_monitor-editable" }, { "properties": { "created_on": { "$ref": "#/components/schemas/load-balancing_timestamp" }, "id": { "$ref": "#/components/schemas/load-balancing_identifier" }, "modified_on": { "$ref": "#/components/schemas/load-balancing_timestamp" } }, "type": "object" } ] }, "load-balancing_monitor-editable": { "type": "object", "properties": { "allow_insecure": { "$ref": "#/components/schemas/load-balancing_allow_insecure" }, "consecutive_down": { "$ref": "#/components/schemas/load-balancing_consecutive_down" }, "consecutive_up": { "$ref": "#/components/schemas/load-balancing_consecutive_up" }, "description": { "$ref": "#/components/schemas/load-balancing_description" }, "expected_body": { "$ref": "#/components/schemas/load-balancing_expected_body" }, "expected_codes": { "$ref": "#/components/schemas/load-balancing_expected_codes" }, "follow_redirects": { "$ref": "#/components/schemas/load-balancing_follow_redirects" }, "header": { "$ref": "#/components/schemas/load-balancing_header" }, "interval": { "$ref": "#/components/schemas/load-balancing_interval" }, "method": { "$ref": "#/components/schemas/load-balancing_method" }, "path": { "$ref": "#/components/schemas/load-balancing_path" }, "port": { "$ref": "#/components/schemas/load-balancing_port" }, "probe_zone": { "$ref": "#/components/schemas/load-balancing_probe_zone" }, "retries": { "$ref": "#/components/schemas/load-balancing_retries" }, "timeout": { "$ref": "#/components/schemas/load-balancing_timeout" }, "type": { "$ref": "#/components/schemas/load-balancing_type" } } }, "load-balancing_monitor-group": { "type": "object", "properties": { "created_on": { "description": "The timestamp of when the monitor group was created", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true }, "description": { "description": "A short description of the monitor group", "type": "string", "example": "Primary datacenter monitors" }, "id": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_monitor_group_id" } ], "readOnly": true }, "members": { "description": "List of monitors in this group", "type": "array", "items": { "$ref": "#/components/schemas/load-balancing_monitor-group-member" }, "x-stainless-collection-type": "set" }, "modified_on": { "description": "The timestamp of when the monitor group was last updated", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true } }, "required": [ "id", "description", "members" ] }, "load-balancing_monitor-group-member": { "type": "object", "properties": { "created_at": { "description": "The timestamp of when the monitor was added to the group", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true }, "enabled": { "description": "Whether this monitor is enabled in the group", "type": "boolean", "example": true }, "monitor_id": { "$ref": "#/components/schemas/load-balancing_monitor_id" }, "monitoring_only": { "description": "Whether this monitor is used for monitoring only (does not affect pool health)", "type": "boolean", "example": false }, "must_be_healthy": { "description": "Whether this monitor must be healthy for the pool to be considered healthy", "type": "boolean", "example": true }, "updated_at": { "description": "The timestamp of when the monitor group member was last updated", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true } }, "required": [ "monitor_id", "enabled", "monitoring_only", "must_be_healthy" ] }, "load-balancing_monitor-group-references-response": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-common" }, { "properties": { "result": { "description": "List of resources that reference a given monitor group.", "type": "array", "items": { "properties": { "reference_type": { "type": "string", "enum": [ "*", "referral", "referrer" ], "x-auditable": true }, "resource_id": { "type": "string", "x-auditable": true }, "resource_name": { "type": "string", "x-auditable": true }, "resource_type": { "type": "string", "x-auditable": true } }, "type": "object" }, "example": [ { "reference_type": "referrer", "resource_id": "17b5962d775c646f3f9725cbc7a53df4", "resource_name": "primary-dc-1", "resource_type": "pool" } ] } }, "type": "object" } ] }, "load-balancing_monitor-group-response-collection": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/load-balancing_monitor-group" } }, "result_info": { "$ref": "#/components/schemas/load-balancing_result_info" } } } ] }, "load-balancing_monitor-group-single-response": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/load-balancing_monitor-group" } } } ] }, "load-balancing_monitor-references-response": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-common" }, { "properties": { "result": { "description": "List of resources that reference a given monitor.", "type": "array", "items": { "properties": { "reference_type": { "type": "string", "enum": [ "*", "referral", "referrer" ], "x-auditable": true }, "resource_id": { "type": "string", "x-auditable": true }, "resource_name": { "type": "string", "x-auditable": true }, "resource_type": { "type": "string", "x-auditable": true } }, "type": "object" }, "example": [ { "reference_type": "referrer", "resource_id": "17b5962d775c646f3f9725cbc7a53df4", "resource_name": "primary-dc-1", "resource_type": "pool" } ] } }, "type": "object" } ] }, "load-balancing_monitor-response-collection": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-paginated-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/load-balancing_monitor" } } }, "type": "object" } ] }, "load-balancing_monitor-response-single": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/load-balancing_monitor" } }, "type": "object" } ] }, "load-balancing_monitor_group_id": { "description": "The ID of the Monitor Group to use for checking the health of origins within this pool.", "type": "string", "x-auditable": true }, "load-balancing_monitor_id": { "description": "The ID of the Monitor to use for checking the health of origins within this pool.", "type": "string", "x-auditable": true }, "load-balancing_name": { "description": "A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed.", "type": "string", "example": "primary-dc-1", "x-auditable": true }, "load-balancing_networks": { "description": "List of networks where Load Balancer or Pool is enabled.", "type": "array", "items": { "example": [ "cloudflare", "jdcloud" ], "type": "string", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "load-balancing_notification_email": { "description": "This field is now deprecated. It has been moved to Cloudflare's Centralized Notification service https://developers.cloudflare.com/fundamentals/notifications/. The email address to send health status notifications to. This can be an individual mailbox or a mailing list. Multiple emails can be supplied as a comma delimited list.", "type": "string", "example": "someone@example.com,sometwo@example.com", "default": "", "x-auditable": true }, "load-balancing_notification_filter": { "description": "Filter pool and origin health notifications by resource type or health status. Use null to reset.", "type": "object", "properties": { "origin": { "$ref": "#/components/schemas/load-balancing_filter_options" }, "pool": { "$ref": "#/components/schemas/load-balancing_filter_options" } }, "example": { "origin": { "disable": true }, "pool": { "healthy": false } }, "nullable": true, "x-stainless-terraform-configurability": "computed_optional" }, "load-balancing_origin": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/load-balancing_address" }, "disabled_at": { "$ref": "#/components/schemas/load-balancing_disabled_at" }, "enabled": { "$ref": "#/components/schemas/load-balancing_schemas-enabled" }, "flatten_cname": { "$ref": "#/components/schemas/load-balancing_origin_flatten_cname" }, "header": { "$ref": "#/components/schemas/load-balancing_schemas-header" }, "name": { "$ref": "#/components/schemas/load-balancing_schemas-name" }, "port": { "$ref": "#/components/schemas/load-balancing_origin_port" }, "virtual_network_id": { "$ref": "#/components/schemas/load-balancing_virtual_network_id" }, "weight": { "$ref": "#/components/schemas/load-balancing_weight" } } }, "load-balancing_origin-analytics": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/load-balancing_address" }, "changed": { "$ref": "#/components/schemas/load-balancing_origin-changed" }, "enabled": { "$ref": "#/components/schemas/load-balancing_schemas-enabled" }, "failure_reason": { "$ref": "#/components/schemas/load-balancing_origin-failure-reason" }, "healthy": { "$ref": "#/components/schemas/load-balancing_origin-healthy" }, "ip": { "$ref": "#/components/schemas/load-balancing_origin-ip" }, "name": { "$ref": "#/components/schemas/load-balancing_schemas-name" } } }, "load-balancing_origin-changed": { "description": "Whether the origin has changed health status.", "type": "boolean", "example": true, "x-auditable": true }, "load-balancing_origin-failure-reason": { "description": "Failure reason for un-healthy origin health check.", "type": "string", "example": "No failures", "x-auditable": true }, "load-balancing_origin-health": { "type": "object", "properties": { "ip": { "type": "object", "properties": { "failure_reason": { "description": "Failure reason.", "type": "string", "example": "No failure reasons", "x-auditable": true }, "healthy": { "description": "Origin health status.", "type": "boolean", "example": true, "x-auditable": true }, "response_code": { "description": "Response code from origin health check.", "type": "number", "example": 200, "x-auditable": true }, "rtt": { "description": "Origin RTT (Round Trip Time) response.", "type": "string", "example": "201.5ms", "x-auditable": true } } } } }, "load-balancing_origin-healthy": { "description": "Whether the origin is reported as healthy.", "type": "boolean", "example": true, "x-auditable": true }, "load-balancing_origin-ip": { "description": "The IP address (IPv4 or IPv6) of the origin.", "type": "string", "example": "198.51.100.4", "x-auditable": true }, "load-balancing_origin_flatten_cname": { "description": "Whether to flatten CNAME records for this origin, resolving them to A/AAAA records before returning to the client. When true (the default), the director resolves CNAME addresses to their underlying A/AAAA records. When false, the origin address is returned as a raw CNAME record without resolution. This setting mirrors the DNS API record flatten_cname setting.", "type": "boolean", "default": true }, "load-balancing_origin_health_data": { "description": "The origin ipv4/ipv6 address or domain name mapped to its health data.", "type": "object", "properties": { "failure_reason": { "type": "string", "x-auditable": true }, "healthy": { "type": "boolean", "x-auditable": true }, "response_code": { "type": "number", "x-auditable": true }, "rtt": { "type": "string", "x-auditable": true } }, "example": { "failure_reason": "No failures", "healthy": true, "response_code": 200, "rtt": "66ms" } }, "load-balancing_origin_healthy": { "description": "If true, filter events where the origin status is healthy. If false, filter events where the origin status is unhealthy.", "type": "boolean", "example": true, "default": true, "x-auditable": true }, "load-balancing_origin_port": { "description": "The port for upstream connections. A value of 0 means the default port for the protocol will be used.", "type": "integer", "default": 0 }, "load-balancing_origin_steering": { "description": "Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity.", "type": "object", "properties": { "policy": { "description": "The type of origin steering policy to use.\n- `\"random\"`: Select an origin randomly.\n- `\"hash\"`: Select an origin by computing a hash over the CF-Connecting-IP address.\n- `\"least_outstanding_requests\"`: Select an origin by taking into consideration origin weights, as well as each origin's number of outstanding requests. Origins with more pending requests are weighted proportionately less relative to others.\n- `\"least_connections\"`: Select an origin by taking into consideration origin weights, as well as each origin's number of open connections. Origins with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections.", "type": "string", "default": "random", "enum": [ "random", "hash", "least_outstanding_requests", "least_connections" ], "x-auditable": true } }, "nullable": true, "x-stainless-terraform-configurability": "computed_optional" }, "load-balancing_origins": { "description": "The list of origins within this pool. Traffic directed at this pool is balanced across all currently healthy origins, provided the pool itself is healthy.", "type": "array", "items": { "$ref": "#/components/schemas/load-balancing_origin" }, "x-stainless-collection-type": "set" }, "load-balancing_patch_pools_notification_email": { "description": "The email address to send health status notifications to. This field is now deprecated in favor of Cloudflare Notifications for Load Balancing, so only resetting this field with an empty string `\"\"` is accepted.", "type": "string", "example": "", "enum": [ "" ] }, "load-balancing_path": { "description": "The endpoint path you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors.", "type": "string", "example": "/health", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "load-balancing_pool": { "type": "object", "properties": { "check_regions": { "$ref": "#/components/schemas/load-balancing_check_regions" }, "created_on": { "$ref": "#/components/schemas/load-balancing_timestamp" }, "description": { "$ref": "#/components/schemas/load-balancing_schemas-description" }, "disabled_at": { "$ref": "#/components/schemas/load-balancing_schemas-disabled_at" }, "enabled": { "$ref": "#/components/schemas/load-balancing_enabled" }, "health_sources": { "$ref": "#/components/schemas/load-balancing_health_sources" }, "id": { "$ref": "#/components/schemas/load-balancing_schemas-identifier" }, "latitude": { "$ref": "#/components/schemas/load-balancing_latitude" }, "load_shedding": { "$ref": "#/components/schemas/load-balancing_load_shedding" }, "longitude": { "$ref": "#/components/schemas/load-balancing_longitude" }, "minimum_origins": { "$ref": "#/components/schemas/load-balancing_minimum_origins" }, "modified_on": { "$ref": "#/components/schemas/load-balancing_timestamp" }, "monitor": { "$ref": "#/components/schemas/load-balancing_monitor_id" }, "monitor_group": { "$ref": "#/components/schemas/load-balancing_monitor_group_id" }, "name": { "$ref": "#/components/schemas/load-balancing_name" }, "networks": { "$ref": "#/components/schemas/load-balancing_networks" }, "notification_email": { "$ref": "#/components/schemas/load-balancing_notification_email" }, "notification_filter": { "$ref": "#/components/schemas/load-balancing_notification_filter" }, "origin_steering": { "$ref": "#/components/schemas/load-balancing_origin_steering" }, "origins": { "$ref": "#/components/schemas/load-balancing_origins" } } }, "load-balancing_pool_default_weight": { "description": "The default weight for pools not listed in `pool_weights`. The declarative alternative to `random_steering.default_weight`; mutually exclusive with `random_steering`.", "type": "number", "example": 0.2, "maximum": 1, "minimum": 0, "multipleOf": 0.1, "x-stainless-terraform-configurability": "computed_optional" }, "load-balancing_pool_name": { "description": "The name for the pool to filter.", "type": "string", "example": "primary-dc", "x-auditable": true }, "load-balancing_pool_set": { "description": "One entry in a load balancer's `pool_sets`. Pool sets are evaluated in array order; the first whose `match` succeeds applies its `overrides` (or `fixed_response`), and evaluation stops there.", "type": "object", "properties": { "disabled": { "description": "Disable this specific pool set. It will no longer be evaluated.", "type": "boolean", "default": false, "x-auditable": true }, "fixed_response": { "$ref": "#/components/schemas/load-balancing_fixed_response" }, "match": { "$ref": "#/components/schemas/load-balancing_match" }, "name": { "description": "A human-readable name for this pool set.", "type": "string", "example": "wnam-primary", "maxLength": 200, "x-auditable": true }, "overrides": { "$ref": "#/components/schemas/load-balancing_pool_set_overrides" } }, "example": { "match": { "topology": { "regions": [ "WNAM" ] } }, "name": "wnam-primary", "overrides": { "fallback_pool": "9290f38c5d07c2e2f4df57b1f61d4196", "pools": [ "17b5962d775c646f3f9725cbc7a53df4" ], "steering_policy": "random" } }, "x-stainless-terraform-configurability": "computed_optional" }, "load-balancing_pool_set_overrides": { "description": "The behavior a pool set applies when its `match` succeeds. A strict subset of a rule's `overrides`: a pool set replaces the topology wholesale with a flat pool list (`pools`), so only the declarative pool-routing fields plus `fallback_pool` and `steering_policy` are settable. All fields are optional.", "type": "object", "properties": { "fallback_pool": { "$ref": "#/components/schemas/load-balancing_fallback_pool" }, "pool_default_weight": { "$ref": "#/components/schemas/load-balancing_pool_default_weight" }, "pool_weights": { "$ref": "#/components/schemas/load-balancing_pool_weights" }, "pools": { "$ref": "#/components/schemas/load-balancing_pools" }, "steering_policy": { "$ref": "#/components/schemas/load-balancing_steering_policy" } }, "x-stainless-terraform-configurability": "computed_optional" }, "load-balancing_pool_sets": { "description": "An optional list of pool sets, evaluated in array order with first match wins. Pool sets are independent from the standard steering fields (`region_pools` / `country_pools` / `pop_pools` / `default_pools` / `steering_policy` / `random_steering` / `fallback_pool` / `rules`). On a PATCH, an empty array (`pool_sets: []`) clears all pool sets, while omitting the field leaves existing pool sets unchanged.", "type": "array", "items": { "$ref": "#/components/schemas/load-balancing_pool_set" }, "x-stainless-terraform-configurability": "computed_optional" }, "load-balancing_pool_weights": { "description": "A mapping of pool IDs to custom weights, relative to the other pools. The declarative alternative to `random_steering.pool_weights`; mutually exclusive with `random_steering`.", "type": "object", "example": { "9290f38c5d07c2e2f4df57b1f61d4196": 0.5, "de90f38ced07c2e2f4df50b1f61d4194": 0.3 }, "additionalProperties": { "type": "number", "x-auditable": true }, "x-stainless-terraform-configurability": "computed_optional" }, "load-balancing_pools": { "description": "A flat, ordered list of pool IDs to route the matched audience to. Replaces the resolved topology with exactly these pools. Mutually exclusive with `fixed_response`.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "17b5962d775c646f3f9725cbc7a53df4" ], "x-stainless-terraform-configurability": "computed_optional" }, "load-balancing_pools-references-response": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-common" }, { "properties": { "result": { "description": "List of resources that reference a given pool.", "type": "array", "items": { "properties": { "reference_type": { "type": "string", "enum": [ "*", "referral", "referrer" ], "x-auditable": true }, "resource_id": { "type": "string", "x-auditable": true }, "resource_name": { "type": "string", "x-auditable": true }, "resource_type": { "type": "string", "x-auditable": true } }, "type": "object" }, "example": [ { "reference_type": "referrer", "resource_id": "699d98642c564d2e855e9661899b7252", "resource_name": "www.example.com", "resource_type": "load_balancer" }, { "reference_type": "referral", "resource_id": "f1aba936b94213e5b8dca0c0dbf1f9cc", "resource_name": "Login page monitor", "resource_type": "monitor" } ] } }, "type": "object" } ] }, "load-balancing_pop_pools": { "description": "Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools.", "type": "object", "example": { "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "additionalProperties": { "description": "A `string:[string]` object of key-values. PoP code maps to list of pool IDs.", "items": { "type": "string", "x-auditable": true }, "type": "array" } }, "load-balancing_port": { "description": "The port number to connect to for the health check. Required for TCP, UDP, and SMTP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443).", "type": "integer", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "optional" }, "load-balancing_preview_id": { "example": "f1aba936b94213e5b8dca0c0dbf1f9cc" }, "load-balancing_preview_response": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "pools": { "description": "Monitored pool IDs mapped to their respective names.", "type": "object", "example": { "abwlnp5jbqn45ecgxd03erbgtxtqai0d": "WNAM Datacenter", "ve8h9lrcip5n5bbga9yqmdws28ay5d0l": "EEU Datacenter" }, "additionalProperties": { "description": "The pool name associated with the pool ID.", "type": "string", "x-auditable": true } }, "preview_id": { "$ref": "#/components/schemas/load-balancing_identifier" } } } }, "type": "object" } ] }, "load-balancing_preview_result": { "description": "Resulting health data from a preview operation.", "type": "object", "example": { "abwlnp5jbqn45ecgxd03erbgtxtqai0d": { "healthy": true, "origins": [ { "originone.example.com.": { "failure_reason": "No failures", "healthy": true, "response_code": 200, "rtt": "66ms" } } ] } }, "additionalProperties": { "properties": { "healthy": { "type": "boolean", "x-auditable": true }, "origins": { "type": "array", "items": { "additionalProperties": { "$ref": "#/components/schemas/load-balancing_origin_health_data" }, "maxProperties": 1, "minProperties": 1, "type": "object" } } }, "type": "object" } }, "load-balancing_preview_result_response": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/load-balancing_preview_result" } }, "type": "object" } ] }, "load-balancing_probe_zone": { "description": "Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors.", "type": "string", "example": "example.com", "default": "", "x-auditable": true }, "load-balancing_proxied": { "description": "Whether the hostname should be gray clouded (false) or orange clouded (true).", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "load-balancing_random_steering": { "description": "Configures pool weights.\n- `steering_policy=\"random\"`: A random pool is selected with probability proportional to pool weights.\n- `steering_policy=\"least_outstanding_requests\"`: Use pool weights to scale each pool's outstanding requests.\n- `steering_policy=\"least_connections\"`: Use pool weights to scale each pool's open connections.", "type": "object", "properties": { "default_weight": { "description": "The default weight for pools in the load balancer that are not specified in the pool_weights map.", "type": "number", "example": 0.2, "default": 1, "maximum": 1, "minimum": 0, "multipleOf": 0.1, "x-auditable": true }, "pool_weights": { "description": "A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer.", "type": "object", "example": { "9290f38c5d07c2e2f4df57b1f61d4196": 0.5, "de90f38ced07c2e2f4df50b1f61d4194": 0.3 }, "additionalProperties": { "type": "number", "x-auditable": true } } } }, "load-balancing_region_code": { "description": "A list of Cloudflare regions. WNAM: Western North America, ENAM: Eastern North America, WEU: Western Europe, EEU: Eastern Europe, NSAM: Northern South America, SSAM: Southern South America, OC: Oceania, ME: Middle East, NAF: North Africa, SAF: South Africa, SAS: Southern Asia, SEAS: South East Asia, NEAS: North East Asia).", "type": "string", "example": "WNAM", "enum": [ "WNAM", "ENAM", "WEU", "EEU", "NSAM", "SSAM", "OC", "ME", "NAF", "SAF", "SAS", "SEAS", "NEAS" ] }, "load-balancing_region_components-schemas-response_collection": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-single" }, { "properties": { "result": { "type": "object" } }, "type": "object" } ] }, "load-balancing_region_pools": { "description": "A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools.", "type": "object", "example": { "ENAM": [ "00920f38ce07c2e2f4df50b1f61d4194" ], "WNAM": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ] }, "additionalProperties": { "description": "A `string:[string]` object of key-values. Region code maps to list of pool IDs.", "items": { "type": "string", "x-auditable": true }, "type": "array" } }, "load-balancing_resource_reference": { "description": "A reference to a load balancer resource.", "type": "object", "properties": { "reference_type": { "description": "When listed as a reference, the type (direction) of the reference.", "type": "string", "enum": [ "referral", "referrer" ], "x-auditable": true }, "references": { "description": "A list of references to (referrer) or from (referral) this resource.", "type": "array", "items": { "description": "A reference to a load balancer resource.", "type": "object" }, "example": [ { "reference_type": "referrer", "resource_id": "699d98642c564d2e855e9661899b7252", "resource_name": "www.example.com", "resource_type": "load_balancer" }, { "reference_type": "referral", "resource_id": "f1aba936b94213e5b8dca0c0dbf1f9cc", "resource_name": "Login page monitor", "resource_type": "monitor" } ] }, "resource_id": { "type": "string", "example": "17b5962d775c646f3f9725cbc7a53df4" }, "resource_name": { "description": "The human-identifiable name of the resource.", "type": "string", "example": "primary-dc-1", "x-auditable": true }, "resource_type": { "description": "The type of the resource.", "type": "string", "example": "pool", "enum": [ "load_balancer", "monitor", "pool" ], "x-auditable": true } } }, "load-balancing_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results on the current page.", "type": "number", "example": 20 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "Total number of pages available.", "type": "number", "example": 100 } } }, "load-balancing_retries": { "description": "The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately.", "type": "integer", "default": 2, "x-auditable": true }, "load-balancing_rule_overrides": { "description": "A collection of overrides to apply when this rule's condition (or a pool set's `match`) is true. All fields are optional.", "type": "object", "properties": { "adaptive_routing": { "$ref": "#/components/schemas/load-balancing_adaptive_routing" }, "country_pools": { "$ref": "#/components/schemas/load-balancing_country_pools" }, "default_pools": { "$ref": "#/components/schemas/load-balancing_default_pools" }, "fallback_pool": { "$ref": "#/components/schemas/load-balancing_fallback_pool" }, "location_strategy": { "$ref": "#/components/schemas/load-balancing_location_strategy" }, "pool_default_weight": { "$ref": "#/components/schemas/load-balancing_pool_default_weight" }, "pool_weights": { "$ref": "#/components/schemas/load-balancing_pool_weights" }, "pools": { "$ref": "#/components/schemas/load-balancing_pools" }, "pop_pools": { "$ref": "#/components/schemas/load-balancing_pop_pools" }, "random_steering": { "$ref": "#/components/schemas/load-balancing_random_steering" }, "region_pools": { "$ref": "#/components/schemas/load-balancing_region_pools" }, "session_affinity": { "$ref": "#/components/schemas/load-balancing_session_affinity" }, "session_affinity_attributes": { "$ref": "#/components/schemas/load-balancing_session_affinity_attributes" }, "session_affinity_ttl": { "$ref": "#/components/schemas/load-balancing_session_affinity_ttl" }, "steering_policy": { "$ref": "#/components/schemas/load-balancing_steering_policy" }, "ttl": { "$ref": "#/components/schemas/load-balancing_ttl" } }, "x-stainless-terraform-configurability": "computed_optional" }, "load-balancing_rules": { "description": "BETA Field Not General Access: A list of rules for this load balancer to execute.", "type": "array", "items": { "additionalProperties": false, "description": "A rule object containing conditions and overrides for this load balancer to evaluate.", "properties": { "condition": { "description": "The condition expressions to evaluate. If the condition evaluates to true, the overrides or fixed_response in this rule will be applied. An empty condition is always true. For more details on condition expressions, please see https://developers.cloudflare.com/load-balancing/understand-basics/load-balancing-rules/expressions.", "type": "string", "example": "http.request.uri.path contains \"/testing\"", "x-auditable": true }, "disabled": { "description": "Disable this specific rule. It will no longer be evaluated by this load balancer.", "type": "boolean", "default": false, "x-auditable": true }, "fixed_response": { "$ref": "#/components/schemas/load-balancing_fixed_response" }, "name": { "description": "Name of this rule. Only used for human readability.", "type": "string", "example": "route the path /testing to testing datacenter.", "maxLength": 200, "x-auditable": true }, "overrides": { "$ref": "#/components/schemas/load-balancing_rule_overrides" }, "priority": { "description": "The order in which rules should be executed in relation to each other. Lower values are executed first. Values do not need to be sequential. If no value is provided for any rule the array order of the rules field will be used to assign a priority.", "type": "integer", "default": 0, "minimum": 0, "x-auditable": true }, "terminates": { "description": "If this rule's condition is true, this causes rule evaluation to stop after processing this rule.", "type": "boolean", "x-auditable": true } }, "type": "object" } }, "load-balancing_schemas-description": { "description": "A human-readable description of the pool.", "type": "string", "example": "Primary data center - Provider XYZ", "default": "", "x-auditable": true }, "load-balancing_schemas-disabled_at": { "description": "This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at.", "type": "string", "format": "date-time", "readOnly": true, "x-auditable": true }, "load-balancing_schemas-enabled": { "description": "Whether to enable (the default) this origin within the pool. Disabled origins will not receive traffic and are excluded from health checks. The origin will only be disabled for the current pool.", "type": "boolean", "example": true, "default": true, "x-auditable": true }, "load-balancing_schemas-header": { "description": "The request header is used to pass additional information with an HTTP request. Currently supported header is 'Host'.", "type": "object", "properties": { "Host": { "$ref": "#/components/schemas/load-balancing_Host" } } }, "load-balancing_schemas-id_response": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/load-balancing_schemas-identifier" } } } }, "type": "object" } ] }, "load-balancing_schemas-identifier": { "type": "string", "example": "17b5962d775c646f3f9725cbc7a53df4", "x-auditable": true }, "load-balancing_schemas-name": { "description": "A human-identifiable name for the origin.", "type": "string", "example": "app-server-1", "x-auditable": true }, "load-balancing_schemas-preview_id": { "type": "string", "example": "p1aba936b94213e5b8dca0c0dbf1f9cc" }, "load-balancing_schemas-response_collection": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-paginated-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/load-balancing_pool" } } }, "type": "object" } ] }, "load-balancing_schemas-single_response": { "allOf": [ { "$ref": "#/components/schemas/load-balancing_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/load-balancing_pool" } }, "type": "object" } ] }, "load-balancing_search": { "type": "object", "properties": { "resources": { "description": "A list of resources matching the search query.", "type": "array", "items": { "$ref": "#/components/schemas/load-balancing_resource_reference" } } } }, "load-balancing_search_result": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/load-balancing_search" } } }, "load-balancing_session_affinity": { "description": "Specifies the type of session affinity the load balancer should use unless specified as `\"none\"`. The supported types are: - `\"cookie\"`: On the first request to a proxied load balancer, a cookie is generated, encoding information of which origin the request will be forwarded to. Subsequent requests, by the same client to the same load balancer, will be sent to the origin server the cookie encodes, for the duration of the cookie and as long as the origin server remains healthy. If the cookie has expired or the origin server is unhealthy, then a new origin server is calculated and used. - `\"ip_cookie\"`: Behaves the same as `\"cookie\"` except the initial origin selection is stable and based on the client's ip address. - `\"header\"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration.", "type": "string", "example": "cookie", "default": "none", "enum": [ "none", "cookie", "ip_cookie", "header" ], "x-auditable": true }, "load-balancing_session_affinity_attributes": { "description": "Configures attributes for session affinity.", "type": "object", "properties": { "drain_duration": { "description": "Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer.", "type": "number", "example": 100, "x-auditable": true }, "headers": { "description": "Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `\"cookie:,\"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `\"cookie\"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans.", "type": "array", "items": { "description": "An HTTP header name.", "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "type": "string", "x-auditable": true }, "default": [], "uniqueItems": true }, "require_all_headers": { "description": "When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are: - `\"true\"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `\"false\"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created.", "type": "boolean", "default": false, "x-auditable": true }, "samesite": { "description": "Configures the SameSite attribute on session affinity cookie. Value \"Auto\" will be translated to \"Lax\" or \"None\" depending if Always Use HTTPS is enabled. Note: when using value \"None\", the secure attribute can not be set to \"Never\".", "type": "string", "example": "Auto", "default": "Auto", "enum": [ "Auto", "Lax", "None", "Strict" ], "x-auditable": true }, "secure": { "description": "Configures the Secure attribute on session affinity cookie. Value \"Always\" indicates the Secure attribute will be set in the Set-Cookie header, \"Never\" indicates the Secure attribute will not be set, and \"Auto\" will set the Secure attribute depending if Always Use HTTPS is enabled.", "type": "string", "example": "Auto", "default": "Auto", "enum": [ "Auto", "Always", "Never" ], "x-auditable": true }, "zero_downtime_failover": { "description": "Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are: - `\"none\"`: No failover takes place for sessions pinned to the origin (default). - `\"temporary\"`: Traffic will be sent to another other healthy origin until the originally pinned origin is available; note that this can potentially result in heavy origin flapping. - `\"sticky\"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header.", "type": "string", "example": "sticky", "default": "none", "enum": [ "none", "temporary", "sticky" ], "x-auditable": true } } }, "load-balancing_session_affinity_ttl": { "description": "Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `\"cookie\"` / `\"ip_cookie\"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `\"header\"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified.", "type": "number", "example": 1800, "x-auditable": true }, "load-balancing_steering_policy": { "description": "Steering Policy for this load balancer.\n- `\"off\"`: Use `default_pools`.\n- `\"geo\"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`.\n- `\"random\"`: Select a pool randomly.\n- `\"dynamic_latency\"`: Use round trip time to select the closest pool in default_pools (requires pool health checks).\n- `\"proximity\"`: Use the pools' latitude and longitude to select the closest pool using the Cloudflare PoP location for proxied requests or the location determined by `location_strategy` for non-proxied requests.\n- `\"least_outstanding_requests\"`: Select a pool by taking into consideration `random_steering` weights, as well as each pool's number of outstanding requests. Pools with more pending requests are weighted proportionately less relative to others.\n- `\"least_connections\"`: Select a pool by taking into consideration `random_steering` weights, as well as each pool's number of open connections. Pools with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections.\n- `\"\"`: Will map to `\"geo\"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `\"off\"`.", "type": "string", "example": "dynamic_latency", "default": "", "enum": [ "off", "geo", "random", "dynamic_latency", "proximity", "least_outstanding_requests", "least_connections", "" ], "x-auditable": true }, "load-balancing_subdivision_code_a2": { "description": "Two-letter subdivision code followed in ISO 3166-2.", "type": "string", "example": "CA", "x-auditable": true }, "load-balancing_timeout": { "description": "The timeout (in seconds) before marking the health check as failed.", "type": "integer", "default": 5, "x-auditable": true }, "load-balancing_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true, "x-auditable": true }, "load-balancing_topology_match": { "description": "Matches requests by location. Set any combination of `pops`, `countries`, and `regions` (at least one is required); a request matches when its value appears in any populated list (e.g. `regions: [\"WNAM\"]` with `countries: [\"US\"]` matches a request in either WNAM or the US).", "type": "object", "properties": { "countries": { "description": "A list of ISO 3166-1 alpha-2 country codes. Matches when the request's country is in this list.", "type": "array", "items": { "type": "string", "x-auditable": true }, "maxItems": 1000 }, "pops": { "description": "A list of Cloudflare PoP codes. Matches when the request's PoP is in this list.", "type": "array", "items": { "type": "string", "x-auditable": true }, "maxItems": 1000 }, "regions": { "description": "A list of Cloudflare region codes (e.g. `WNAM`, `ENAM`, `WEU`). Matches when the request's region is in this list.", "type": "array", "items": { "type": "string", "x-auditable": true }, "maxItems": 1000 } }, "x-stainless-terraform-configurability": "computed_optional" }, "load-balancing_ttl": { "description": "Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers.", "type": "number", "example": 30, "x-auditable": true }, "load-balancing_type": { "description": "The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'.", "type": "string", "example": "https", "default": "http", "enum": [ "http", "https", "tcp", "udp_icmp", "icmp_ping", "smtp" ], "x-auditable": true }, "load-balancing_until": { "description": "End date and time of requesting data period in the ISO8601 format.", "type": "string", "format": "date-time", "example": "2016-11-11T13:00:00Z", "x-auditable": true }, "load-balancing_virtual_network_id": { "description": "The virtual network subnet ID the origin belongs in. Virtual network must also belong to the account.", "type": "string", "example": "a5624d4e-044a-4ff0-b3e1-e2465353d4b4" }, "load-balancing_weight": { "description": "The weight of this origin relative to other origins in the pool. Based on the configured weight the total traffic is distributed among origins within the pool.\n- `origin_steering.policy=\"least_outstanding_requests\"`: Use weight to scale the origin's outstanding requests.\n- `origin_steering.policy=\"least_connections\"`: Use weight to scale the origin's open connections.", "type": "number", "example": 0.6, "default": 1, "maximum": 1, "minimum": 0, "multipleOf": 0.01, "x-auditable": true }, "logcontrol_account_identifier": { "$ref": "#/components/schemas/logcontrol_identifier" }, "logcontrol_allow_out_of_region_access": { "description": "Allow out of region access", "type": "boolean", "example": false, "x-auditable": true }, "logcontrol_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/logcontrol_messages" }, "messages": { "$ref": "#/components/schemas/logcontrol_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "logcontrol_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/logcontrol_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/logcontrol_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "logcontrol_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/logcontrol_api-response-common" } ] }, "logcontrol_cmb_config": { "type": "object", "properties": { "allow_out_of_region_access": { "$ref": "#/components/schemas/logcontrol_allow_out_of_region_access" }, "regions": { "$ref": "#/components/schemas/logcontrol_regions" } }, "nullable": true }, "logcontrol_cmb_config_response_single": { "allOf": [ { "$ref": "#/components/schemas/logcontrol_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/logcontrol_cmb_config" } } } ] }, "logcontrol_flag": { "description": "The log retention flag for Logpull API.", "type": "boolean", "example": true, "x-auditable": true }, "logcontrol_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "logcontrol_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "logcontrol_regions": { "description": "Name of the region.", "type": "string", "example": "eu", "maxLength": 256, "pattern": "^[a-z]*$", "x-auditable": true }, "logcontrol_retention_flag": { "type": "object", "properties": { "flag": { "$ref": "#/components/schemas/logcontrol_flag" } }, "nullable": true }, "logcontrol_retention_flag_response_single": { "allOf": [ { "$ref": "#/components/schemas/logcontrol_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/logcontrol_retention_flag" } } } ] }, "logcontrol_zone_identifier": { "$ref": "#/components/schemas/logcontrol_identifier" }, "logpull_AccessKeyId": { "type": "string", "example": "29a92f1a6e6887d79f3401a41" }, "logpull_AccountId": { "type": "string", "example": "991fff3d2f1084b343f5a84db801fea8", "pattern": "^[0-9a-f]{32}$" }, "logpull_Bucket": { "type": "string", "example": "cloudflare-logs" }, "logpull_Limit": { "type": "integer", "example": 1000, "maximum": 1000, "minimum": 1 }, "logpull_Prefix": { "type": "string", "example": "http_requests/example.com/{DATE}" }, "logpull_SecretAccessKey": { "type": "string", "example": "869b6e19534a6715ab69a07d76492d673f8134d" }, "logpull_TimestampRFC3339": { "type": "string", "format": "date-time", "example": "2022-06-06T16:00:00Z" }, "logpush_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/logpush_messages" }, "messages": { "$ref": "#/components/schemas/logpush_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "logpush_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/logpush_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/logpush_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "logpush_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common" } ] }, "logpush_dataset": { "description": "Name of the dataset. A list of supported datasets can be found on the [Developer Docs](https://developers.cloudflare.com/logs/reference/log-fields/).", "type": "string", "example": "http_requests", "default": "http_requests", "enum": [ "access_requests", "account_abuse_protection_events", "audit_logs", "audit_logs_v2", "biso_user_actions", "casb_findings", "device_posture_results", "dex_application_tests", "dex_device_state_events", "dlp_forensic_copies", "dns_firewall_logs", "dns_logs", "email_security_alerts", "email_security_post_delivery_events", "firewall_events", "gateway_dns", "gateway_http", "gateway_network", "http_requests", "ipsec_logs", "magic_bgp_logs", "magic_ids_detections", "mcp_portal_logs", "mnm_flow_logs", "nel_reports", "network_analytics_logs", "page_shield_events", "sinkhole_http_logs", "spectrum_events", "ssh_logs", "turnstile_events", "warp_config_changes", "warp_toggle_changes", "websocket_analytics", "workers_trace_events", "zaraz_events", "zero_trust_network_sessions" ], "nullable": true, "x-auditable": true }, "logpush_destination_conf": { "description": "Uniquely identifies a resource (such as an s3 bucket) where data. will be pushed. Additional configuration parameters supported by the destination may be included.", "type": "string", "format": "uri", "example": "s3://mybucket/logs?region=us-west-2", "maxLength": 4096, "x-sensitive": true }, "logpush_destination_conf-2": { "description": "Unique WebSocket address that will receive messages from Cloudflare’s edge.", "type": "string", "format": "uri", "example": "wss://logs.cloudflare.com/instant-logs/ws/sessions/99d471b1ca3c23cc8e30b6acec5db987", "maxLength": 4096, "x-auditable": true }, "logpush_destination_exists_response": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common" }, { "properties": { "result": { "type": "object", "nullable": true, "properties": { "exists": { "type": "boolean", "example": false, "x-auditable": true } } } }, "type": "object" } ] }, "logpush_enabled": { "description": "Flag that indicates if the job is enabled.", "type": "boolean", "example": false, "default": false, "x-auditable": true }, "logpush_error_message": { "description": "If not null, the job is currently failing. Failures are usually. repetitive (example: no permissions to write to destination bucket). Only the last failure is recorded. On successful execution of a job the error_message and last_error are set to null.", "type": "string", "nullable": true, "x-auditable": true }, "logpush_fields": { "description": "Comma-separated list of fields.", "type": "string", "example": "ClientIP,ClientRequestHost,ClientRequestMethod,ClientRequestURI,EdgeEndTimestamp,EdgeResponseBytes,EdgeResponseStatus,EdgeStartTimestamp,RayID", "x-auditable": true }, "logpush_filter": { "description": "The filters to select the events to include and/or remove from your logs. For more information, refer to [Filters](https://developers.cloudflare.com/logs/reference/filters/).", "type": "string", "example": "{\"where\":{\"and\":[{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/static\"},{\"key\":\"ClientRequestHost\",\"operator\":\"eq\",\"value\":\"example.com\"}]}}", "nullable": true }, "logpush_filter-2": { "description": "Filters to drill down into specific events.", "type": "string", "example": "{\"where\":{\"and\":[{\"key\":\"ClientCountry\",\"operator\":\"neq\",\"value\":\"ca\"}]}}", "x-auditable": true }, "logpush_filter_attack_traffic": { "description": "When true, excludes DDoS attack traffic from logs. This option is supported for the `http_requests`, `firewall_events`, and `network_analytics_logs` datasets.", "type": "boolean", "default": false, "x-auditable": true }, "logpush_frequency": { "description": "This field is deprecated. Please use `max_upload_*` parameters instead. . The frequency at which Cloudflare sends batches of logs to your destination. Setting frequency to high sends your logs in larger quantities of smaller files. Setting frequency to low sends logs in smaller quantities of larger files.", "type": "string", "example": "high", "default": "high", "deprecated": true, "enum": [ "high", "low" ], "nullable": true, "x-auditable": true }, "logpush_get_ownership_response": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common" }, { "properties": { "result": { "type": "object", "nullable": true, "properties": { "filename": { "type": "string", "example": "logs/challenge-filename.txt", "x-auditable": true }, "message": { "type": "string", "example": "", "x-auditable": true }, "valid": { "type": "boolean", "example": true, "x-auditable": true } } } }, "type": "object" } ] }, "logpush_id": { "description": "Unique id of the job.", "type": "integer", "minimum": 1, "x-auditable": true }, "logpush_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "logpush_instant_logs_job": { "type": "object", "properties": { "destination_conf": { "$ref": "#/components/schemas/logpush_destination_conf-2" }, "fields": { "$ref": "#/components/schemas/logpush_fields" }, "filter": { "$ref": "#/components/schemas/logpush_filter-2" }, "sample": { "$ref": "#/components/schemas/logpush_sample" }, "session_id": { "$ref": "#/components/schemas/logpush_session_id" } }, "nullable": true }, "logpush_instant_logs_job_response_collection": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/logpush_instant_logs_job" } } }, "type": "object" } ] }, "logpush_instant_logs_job_response_single": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/logpush_instant_logs_job" } }, "type": "object" } ] }, "logpush_kind": { "description": "The kind parameter (optional) is used to differentiate between Logpush and Edge Log Delivery jobs (when supported by the dataset).", "type": "string", "example": "", "default": "", "enum": [ "", "edge" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "logpush_last_complete": { "description": "Records the last time for which logs have been successfully pushed. If the last successful push was for logs range 2018-07-23T10:00:00Z to 2018-07-23T10:01:00Z then the value of this field will be 2018-07-23T10:01:00Z. If the job has never run or has just been enabled and hasn't run yet then the field will be empty.", "type": "string", "format": "date-time", "nullable": true, "x-auditable": true }, "logpush_last_error": { "description": "Records the last time the job failed. If not null, the job is currently. failing. If null, the job has either never failed or has run successfully at least once since last failure. See also the error_message field.", "type": "string", "format": "date-time", "nullable": true, "x-auditable": true }, "logpush_logpull_options": { "description": "This field is deprecated. Use `output_options` instead. Configuration string. It specifies things like requested fields and timestamp formats. If migrating from the logpull api, copy the url (full url or just the query string) of your call here, and logpush will keep on making this call for you, setting start and end times appropriately.", "type": "string", "format": "uri-reference", "example": "fields=RayID,ClientIP,EdgeStartTimestamp×tamps=rfc3339", "deprecated": true, "maxLength": 4096, "nullable": true, "x-auditable": true }, "logpush_logpush_field_response_collection": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common" }, { "properties": { "result": { "type": "object", "additionalProperties": { "type": "string", "x-auditable": true } } }, "type": "object" } ] }, "logpush_logpush_job": { "type": "object", "properties": { "dataset": { "$ref": "#/components/schemas/logpush_dataset" }, "destination_conf": { "$ref": "#/components/schemas/logpush_destination_conf" }, "enabled": { "$ref": "#/components/schemas/logpush_enabled" }, "error_message": { "$ref": "#/components/schemas/logpush_error_message" }, "filter_attack_traffic": { "$ref": "#/components/schemas/logpush_filter_attack_traffic" }, "frequency": { "$ref": "#/components/schemas/logpush_frequency" }, "id": { "$ref": "#/components/schemas/logpush_id" }, "kind": { "$ref": "#/components/schemas/logpush_kind" }, "last_complete": { "$ref": "#/components/schemas/logpush_last_complete" }, "last_error": { "$ref": "#/components/schemas/logpush_last_error" }, "logpull_options": { "$ref": "#/components/schemas/logpush_logpull_options" }, "max_upload_bytes": { "$ref": "#/components/schemas/logpush_max_upload_bytes" }, "max_upload_interval_seconds": { "$ref": "#/components/schemas/logpush_max_upload_interval_seconds" }, "max_upload_records": { "$ref": "#/components/schemas/logpush_max_upload_records" }, "name": { "$ref": "#/components/schemas/logpush_name" }, "output_options": { "$ref": "#/components/schemas/logpush_output_options" } }, "nullable": true }, "logpush_logpush_job_response_collection": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/logpush_logpush_job" } } }, "type": "object" } ] }, "logpush_logpush_job_response_single": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/logpush_logpush_job" } }, "type": "object" } ] }, "logpush_max_upload_bytes": { "description": "The maximum uncompressed file size of a batch of logs. This setting value must be between `5 MB` and `1 GB`, or `0` to disable it. Note that you cannot set a minimum file size; this means that log files may be much smaller than this batch size.", "type": "integer", "example": 5000000, "nullable": true, "oneOf": [ { "enum": [ 0 ], "type": "integer" }, { "maximum": 1000000000, "minimum": 5000000, "type": "integer" } ], "x-auditable": true }, "logpush_max_upload_interval_seconds": { "description": "The maximum interval in seconds for log batches. This setting must be between 30 and 300 seconds (5 minutes), or `0` to disable it. Note that you cannot specify a minimum interval for log batches; this means that log files may be sent in shorter intervals than this.", "type": "integer", "example": 30, "nullable": true, "oneOf": [ { "enum": [ 0 ], "type": "integer" }, { "maximum": 300, "minimum": 30, "type": "integer" } ], "x-auditable": true }, "logpush_max_upload_records": { "description": "The maximum number of log lines per batch. This setting must be between 1000 and 1,000,000 lines, or `0` to disable it. Note that you cannot specify a minimum number of log lines per batch; this means that log files may contain many fewer lines than this.", "type": "integer", "example": 1000, "nullable": true, "oneOf": [ { "enum": [ 0 ], "type": "integer" }, { "maximum": 1000000, "minimum": 1000, "type": "integer" } ], "x-auditable": true }, "logpush_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "logpush_name": { "description": "Optional human readable job name. Not unique. Cloudflare suggests. that you set this to a meaningful string, like the domain name, to make it easier to identify your job.", "type": "string", "example": "example.com", "maxLength": 512, "nullable": true, "pattern": "^[a-zA-Z0-9\\._-]*$", "x-auditable": true }, "logpush_output_options": { "description": "The structured replacement for `logpull_options`. When including this field, the `logpull_option` field will be ignored.", "type": "object", "properties": { "CVE-2021-44228": { "description": "If set to true, will cause all occurrences of `${` in the generated files to be replaced with `x{`.", "type": "boolean", "nullable": true, "x-auditable": true }, "batch_prefix": { "description": "String to be prepended before each batch.", "type": "string", "nullable": true, "x-auditable": true }, "batch_suffix": { "description": "String to be appended after each batch.", "type": "string", "nullable": true, "x-auditable": true }, "field_delimiter": { "description": "String to join fields. This field be ignored when `record_template` is set.", "type": "string", "nullable": true, "x-auditable": true }, "field_names": { "description": "List of field names to be included in the Logpush output. For the moment, there is no option to add all fields at once, so you must specify all the fields names you are interested in.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "ClientIP", "EdgeStartTimestamp", "RayID" ] }, "merge_subrequests": { "description": "If set to true, subrequests will be merged into the parent request. Only supported for the `http_requests` dataset.", "type": "boolean", "nullable": true, "x-auditable": true }, "output_type": { "description": "Specifies the output type, such as `ndjson` or `csv`. This sets default values for the rest of the settings, depending on the chosen output type. Some formatting rules, like string quoting, are different between output types.", "type": "string", "example": "ndjson", "enum": [ "ndjson", "csv" ], "x-auditable": true }, "record_delimiter": { "description": "String to be inserted in-between the records as separator.", "type": "string", "nullable": true, "x-auditable": true }, "record_prefix": { "description": "String to be prepended before each record.", "type": "string", "nullable": true, "x-auditable": true }, "record_suffix": { "description": "String to be appended after each record.", "type": "string", "nullable": true, "x-auditable": true }, "record_template": { "description": "String to use as template for each record instead of the default json key value mapping. All fields used in the template must be present in `field_names` as well, otherwise they will end up as null. Format as a Go `text/template` without any standard functions, like conditionals, loops, sub-templates, etc.", "type": "string", "nullable": true, "x-auditable": true }, "sample_rate": { "description": "Specifies the sampling rate as a floating number greater than 0 and at most 1. Sampling is applied on top of filtering, and regardless of the current `sample_interval` of the data.", "type": "number", "format": "float", "exclusiveMinimum": true, "maximum": 1, "minimum": 0, "nullable": true, "x-auditable": true }, "timestamp_format": { "description": "String to specify the format for timestamps, such as `unixnano`, `unix`, `rfc3339`, `rfc3339ms` or `rfc3339ns`.", "type": "string", "enum": [ "unixnano", "unix", "rfc3339", "rfc3339ms", "rfc3339ns" ], "x-auditable": true } }, "nullable": true }, "logpush_ownership_challenge": { "description": "Ownership challenge token to prove destination ownership.", "type": "string", "example": "00000000000000000000", "maxLength": 4096, "pattern": "^[a-zA-Z0-9/\\+\\._-]*$", "x-sensitive": true }, "logpush_sample": { "description": "The sample parameter is the sample rate of the records set by the client: \"sample\": 1 is 100% of records \"sample\": 10 is 10% and so on.", "type": "integer", "example": 1, "x-auditable": true }, "logpush_session_id": { "description": "Unique session id of the job.", "type": "string", "example": "99d471b1ca3c23cc8e30b6acec5db987", "x-auditable": true }, "logpush_transformer": { "type": "object", "properties": { "associated_jobs": { "description": "Logpush jobs that reference this transformer.", "type": "array", "items": { "$ref": "#/components/schemas/logpush_transformer_job_ref" } }, "created_at": { "description": "When the transformer was created (RFC 3339).", "type": "string", "format": "date-time", "example": "2026-08-01T12:00:00Z" }, "dataset": { "$ref": "#/components/schemas/logpush_transformer_dataset" }, "description": { "$ref": "#/components/schemas/logpush_transformer_description" }, "id": { "$ref": "#/components/schemas/logpush_transformer_identifier" }, "name": { "$ref": "#/components/schemas/logpush_transformer_name" }, "updated_at": { "description": "When the transformer was last modified (RFC 3339).", "type": "string", "format": "date-time", "example": "2026-08-10T15:30:00Z" } } }, "logpush_transformer_code": { "description": "The SQL transformer query. Maximum 32 KB. The query must contain a FROM clause referencing a valid logpush dataset.", "type": "string", "example": "SELECT ClientIP, RayID FROM http_requests", "maxLength": 32768, "x-auditable": true }, "logpush_transformer_content_response": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "content": { "description": "The SQL query content.", "example": "SELECT ClientIP, RayID FROM http_requests", "type": "string" } } } }, "type": "object" } ] }, "logpush_transformer_create_request": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/logpush_transformer_code" }, "description": { "$ref": "#/components/schemas/logpush_transformer_description" }, "name": { "$ref": "#/components/schemas/logpush_transformer_name" } }, "required": [ "name", "code" ] }, "logpush_transformer_dataset": { "description": "The dataset this transformer operates on, derived from the SQL query's FROM clause. Informational only. May be absent if the dataset cannot be determined from the query.", "type": "string", "example": "http_requests", "nullable": true, "x-auditable": true }, "logpush_transformer_delete_response": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "description": "The deleted transformer's ID.", "type": "integer", "example": 42 } } } }, "type": "object" } ] }, "logpush_transformer_description": { "description": "Optional customer-provided description.", "type": "string", "example": "Redacts PII fields from HTTP request logs.", "maxLength": 4096, "x-auditable": true }, "logpush_transformer_identifier": { "description": "The transformer ID.", "type": "integer", "example": 42, "minimum": 1, "x-auditable": true }, "logpush_transformer_job_ref": { "type": "object", "properties": { "id": { "description": "The logpush job ID.", "type": "integer", "example": 123 }, "name": { "description": "The logpush job destination name.", "type": "string", "example": "s3-export" }, "object_tag": { "description": "The zone or account tag.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" }, "object_type": { "description": "Whether the job is zone-scoped or account-scoped.", "type": "string", "example": "zone", "enum": [ "zone", "account" ] } } }, "logpush_transformer_name": { "description": "Customer-provided name for identification.", "type": "string", "example": "redact-pii", "maxLength": 255, "x-auditable": true }, "logpush_transformer_preview_request": { "type": "object", "properties": { "input": { "description": "A single log record to transform (JSON object).", "type": "object", "example": { "ClientIP": "198.51.100.1", "ClientRequestHost": "example.com", "EdgeStartTimestamp": 1722513600000000000, "RayID": "abcdef1234567890" }, "additionalProperties": true }, "sql": { "$ref": "#/components/schemas/logpush_transformer_code" } }, "required": [ "sql", "input" ] }, "logpush_transformer_preview_response": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-single" }, { "properties": { "result": { "description": "An array of transformed log records. Queries that produce multiple rows from a single input (e.g. via UNNEST) return one object per output row. Null if the query filtered out the input record.", "type": "array", "items": { "additionalProperties": true, "type": "object" }, "example": [ { "ClientIP": "198.51.100.1", "RayID": "abcdef1234567890" } ], "nullable": true } }, "type": "object" } ] }, "logpush_transformer_response_collection": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/logpush_transformer" } } }, "type": "object" } ] }, "logpush_transformer_response_single": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/logpush_transformer" } }, "type": "object" } ] }, "logpush_transformer_update_request": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/logpush_transformer_code" }, "description": { "$ref": "#/components/schemas/logpush_transformer_description" }, "name": { "$ref": "#/components/schemas/logpush_transformer_name" } }, "required": [ "name" ] }, "logpush_transformer_version": { "type": "object", "properties": { "created_at": { "description": "When this version was created (RFC 3339).", "type": "string", "format": "date-time", "example": "2026-08-10T15:30:00Z" }, "id": { "description": "Unique identifier for this version.", "type": "integer", "format": "int64", "example": 1, "minimum": 1 }, "version": { "description": "Sequential version number.", "type": "integer", "example": 3, "minimum": 1 } } }, "logpush_transformer_version_response_collection": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/logpush_transformer_version" } } }, "type": "object" } ] }, "logpush_validate_ownership_response": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common" }, { "properties": { "result": { "type": "object", "nullable": true, "properties": { "valid": { "type": "boolean", "example": true, "x-auditable": true } } } }, "type": "object" } ] }, "logpush_validate_response": { "allOf": [ { "$ref": "#/components/schemas/logpush_api-response-common" }, { "properties": { "result": { "type": "object", "nullable": true, "properties": { "message": { "type": "string", "example": "", "x-auditable": true }, "valid": { "type": "boolean", "example": true, "x-auditable": true } } } }, "type": "object" } ] }, "logshare_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/logshare_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/logshare_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "logshare_count": { "description": "When `?count=` is provided, the response will contain up to `count` results. Since results are not sorted, you are likely to get different data for repeated requests. `count` must be an integer > 0.", "type": "integer", "minimum": 1, "x-auditable": true }, "logshare_end": { "description": "Sets the (exclusive) end of the requested time frame. This can be a unix timestamp (in seconds or nanoseconds), or an absolute timestamp that conforms to RFC 3339. `end` must be at least five minutes earlier than now and must be later than `start`. Difference between `start` and `end` must be not greater than one hour.", "example": "2018-05-20T10:01:00Z", "anyOf": [ { "type": "string" }, { "type": "integer" } ], "x-auditable": true }, "logshare_fields": { "description": "The `/received` route by default returns a limited set of fields, and allows customers to override the default field set by specifying individual fields. The reasons for this are: 1. Most customers require only a small subset of fields, but that subset varies from customer to customer; 2. Flat schema is much easier to work with downstream (importing into BigTable etc); 3. Performance (time to process, file size). If `?fields=` is not specified, default field set is returned. This default field set may change at any time. When `?fields=` is provided, each record is returned with the specified fields. `fields` must be specified as a comma separated list without any whitespaces, and all fields must exist. The order in which fields are specified does not matter, and the order of fields in the response is not specified.", "type": "string", "example": "ClientIP,RayID,EdgeStartTimestamp", "x-auditable": true }, "logshare_fields_response": { "type": "object", "properties": { "key": { "type": "string", "example": "value", "x-auditable": true } } }, "logshare_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "logshare_logs_response_json_lines": { "example": "{\"ClientIP\":\"192.0.2.1\",\"RayID\":\"41ddf1740f67442d\",\"EdgeStartTimestamp\":1526810289280000000}\n{\"ClientIP\":\"192.0.2.1\",\"RayID\":\"41ddf1740f67442d\",\"EdgeStartTimestamp\":1526810289280000000}\n{\"ClientIP\":\"192.0.2.1\",\"RayID\":\"41ddf1740f67442d\",\"EdgeStartTimestamp\":1526810289280000000}", "anyOf": [ { "type": "string" }, { "type": "object" } ] }, "logshare_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "logshare_ray_identifier": { "description": "Ray identifier.", "type": "string", "example": "41ddf1740f67442d", "maxLength": 16, "readOnly": true, "x-auditable": true }, "logshare_sample": { "description": "When `?sample=` is provided, a sample of matching records is returned. If `sample=0.1` then 10% of records will be returned. Sampling is random: repeated calls will not only return different records, but likely will also vary slightly in number of returned records. When `?count=` is also specified, `count` is applied to the number of returned records, not the sampled records. So, with `sample=0.05` and `count=7`, when there is a total of 100 records available, approximately five will be returned. When there are 1000 records, seven will be returned. When there are 10,000 records, seven will be returned.", "type": "number", "example": 0.1, "maximum": 1, "minimum": 0, "x-auditable": true }, "logshare_start": { "description": "Sets the (inclusive) beginning of the requested time frame. This can be a unix timestamp (in seconds or nanoseconds), or an absolute timestamp that conforms to RFC 3339. At this point in time, it cannot exceed a time in the past greater than seven days.", "example": "2018-05-20T10:00:00Z", "anyOf": [ { "type": "string" }, { "type": "integer" } ], "x-auditable": true }, "logshare_timestamps": { "description": "By default, timestamps in responses are returned as Unix nanosecond integers. The `?timestamps=` argument can be set to change the format in which response timestamps are returned. Possible values are: `unix`, `unixnano`, `rfc3339`. Note that `unix` and `unixnano` return timestamps as integers; `rfc3339` returns timestamps as strings.", "type": "string", "example": "unixnano", "default": "unixnano", "enum": [ "unix", "unixnano", "rfc3339" ], "x-auditable": true }, "logshare_zone_identifier": { "$ref": "#/components/schemas/logshare_identifier" }, "magic-transit_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/magic-transit_messages" }, "messages": { "$ref": "#/components/schemas/magic-transit_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "magic-transit_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/magic-transit_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/magic-transit_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "magic-transit_asn": { "description": "AS number associated with the node object.", "type": "string" }, "magic-transit_check_type": { "description": "type of check to perform", "type": "string", "example": "icmp", "default": "icmp", "enum": [ "icmp" ] }, "magic-transit_colo": { "type": "object", "properties": { "city": { "$ref": "#/components/schemas/magic-transit_colo_city" }, "name": { "$ref": "#/components/schemas/magic-transit_colo_name" } } }, "magic-transit_colo_city": { "description": "Source colo city.", "type": "string", "example": "Denver, CO, US" }, "magic-transit_colo_name": { "description": "Source colo name.", "type": "string", "example": "den01" }, "magic-transit_colo_result": { "type": "object", "properties": { "colo": { "$ref": "#/components/schemas/magic-transit_colo" }, "error": { "$ref": "#/components/schemas/magic-transit_error" }, "hops": { "type": "array", "items": { "$ref": "#/components/schemas/magic-transit_hop_result" } }, "target_summary": { "$ref": "#/components/schemas/magic-transit_target_summary" }, "traceroute_time_ms": { "$ref": "#/components/schemas/magic-transit_traceroute_time_ms" } } }, "magic-transit_colos": { "description": "If no source colo names specified, all colos will be used. China colos are unavailable for traceroutes.", "type": "array", "items": { "description": "Source colo name.", "type": "string" }, "example": [ "den", "sin" ] }, "magic-transit_endpoint_health_check": { "type": "object", "properties": { "check_type": { "$ref": "#/components/schemas/magic-transit_check_type" }, "endpoint": { "description": "the IP address of the host to perform checks against", "type": "string", "example": "203.0.113.1" }, "name": { "description": "Optional name associated with this check", "type": "string", "example": "My Endpoint" } }, "required": [ "check_type", "endpoint" ] }, "magic-transit_endpoint_health_check_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/magic-transit_endpoint_health_check" }, { "properties": { "id": { "$ref": "#/components/schemas/magic-transit_uuid" } } } ], "required": [ "id", "check_type", "endpoint" ] }, "magic-transit_endpoint_health_check_response_collection": { "allOf": [ { "$ref": "#/components/schemas/magic-transit_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/magic-transit_endpoint_health_check_response" } } } } ] }, "magic-transit_endpoint_health_check_response_single": { "allOf": [ { "$ref": "#/components/schemas/magic-transit_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/magic-transit_endpoint_health_check_response" } } } ] }, "magic-transit_error": { "description": "Errors resulting from collecting traceroute from colo to target.", "type": "string", "example": "", "enum": [ "", "Could not gather traceroute data: Code 1", "Could not gather traceroute data: Code 2", "Could not gather traceroute data: Code 3", "Could not gather traceroute data: Code 4" ] }, "magic-transit_hop_result": { "type": "object", "properties": { "nodes": { "description": "An array of node objects.", "type": "array", "items": { "$ref": "#/components/schemas/magic-transit_node_result" } }, "packets_lost": { "$ref": "#/components/schemas/magic-transit_packets_lost" }, "packets_sent": { "$ref": "#/components/schemas/magic-transit_packets_sent" }, "packets_ttl": { "$ref": "#/components/schemas/magic-transit_packets_ttl" } } }, "magic-transit_identifier": { "description": "Identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "magic-transit_ip": { "description": "IP address of the node.", "type": "string" }, "magic-transit_labels": { "description": "Field appears if there is an additional annotation printed when the probe returns. Field also appears when running a GRE+ICMP traceroute to denote which traceroute a node comes from.", "type": "array", "items": { "type": "string" } }, "magic-transit_max_rtt_ms": { "description": "Maximum RTT in ms.", "type": "number" }, "magic-transit_max_ttl": { "description": "Max TTL.", "type": "integer", "default": 15, "maximum": 64, "minimum": 0 }, "magic-transit_mean_rtt_ms": { "description": "Mean RTT in ms.", "type": "number" }, "magic-transit_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "magic-transit_min_rtt_ms": { "description": "Minimum RTT in ms.", "type": "number" }, "magic-transit_name": { "description": "Host name of the address, this may be the same as the IP address.", "type": "string" }, "magic-transit_node_result": { "type": "object", "properties": { "asn": { "$ref": "#/components/schemas/magic-transit_asn" }, "ip": { "$ref": "#/components/schemas/magic-transit_ip" }, "labels": { "$ref": "#/components/schemas/magic-transit_labels" }, "max_rtt_ms": { "$ref": "#/components/schemas/magic-transit_max_rtt_ms" }, "mean_rtt_ms": { "$ref": "#/components/schemas/magic-transit_mean_rtt_ms" }, "min_rtt_ms": { "$ref": "#/components/schemas/magic-transit_min_rtt_ms" }, "name": { "$ref": "#/components/schemas/magic-transit_name" }, "packet_count": { "$ref": "#/components/schemas/magic-transit_packet_count" }, "std_dev_rtt_ms": { "$ref": "#/components/schemas/magic-transit_std_dev_rtt_ms" } }, "example": { "asn": "AS13335", "ip": "1.1.1.1", "max_latency_ms": 0.034, "mean_latency_ms": 0.021, "min_latency_ms": 0.014, "name": "one.one.one.one", "packet_count": 3, "std_dev_latency_ms": 0.011269427669584647 } }, "magic-transit_options": { "type": "object", "properties": { "max_ttl": { "$ref": "#/components/schemas/magic-transit_max_ttl" }, "packet_type": { "$ref": "#/components/schemas/magic-transit_packet_type" }, "packets_per_ttl": { "$ref": "#/components/schemas/magic-transit_packets_per_ttl" }, "port": { "$ref": "#/components/schemas/magic-transit_port" }, "wait_time": { "$ref": "#/components/schemas/magic-transit_wait_time" } }, "example": { "max_ttl": 15, "packet_type": "icmp" } }, "magic-transit_packet_count": { "description": "Number of packets with a response from this node.", "type": "integer" }, "magic-transit_packet_type": { "description": "Type of packet sent.", "type": "string", "example": "icmp", "default": "icmp", "enum": [ "icmp", "tcp", "udp", "gre", "gre+icmp" ] }, "magic-transit_packets_lost": { "description": "Number of packets where no response was received.", "type": "integer" }, "magic-transit_packets_per_ttl": { "description": "Number of packets sent at each TTL.", "type": "integer", "default": 3, "maximum": 10, "minimum": 0 }, "magic-transit_packets_sent": { "description": "Number of packets sent with specified TTL.", "type": "integer" }, "magic-transit_packets_ttl": { "description": "The time to live (TTL).", "type": "integer" }, "magic-transit_port": { "description": "For UDP and TCP, specifies the destination port. For ICMP, specifies the initial ICMP sequence value. Default value 0 will choose the best value to use for each protocol.", "type": "integer", "default": 0, "maximum": 65535, "minimum": 0 }, "magic-transit_std_dev_rtt_ms": { "description": "Standard deviation of the RTTs in ms.", "type": "number" }, "magic-transit_target": { "description": "The target hostname, IPv6, or IPv6 address.", "type": "string", "example": "1.1.1.1" }, "magic-transit_target_result": { "type": "object", "properties": { "colos": { "type": "array", "items": { "$ref": "#/components/schemas/magic-transit_colo_result" } }, "target": { "$ref": "#/components/schemas/magic-transit_target" } } }, "magic-transit_target_summary": { "description": "Aggregated statistics from all hops about the target.", "type": "object", "example": { "asn": "", "ip": "1.1.1.1", "max_latency_ms": 0.034, "mean_latency_ms": 0.021, "min_latency_ms": 0.014, "name": "1.1.1.1", "packet_count": 3, "std_dev_latency_ms": 0.011269427669584647 } }, "magic-transit_targets": { "type": "array", "items": { "description": "Hosts as a hostname or IPv4/IPv6 address represented by strings.", "example": "203.0.113.1", "type": "string" }, "example": [ "203.0.113.1", "cloudflare.com" ], "maxLength": 10 }, "magic-transit_traceroute_response_collection": { "allOf": [ { "$ref": "#/components/schemas/magic-transit_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/magic-transit_target_result" } } } } ] }, "magic-transit_traceroute_time_ms": { "description": "Total time of traceroute in ms.", "type": "integer" }, "magic-transit_uuid": { "description": "UUID.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36 }, "magic-transit_wait_time": { "description": "Set the time (in seconds) to wait for a response to a probe.", "type": "integer", "default": 1, "maximum": 5, "minimum": 1 }, "magic-visibility-mnm_account_identifier": { "type": "string", "example": "6f91088a406011ed95aed352566e8d4c", "x-auditable": true }, "magic-visibility-mnm_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/magic-visibility-mnm_api-response-common" }, { "properties": { "result": { "type": "array", "items": {}, "nullable": true }, "result_info": { "$ref": "#/components/schemas/magic-visibility-mnm_result_info" } } } ] }, "magic-visibility-mnm_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/magic-visibility-mnm_messages" }, "messages": { "$ref": "#/components/schemas/magic-visibility-mnm_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": {}, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "magic-visibility-mnm_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/magic-visibility-mnm_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/magic-visibility-mnm_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "magic-visibility-mnm_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/magic-visibility-mnm_api-response-common" }, { "properties": { "result": { "anyOf": [ { "nullable": true, "type": "object" }, { "nullable": true, "type": "string" } ] } } } ] }, "magic-visibility-mnm_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "magic-visibility-mnm_mnm_config": { "type": "object", "properties": { "default_sampling": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_config_default_sampling" }, "name": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_config_name" }, "router_ips": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_config_router_ips" }, "warp_devices": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_config_warp_devices" } }, "required": [ "name", "default_sampling", "router_ips", "warp_devices" ] }, "magic-visibility-mnm_mnm_config_default_sampling": { "description": "Fallback sampling rate of flow messages being sent in packets per second. This should match the packet sampling rate configured on the router.", "type": "number", "default": 1, "minimum": 1, "x-auditable": true }, "magic-visibility-mnm_mnm_config_name": { "description": "The account name.", "type": "string", "example": "cloudflare user's account", "x-auditable": true }, "magic-visibility-mnm_mnm_config_router_ip": { "description": "IPv4 CIDR of the router sourcing flow data. Only /32 addresses are currently supported.", "type": "string", "example": "203.0.113.1", "x-auditable": true }, "magic-visibility-mnm_mnm_config_router_ips": { "type": "array", "items": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_config_router_ip" } }, "magic-visibility-mnm_mnm_config_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic-visibility-mnm_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_config" } }, "type": "object" } ] }, "magic-visibility-mnm_mnm_config_warp_device": { "description": "Object representing a warp device with an ID and name.", "type": "object", "properties": { "id": { "description": "Unique identifier for the warp device.", "type": "string", "example": "5360368d-b351-4791-abe1-93550dabd351", "x-auditable": true }, "name": { "description": "Name of the warp device.", "type": "string", "example": "My warp device", "x-auditable": true }, "router_ip": { "description": "IPv4 CIDR of the router sourcing flow data associated with this warp device. Only /32 addresses are currently supported.", "type": "string", "example": "203.0.113.1", "x-auditable": true } }, "required": [ "id", "name", "router_ip" ] }, "magic-visibility-mnm_mnm_config_warp_devices": { "type": "array", "items": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_config_warp_device" } }, "magic-visibility-mnm_mnm_rule": { "type": "object", "properties": { "automatic_advertisement": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_automatic_advertisement" }, "bandwidth_threshold": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_bandwidth_threshold" }, "duration": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_duration" }, "id": { "$ref": "#/components/schemas/magic-visibility-mnm_rule_identifier" }, "name": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_name" }, "packet_threshold": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_packet_threshold" }, "prefix_match": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_prefix_match" }, "prefixes": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_ip_prefixes" }, "type": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_type" }, "zscore_sensitivity": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_zscore_sensitivity" }, "zscore_target": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_zscore_target" } }, "nullable": true, "required": [ "id", "name", "prefixes", "automatic_advertisement", "type" ] }, "magic-visibility-mnm_mnm_rule_advertisable_response": { "type": "object", "properties": { "automatic_advertisement": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_automatic_advertisement" } }, "nullable": true, "required": [ "automatic_advertisement" ] }, "magic-visibility-mnm_mnm_rule_advertisement_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic-visibility-mnm_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_advertisable_response" } }, "type": "object" } ] }, "magic-visibility-mnm_mnm_rule_automatic_advertisement": { "description": "Toggle on if you would like Cloudflare to automatically advertise the IP Prefixes within the rule via Magic Transit when the rule is triggered. Only available for users of Magic Transit.", "type": "boolean", "example": "false", "nullable": true, "x-auditable": true }, "magic-visibility-mnm_mnm_rule_bandwidth_threshold": { "description": "The number of bits per second for the rule. When this value is exceeded for the set duration, an alert notification is sent. Minimum of 1 and no maximum.", "type": "number", "example": 1000, "minimum": 1, "x-auditable": true }, "magic-visibility-mnm_mnm_rule_create": { "type": "object", "properties": { "automatic_advertisement": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_automatic_advertisement" }, "bandwidth_threshold": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_bandwidth_threshold" }, "duration": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_duration" }, "name": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_name" }, "packet_threshold": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_packet_threshold" }, "prefix_match": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_prefix_match" }, "prefixes": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_ip_prefixes" }, "type": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_type" }, "zscore_sensitivity": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_zscore_sensitivity" }, "zscore_target": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_zscore_target" } }, "nullable": true, "required": [ "name", "prefixes", "automatic_advertisement", "type" ] }, "magic-visibility-mnm_mnm_rule_duration": { "description": "The amount of time that the rule threshold must be exceeded to send an alert notification. The final value must be equivalent to one of the following 8 values [\"1m\",\"5m\",\"10m\",\"15m\",\"20m\",\"30m\",\"45m\",\"60m\"].", "type": "string", "example": "300s", "default": "1m", "enum": [ "1m", "5m", "10m", "15m", "20m", "30m", "45m", "60m" ], "x-auditable": true }, "magic-visibility-mnm_mnm_rule_ip_prefix": { "description": "The IP prefixes that are monitored for this rule. Must be a CIDR range like 203.0.113.0/24. Max 5000 different CIDR ranges.", "type": "string", "example": "203.0.113.1/32", "x-auditable": true }, "magic-visibility-mnm_mnm_rule_ip_prefixes": { "type": "array", "items": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule_ip_prefix" } }, "magic-visibility-mnm_mnm_rule_name": { "description": "The name of the rule. Must be unique. Supports characters A-Z, a-z, 0-9, underscore (_), dash (-), period (.), and tilde (~). You can’t have a space in the rule name. Max 256 characters.", "type": "string", "example": "my_rule_1", "x-auditable": true }, "magic-visibility-mnm_mnm_rule_packet_threshold": { "description": "The number of packets per second for the rule. When this value is exceeded for the set duration, an alert notification is sent. Minimum of 1 and no maximum.", "type": "number", "example": 10000, "minimum": 1, "x-auditable": true }, "magic-visibility-mnm_mnm_rule_prefix_match": { "description": "Prefix match type to be applied for a prefix auto advertisement when using an advanced_ddos rule.", "type": "string", "example": "exact", "enum": [ "exact", "subnet", "supernet" ], "nullable": true, "x-auditable": true }, "magic-visibility-mnm_mnm_rule_type": { "description": "MNM rule type.", "type": "string", "example": "zscore", "enum": [ "threshold", "zscore", "advanced_ddos" ], "x-auditable": true }, "magic-visibility-mnm_mnm_rule_zscore_sensitivity": { "description": "Level of sensitivity set for zscore rules.", "type": "string", "example": "high", "enum": [ "low", "medium", "high" ], "nullable": true, "x-auditable": true }, "magic-visibility-mnm_mnm_rule_zscore_target": { "description": "Target of the zscore rule analysis.", "type": "string", "example": "bits", "enum": [ "bits", "packets" ], "nullable": true, "x-auditable": true }, "magic-visibility-mnm_mnm_rules_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic-visibility-mnm_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule" }, "nullable": true } } } ] }, "magic-visibility-mnm_mnm_rules_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic-visibility-mnm_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_rule" } }, "type": "object" } ] }, "magic-visibility-mnm_mnm_vpc_flows_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic-visibility-mnm_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic-visibility-mnm_mnm_vpc_flows_token" } }, "type": "object" } ] }, "magic-visibility-mnm_mnm_vpc_flows_token": { "description": "Authentication token to be used for VPC Flows export authentication.", "type": "string", "example": "JWE/JWT auth token", "x-sensitive": true }, "magic-visibility-mnm_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters", "type": "number", "example": 2000 } } }, "magic-visibility-mnm_rule_identifier": { "description": "The id of the rule. Must be unique.", "type": "string", "example": "2890e6fa406311ed9b5a23f70f6fb8cf", "x-auditable": true }, "magic-visibility-pcaps_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/magic-visibility-pcaps_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "type": "object" }, "nullable": true }, "result_info": { "$ref": "#/components/schemas/magic-visibility-pcaps_result_info" } }, "type": "object" } ] }, "magic-visibility-pcaps_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/magic-visibility-pcaps_messages" }, "messages": { "$ref": "#/components/schemas/magic-visibility-pcaps_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": { "type": "object" }, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "magic-visibility-pcaps_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/magic-visibility-pcaps_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/magic-visibility-pcaps_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "result" ] }, "magic-visibility-pcaps_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/magic-visibility-pcaps_api-response-common" }, { "properties": { "result": { "anyOf": [ { "type": "object" }, { "type": "string" } ] } }, "type": "object" } ] }, "magic-visibility-pcaps_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "magic-visibility-pcaps_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "magic-visibility-pcaps_pcaps_byte_limit": { "description": "The maximum number of bytes to capture. This field only applies to `full` packet captures.", "type": "number", "example": 500000, "maximum": 1000000000, "minimum": 1, "x-auditable": true }, "magic-visibility-pcaps_pcaps_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic-visibility-pcaps_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_response_simple" }, { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_response_full" } ] } } }, "type": "object" } ] }, "magic-visibility-pcaps_pcaps_colo_name": { "description": "The name of the data center used for the packet capture. This can be a specific colo (ord02) or a multi-colo name (ORD). This field only applies to `full` packet captures.", "type": "string", "example": "ord02", "x-auditable": true }, "magic-visibility-pcaps_pcaps_destination_conf": { "description": "The full URI for the bucket. This field only applies to `full` packet captures.", "type": "string", "example": "s3://pcaps-bucket?region=us-east-1" }, "magic-visibility-pcaps_pcaps_error_message": { "description": "An error message that describes why the packet capture failed. This field only applies to `full` packet captures.", "type": "string", "example": "No packets matched the filter in the time limit given. Please modify the filter or try again." }, "magic-visibility-pcaps_pcaps_filter_v1": { "description": "The packet capture filter. When this field is empty, all packets are captured.", "type": "object", "properties": { "destination_address": { "description": "The destination IP address of the packet.", "type": "string", "example": "1.2.3.4", "x-auditable": true }, "destination_port": { "description": "The destination port of the packet.", "type": "number", "example": 80, "x-auditable": true }, "protocol": { "description": "The protocol number of the packet.", "type": "number", "example": 6, "x-auditable": true }, "source_address": { "description": "The source IP address of the packet.", "type": "string", "example": "1.2.3.4", "x-auditable": true }, "source_port": { "description": "The source port of the packet.", "type": "number", "example": 123, "x-auditable": true } } }, "magic-visibility-pcaps_pcaps_id": { "description": "The ID for the packet capture.", "type": "string", "example": "66802ca5668e47a2b82c2e6746e45037", "maxLength": 32, "minLength": 32, "x-auditable": true }, "magic-visibility-pcaps_pcaps_offset_time": { "description": "The RFC 3339 offset timestamp from which to query backwards for packets. Must be within the last 24h. When this field is empty, defaults to time of request.", "type": "string", "format": "date-time", "example": "2020-01-01T08:00:00Z", "x-auditable": true }, "magic-visibility-pcaps_pcaps_ownership_challenge": { "description": "The ownership challenge filename stored in the bucket.", "type": "string", "example": "ownership-challenge-9883874ecac311ec8475433579a6bf5f.txt" }, "magic-visibility-pcaps_pcaps_ownership_collection": { "allOf": [ { "$ref": "#/components/schemas/magic-visibility-pcaps_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_ownership_response" }, "nullable": true } }, "type": "object" } ] }, "magic-visibility-pcaps_pcaps_ownership_request": { "type": "object", "properties": { "destination_conf": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_destination_conf" } }, "required": [ "destination_conf" ] }, "magic-visibility-pcaps_pcaps_ownership_response": { "type": "object", "properties": { "destination_conf": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_destination_conf" }, "filename": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_ownership_challenge" }, "id": { "description": "The bucket ID associated with the packet captures API.", "type": "string", "example": "9883874ecac311ec8475433579a6bf5f", "maxLength": 32, "minLength": 32 }, "status": { "description": "The status of the ownership challenge. Can be pending, success or failed.", "type": "string", "example": "success", "enum": [ "pending", "success", "failed" ] }, "submitted": { "description": "The RFC 3339 timestamp when the bucket was added to packet captures API.", "type": "string", "example": "2020-01-01T08:00:00Z" }, "validated": { "description": "The RFC 3339 timestamp when the bucket was validated.", "type": "string", "example": "2020-01-01T08:00:00Z" } }, "required": [ "id", "status", "submitted", "destination_conf", "filename" ] }, "magic-visibility-pcaps_pcaps_ownership_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic-visibility-pcaps_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_ownership_response" } }, "type": "object" } ] }, "magic-visibility-pcaps_pcaps_ownership_validate_request": { "type": "object", "properties": { "destination_conf": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_destination_conf" }, "ownership_challenge": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_ownership_challenge" } }, "required": [ "destination_conf", "ownership_challenge" ] }, "magic-visibility-pcaps_pcaps_packet_limit": { "description": "The limit of packets contained in a packet capture.", "type": "number", "example": 10000, "maximum": 10000, "minimum": 1, "x-auditable": true }, "magic-visibility-pcaps_pcaps_packets_captured": { "description": "The number of packets captured.", "type": "integer" }, "magic-visibility-pcaps_pcaps_request_full": { "type": "object", "properties": { "byte_limit": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_byte_limit" }, "colo_name": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_colo_name" }, "destination_conf": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_destination_conf" }, "filter_v1": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_filter_v1" }, "packet_limit": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_packet_limit" }, "system": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_system" }, "time_limit": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_time_limit_full" }, "type": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_type" } }, "required": [ "time_limit", "type", "system", "colo_name", "destination_conf" ] }, "magic-visibility-pcaps_pcaps_request_pcap": { "anyOf": [ { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_request_simple" }, { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_request_full" } ] }, "magic-visibility-pcaps_pcaps_request_simple": { "type": "object", "properties": { "filter_v1": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_filter_v1" }, "offset_time": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_offset_time" }, "packet_limit": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_packet_limit" }, "system": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_system" }, "time_limit": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_time_limit_sampled" }, "type": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_type" } }, "required": [ "time_limit", "packet_limit", "type", "system" ] }, "magic-visibility-pcaps_pcaps_response_full": { "type": "object", "properties": { "byte_limit": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_byte_limit" }, "colo_name": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_colo_name" }, "destination_conf": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_destination_conf" }, "error_message": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_error_message" }, "filter_v1": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_filter_v1" }, "id": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_id" }, "packets_captured": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_packets_captured" }, "status": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_status" }, "stop_requested": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_stop_requested" }, "submitted": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_submitted" }, "system": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_system" }, "time_limit": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_time_limit_full" }, "type": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_type" } } }, "magic-visibility-pcaps_pcaps_response_simple": { "type": "object", "properties": { "filter_v1": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_filter_v1" }, "id": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_id" }, "offset_time": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_offset_time" }, "status": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_status" }, "submitted": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_submitted" }, "system": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_system" }, "time_limit": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_time_limit_sampled" }, "type": { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_type" } } }, "magic-visibility-pcaps_pcaps_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic-visibility-pcaps_api-response-single" }, { "properties": { "result": { "anyOf": [ { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_response_simple" }, { "$ref": "#/components/schemas/magic-visibility-pcaps_pcaps_response_full" } ] } }, "type": "object" } ] }, "magic-visibility-pcaps_pcaps_status": { "description": "The status of the packet capture request.", "type": "string", "example": "success", "enum": [ "unknown", "success", "pending", "running", "conversion_pending", "conversion_running", "complete", "failed" ] }, "magic-visibility-pcaps_pcaps_stop_requested": { "description": "The RFC 3339 timestamp when stopping the packet capture was requested. This field only applies to `full` packet captures.", "type": "string", "format": "date-time" }, "magic-visibility-pcaps_pcaps_submitted": { "description": "The RFC 3339 timestamp when the packet capture was created.", "type": "string", "example": "2020-01-01T08:00:00Z" }, "magic-visibility-pcaps_pcaps_system": { "description": "The system used to collect packet captures.", "type": "string", "example": "magic-transit", "enum": [ "magic-transit" ], "x-auditable": true }, "magic-visibility-pcaps_pcaps_time_limit_full": { "description": "The packet capture duration in seconds.", "type": "number", "example": 86400, "maximum": 86400, "minimum": 1, "x-auditable": true }, "magic-visibility-pcaps_pcaps_time_limit_sampled": { "description": "The packet capture duration in seconds.", "type": "number", "example": 300, "maximum": 300, "minimum": 1, "x-auditable": true }, "magic-visibility-pcaps_pcaps_type": { "description": "The type of packet capture. `Simple` captures sampled packets, and `full` captures entire payloads and non-sampled packets.", "type": "string", "example": "simple", "enum": [ "simple", "full" ], "x-auditable": true }, "magic-visibility-pcaps_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 } } }, "magic_account_app": { "description": "Custom app defined for an account.", "type": "object", "properties": { "account_app_id": { "$ref": "#/components/schemas/magic_account_app_id" }, "hostnames": { "$ref": "#/components/schemas/magic_app_hostnames" }, "ip_subnets": { "$ref": "#/components/schemas/magic_app_subnets" }, "name": { "$ref": "#/components/schemas/magic_app_name" }, "source_subnets": { "$ref": "#/components/schemas/magic_app_source_subnets" }, "type": { "$ref": "#/components/schemas/magic_app_type" } }, "required": [ "account_app_id" ], "title": "Account App" }, "magic_account_app_id": { "description": "Magic account app ID.", "type": "string", "example": "ac60d3d0435248289d446cedd870bcf4" }, "magic_acl": { "description": "Bidirectional ACL policy for network traffic within a site.", "type": "object", "properties": { "description": { "description": "Description for the ACL.", "type": "string", "example": "Allows local traffic between PIN pads and cash register." }, "forward_locally": { "$ref": "#/components/schemas/magic_forward_locally" }, "id": { "$ref": "#/components/schemas/magic_identifier" }, "lan_1": { "$ref": "#/components/schemas/magic_lan-acl-configuration" }, "lan_2": { "$ref": "#/components/schemas/magic_lan-acl-configuration" }, "name": { "description": "The name of the ACL.", "type": "string", "example": "PIN Pad - Cash Register" }, "protocols": { "type": "array", "items": { "description": "Array of allowed communication protocols between configured LANs. If no protocols are provided, all protocols are allowed.", "enum": [ "tcp", "udp", "icmp" ], "type": "string" } }, "unidirectional": { "$ref": "#/components/schemas/magic_unidirectional" } } }, "magic_acl-port-range": { "description": "A valid port range value.", "type": "string", "example": "8080-9000" }, "magic_acl-subnet": { "oneOf": [ { "$ref": "#/components/schemas/magic_ip-address" }, { "$ref": "#/components/schemas/magic_cidr" } ] }, "magic_acl_deleted_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_acl" } }, "type": "object" } ] }, "magic_acl_modified_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_acl" } }, "type": "object" } ] }, "magic_acl_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_acl" } }, "type": "object" } ] }, "magic_acl_update_request": { "type": "object", "properties": { "description": { "description": "Description for the ACL.", "type": "string", "example": "Allows local traffic between PIN pads and cash register." }, "forward_locally": { "$ref": "#/components/schemas/magic_forward_locally" }, "lan_1": { "$ref": "#/components/schemas/magic_lan-acl-configuration" }, "lan_2": { "$ref": "#/components/schemas/magic_lan-acl-configuration" }, "name": { "description": "The name of the ACL.", "type": "string", "example": "PIN Pad - Cash Register" }, "protocols": { "type": "array", "items": { "description": "Array of allowed communication protocols between configured LANs. If no protocols are provided, all protocols are allowed.", "enum": [ "tcp", "udp", "icmp" ], "type": "string" } }, "unidirectional": { "$ref": "#/components/schemas/magic_unidirectional" } } }, "magic_acls_add_single_request": { "description": "Bidirectional ACL policy for local network traffic within a site.", "type": "object", "properties": { "description": { "description": "Description for the ACL.", "type": "string", "example": "Allows local traffic between PIN pads and cash register." }, "forward_locally": { "$ref": "#/components/schemas/magic_forward_locally" }, "lan_1": { "$ref": "#/components/schemas/magic_lan-acl-configuration" }, "lan_2": { "$ref": "#/components/schemas/magic_lan-acl-configuration" }, "name": { "description": "The name of the ACL.", "type": "string", "example": "PIN Pad - Cash Register" }, "protocols": { "type": "array", "items": { "description": "Array of allowed communication protocols between configured LANs. If no protocols are provided, all protocols are allowed.", "enum": [ "tcp", "udp", "icmp" ], "type": "string" } }, "unidirectional": { "$ref": "#/components/schemas/magic_unidirectional" } }, "required": [ "name", "lan_1", "lan_2" ] }, "magic_acls_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/magic_acl" } } }, "type": "object" } ] }, "magic_allow_null_cipher": { "description": "When `true`, the tunnel can use a null-cipher (`ENCR_NULL`) in the ESP tunnel (Phase 2).", "type": "boolean", "example": true }, "magic_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/magic_messages" }, "messages": { "$ref": "#/components/schemas/magic_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": { "type": "object" }, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "magic_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/magic_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/magic_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "magic_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/magic_api-response-common" }, { "properties": { "result": { "anyOf": [ { "nullable": true, "type": "object" }, { "nullable": true, "type": "string" } ] } }, "type": "object" } ] }, "magic_app": { "description": "Collection of Hostnames and/or IP Subnets to associate with traffic decisions.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/magic_account_app" }, { "$ref": "#/components/schemas/magic_managed_app" } ] }, "magic_app_add_single_request": { "type": "object", "properties": { "hostnames": { "$ref": "#/components/schemas/magic_app_hostnames" }, "ip_subnets": { "$ref": "#/components/schemas/magic_app_subnets" }, "name": { "$ref": "#/components/schemas/magic_app_name" }, "source_subnets": { "$ref": "#/components/schemas/magic_app_source_subnets" }, "type": { "$ref": "#/components/schemas/magic_app_type" } }, "anyOf": [ { "required": [ "hostnames" ], "title": "Hostnames", "type": "object" }, { "required": [ "ip_subnets" ], "title": "Subnets", "type": "object" }, { "required": [ "source_subnets" ], "title": "Source Subnets", "type": "object" } ], "required": [ "name", "type" ] }, "magic_app_breakout": { "description": "Whether to breakout traffic to the app's endpoints directly. Null preserves default behavior.", "type": "boolean", "example": true }, "magic_app_breakout_preferred_wans": { "description": "WAN interfaces to prefer over default WANs, highest-priority first. Can only be specified for breakout rules (breakout must be true).", "type": "array", "items": { "$ref": "#/components/schemas/magic_identifier" } }, "magic_app_config": { "description": "Traffic decision configuration for an app.", "type": "object", "allOf": [ { "properties": { "breakout": { "$ref": "#/components/schemas/magic_app_breakout" }, "id": { "$ref": "#/components/schemas/magic_identifier" }, "preferred_wans": { "$ref": "#/components/schemas/magic_app_breakout_preferred_wans" }, "priority": { "$ref": "#/components/schemas/magic_app_priority" }, "site_id": { "$ref": "#/components/schemas/magic_identifier" } }, "required": [ "id", "site_id" ], "type": "object" }, { "oneOf": [ { "properties": { "account_app_id": { "$ref": "#/components/schemas/magic_account_app_id" } }, "required": [ "account_app_id" ], "title": "Account App", "type": "object" }, { "properties": { "managed_app_id": { "$ref": "#/components/schemas/magic_managed_app_id" } }, "required": [ "managed_app_id" ], "title": "Managed App", "type": "object" } ] } ] }, "magic_app_config_add_single_request": { "type": "object", "allOf": [ { "oneOf": [ { "properties": { "account_app_id": { "$ref": "#/components/schemas/magic_account_app_id" } }, "required": [ "account_app_id" ], "title": "Account App", "type": "object" }, { "properties": { "managed_app_id": { "$ref": "#/components/schemas/magic_managed_app_id" } }, "required": [ "managed_app_id" ], "title": "Managed App", "type": "object" } ] }, { "anyOf": [ { "required": [ "breakout" ], "title": "Breakout", "type": "object" }, { "required": [ "priority" ], "title": "Prioritize", "type": "object" } ] }, { "properties": { "breakout": { "$ref": "#/components/schemas/magic_app_breakout" }, "preferred_wans": { "$ref": "#/components/schemas/magic_app_breakout_preferred_wans" }, "priority": { "$ref": "#/components/schemas/magic_app_priority" } }, "type": "object" } ] }, "magic_app_config_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic_apps-response-object" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_app_config" } }, "type": "object" } ] }, "magic_app_config_update_request": { "type": "object", "properties": { "account_app_id": { "$ref": "#/components/schemas/magic_account_app_id" }, "breakout": { "$ref": "#/components/schemas/magic_app_breakout" }, "managed_app_id": { "$ref": "#/components/schemas/magic_managed_app_id" }, "preferred_wans": { "$ref": "#/components/schemas/magic_app_breakout_preferred_wans" }, "priority": { "$ref": "#/components/schemas/magic_app_priority" } } }, "magic_app_configs_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic_apps-response-object" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/magic_app_config" } } }, "type": "object" } ] }, "magic_app_hostnames": { "description": "FQDNs to associate with traffic decisions.", "type": "array", "items": { "example": "auth.cloudflare.com", "type": "string" } }, "magic_app_name": { "description": "Display name for the app.", "type": "string", "example": "Cloudflare Dashboard" }, "magic_app_priority": { "description": "Priority of traffic. 0 is default, anything greater is prioritized. (Currently only 0 and 1 are supported)", "type": "integer", "maximum": 1, "minimum": 0 }, "magic_app_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic_apps-response-object" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_account_app" } }, "type": "object" } ] }, "magic_app_source_subnets": { "description": "IPv4 CIDRs to associate with traffic decisions. (IPv6 CIDRs are currently unsupported)", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/magic_cidr" }, { "example": "1.1.1.1/32", "type": "string" } ] } }, "magic_app_subnets": { "description": "IPv4 CIDRs to associate with traffic decisions. (IPv6 CIDRs are currently unsupported)", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/magic_cidr" }, { "example": "1.1.1.1/32", "type": "string" } ] } }, "magic_app_type": { "description": "Category of the app.", "type": "string", "example": "Development" }, "magic_app_update_request": { "type": "object", "properties": { "hostnames": { "$ref": "#/components/schemas/magic_app_hostnames" }, "ip_subnets": { "$ref": "#/components/schemas/magic_app_subnets" }, "name": { "$ref": "#/components/schemas/magic_app_name" }, "source_subnets": { "$ref": "#/components/schemas/magic_app_source_subnets" }, "type": { "$ref": "#/components/schemas/magic_app_type" } }, "anyOf": [ { "required": [ "name" ], "title": "Update App Name", "type": "object" }, { "required": [ "type" ], "title": "Update App Type", "type": "object" }, { "required": [ "hostnames" ], "title": "Update App Hostnames", "type": "object" }, { "required": [ "ip_subnets" ], "title": "Update App Subnets", "type": "object" }, { "required": [ "source_subnets" ], "title": "Update App Source Subnets", "type": "object" } ] }, "magic_apps-response-array": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/magic_messages" }, "messages": { "$ref": "#/components/schemas/magic_messages" }, "result": { "type": "array", "items": { "type": "object" }, "nullable": true }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "magic_apps-response-object": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/magic_messages" }, "messages": { "$ref": "#/components/schemas/magic_messages" }, "result": { "type": "object", "nullable": true }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "magic_apps_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic_apps-response-array" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/magic_app" } } }, "type": "object" } ] }, "magic_automatic_return_routing": { "description": "True if automatic stateful return routing should be enabled for a tunnel, false otherwise. Requires the `coupler_integration` account flag to be enabled; requests setting this to `true` without that flag will be rejected.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "magic_bgp_config": { "type": "object", "properties": { "customer_asn": { "description": "ASN used on the customer end of the BGP session", "type": "integer", "format": "int32", "minimum": 0 }, "export_filter_id": { "description": "ID of the BGP filter profile applied to routes advertised to the customer.", "type": "string", "example": "a1b2c3d4e5f647890a1b2c3d4e5f6789" }, "extra_prefixes": { "description": "Prefixes in this list will be advertised to the customer device, in addition to the routes in the Magic routing table.", "type": "array", "items": { "format": "cidr", "type": "string" } }, "import_filter_id": { "description": "ID of the BGP filter profile applied to routes received from the customer.", "type": "string", "example": "a1b2c3d4e5f647890a1b2c3d4e5f6789" }, "md5_key": { "description": "MD5 key to use for session authentication.\n\nNote that *this is not a security measure*. MD5 is not a valid security mechanism, and the\nkey is not treated as a secret value. This is *only* supported for preventing\nmisconfiguration, not for defending against malicious attacks.\n\nThe MD5 key, if set, must be of non-zero length and consist only of the following types of\ncharacter:\n\n* ASCII alphanumerics: `[a-zA-Z0-9]`\n* Special characters in the set `'!@#$%^&*()+[]{}<>/.,;:_-~`= \\|`\n\nIn other words, MD5 keys may contain any printable ASCII character aside from newline (0x0A),\nquotation mark (`\"`), vertical tab (0x0B), carriage return (0x0D), tab (0x09), form feed\n(0x0C), and the question mark (`?`). Requests specifying an MD5 key with one or more of\nthese disallowed characters will be rejected.", "type": "string" } }, "required": [ "customer_asn" ] }, "magic_bgp_filter_match_action": { "description": "Action to take when a route matches one of the targets in this profile", "type": "string", "example": "allow", "enum": [ "allow", "deny" ] }, "magic_bgp_filter_profile": { "type": "object", "properties": { "created_on": { "type": "string", "format": "date-time", "readOnly": true }, "description": { "description": "Description of the filter profile", "type": "string", "example": "Allowed corporate subnets from on-premises", "default": "", "maxLength": 1024 }, "id": { "$ref": "#/components/schemas/magic_schemas-identifier" }, "match_action": { "$ref": "#/components/schemas/magic_bgp_filter_match_action" }, "modified_on": { "type": "string", "format": "date-time", "readOnly": true }, "name": { "description": "Friendly name for the filter profile", "type": "string", "example": "Allowed On-Prem Imports", "maxLength": 255, "minLength": 1 }, "targets": { "description": "List of CIDR prefixes. Each entry may carry an optional suffix that specifies which prefix lengths to match relative to the prefix length N: '{X,Y}' matches prefix lengths in the inclusive range [X, Y] where N <= X <= Y <= max (max is 32 for IPv4, 128 for IPv6), '{X}' matches exactly length X (equivalent to {X,X}), '+' is shorthand for {N, max} (the prefix and all more-specific subnets, including at length N itself; valid even when N is the maximum length). Omit the suffix to match the prefix exactly at length N.", "type": "array", "items": { "description": "CIDR notation prefix with optional + or {X,Y} suffix", "example": "10.0.0.0/8{8,32}", "type": "string" }, "maxItems": 1000 } }, "required": [ "id", "name", "description", "match_action", "targets" ] }, "magic_bgp_redistribute_sources": { "description": "Per-source toggles controlling which route sources are redistributed into BGP. Each property enables redistribution for one route source.", "type": "object", "properties": { "static:wan": { "description": "Redistribute static WAN routes into BGP", "type": "boolean" } }, "required": [ "static:wan" ] }, "magic_bgp_settings": { "type": "object", "properties": { "cloudflare_asn": { "description": "Route advertisements from Cloudflare to ramps in this account will use this ASN.", "type": "integer", "format": "uint32", "example": 13335, "minimum": 1 }, "modified_on": { "type": "string", "format": "date-time" }, "redistribute": { "$ref": "#/components/schemas/magic_bgp_redistribute_sources" } }, "required": [ "cloudflare_asn", "redistribute" ] }, "magic_bgp_status_with_state": { "type": "object", "properties": { "bgp_state": { "type": "string" }, "cf_speaker_ip": { "type": "string", "format": "ipv4" }, "cf_speaker_port": { "type": "integer", "maximum": 65535, "minimum": 1 }, "customer_speaker_ip": { "type": "string", "format": "ipv4" }, "customer_speaker_port": { "type": "integer", "maximum": 65535, "minimum": 1 }, "state": { "type": "string", "enum": [ "BGP_DOWN", "BGP_UP", "BGP_ESTABLISHING" ] }, "tcp_established": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "state", "tcp_established", "updated_at" ] }, "magic_bond_id": { "type": "integer", "example": 2 }, "magic_cf1_site": { "type": "object", "properties": { "created_on": { "type": "string", "format": "date-time", "readOnly": true }, "description": { "description": "A human-provided description of the CF1 Site.", "type": "string", "example": "Launch Pad 34" }, "id": { "allOf": [ { "$ref": "#/components/schemas/magic_identifier" } ], "readOnly": true }, "location": { "$ref": "#/components/schemas/magic_cf1_site_location" }, "modified_on": { "type": "string", "format": "date-time", "readOnly": true }, "name": { "description": "A human-provided name describing the CF1 Site that should be unique within the account.", "type": "string", "example": "Pad 34" } }, "required": [ "name" ] }, "magic_cf1_site_location": { "type": "object", "properties": { "lat": { "description": "Latitude of the CF1 Site.", "type": "number", "format": "float", "example": 28.521339842093845 }, "long": { "description": "Longitude of the CF1 Site.", "type": "number", "format": "float", "example": -80.56092644815843 }, "name": { "description": "Name of nearest town, city, or village.", "type": "string", "example": "Cape Canaveral" } } }, "magic_cf1_site_managed_ramp": { "type": "object", "properties": { "managed_by": { "description": "URL reference to the source network resource that this ramp is managed by.", "type": "string", "readOnly": true } } }, "magic_cf1_site_ramp": { "type": "object", "properties": { "created_on": { "type": "string", "format": "date-time", "readOnly": true }, "description": { "description": "A human-provided description of the ramp.", "type": "string", "example": "Primary CF GRE tunnel" }, "gre": { "$ref": "#/components/schemas/magic_cf1_site_managed_ramp" }, "gre_interconnect": { "$ref": "#/components/schemas/magic_cf1_site_managed_ramp" }, "id": { "allOf": [ { "$ref": "#/components/schemas/magic_identifier" } ], "readOnly": true }, "ipsec": { "$ref": "#/components/schemas/magic_cf1_site_managed_ramp" }, "mconn": { "$ref": "#/components/schemas/magic_cf1_site_managed_ramp" }, "modified_on": { "type": "string", "format": "date-time", "readOnly": true }, "mpls_interconnect": { "$ref": "#/components/schemas/magic_cf1_site_managed_ramp" }, "name": { "description": "A human-provided name describing the ramp that should be unique within the CF1 Site.", "type": "string", "example": "primary_gre_ramp" }, "type": { "allOf": [ { "$ref": "#/components/schemas/magic_cf1_site_ramp_type" } ], "readOnly": true } }, "oneOf": [ { "required": [ "gre" ], "type": "object" }, { "required": [ "ipsec" ], "type": "object" }, { "required": [ "gre_interconnect" ], "type": "object" }, { "required": [ "mpls_interconnect" ], "type": "object" }, { "required": [ "mconn" ], "type": "object" } ], "required": [ "id", "name", "type", "created_on", "modified_on" ] }, "magic_cf1_site_ramp_body": { "type": "object", "properties": { "source_ramp_id": { "description": "Identifier of the source network resource to associate as a ramp.", "allOf": [ { "$ref": "#/components/schemas/magic_identifier" } ] }, "type": { "$ref": "#/components/schemas/magic_cf1_site_ramp_type" } }, "required": [ "source_ramp_id", "type" ] }, "magic_cf1_site_ramp_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_cf1_site_ramp" } }, "type": "object" } ] }, "magic_cf1_site_ramp_type": { "description": "The type of network connection (ramp) linking a CF1 Site to Cloudflare's network.", "type": "string", "enum": [ "gre", "gre_interconnect", "mpls_interconnect", "mconn", "ipsec" ] }, "magic_cf1_site_ramps_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/magic_cf1_site_ramp" } } }, "type": "object" } ] }, "magic_cf1_site_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_cf1_site" } }, "type": "object" } ] }, "magic_cf1_site_update": { "description": "Partial update payload for a CF1 Site. All properties are optional; only fields supplied in the request body are modified.", "type": "object", "properties": { "description": { "description": "A human-provided description of the CF1 Site.", "type": "string", "example": "Launch Pad 34" }, "location": { "$ref": "#/components/schemas/magic_cf1_site_location" }, "name": { "description": "A human-provided name describing the CF1 Site that should be unique within the account.", "type": "string", "example": "Pad 34" } } }, "magic_cf1_sites_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/magic_cf1_site" } } }, "type": "object" } ] }, "magic_cidr": { "description": "A valid CIDR notation representing an IP range.", "type": "string", "example": "192.0.2.0/24" }, "magic_cloudflare_gre_endpoint": { "description": "The IP address assigned to the Cloudflare side of the GRE tunnel.", "type": "string", "example": "203.0.113.1", "x-auditable": true }, "magic_cloudflare_ipsec_endpoint": { "description": "The IP address assigned to the Cloudflare side of the IPsec tunnel.", "type": "string", "example": "203.0.113.1" }, "magic_colo_name": { "description": "Scope colo name.", "type": "string", "example": "den01", "x-auditable": true }, "magic_colo_names": { "description": "List of colo names for the ECMP scope.", "type": "array", "items": { "$ref": "#/components/schemas/magic_colo_name" } }, "magic_colo_region": { "description": "Scope colo region.", "type": "string", "example": "APAC", "x-auditable": true }, "magic_colo_regions": { "description": "List of colo regions for the ECMP scope.", "type": "array", "items": { "$ref": "#/components/schemas/magic_colo_region" }, "x-auditable": true }, "magic_components-schemas-description": { "description": "An optional description forthe IPsec tunnel.", "type": "string", "example": "Tunnel for ISP X" }, "magic_components-schemas-modified_tunnels_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "modified": { "type": "boolean", "example": true }, "modified_interconnects": { "type": "array", "items": { "$ref": "#/components/schemas/magic_interconnect" } } } } }, "type": "object" } ] }, "magic_components-schemas-name": { "description": "The name of the interconnect. The name cannot share a name with other tunnels.", "type": "string", "example": "pni_ord" }, "magic_components-schemas-tunnel_modified_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "modified": { "type": "boolean", "example": true }, "modified_interconnect": { "$ref": "#/components/schemas/magic_interconnect" } } } }, "type": "object" } ] }, "magic_components-schemas-tunnel_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "interconnect": { "$ref": "#/components/schemas/magic_interconnect" } } } }, "type": "object" } ] }, "magic_components-schemas-tunnels_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "interconnects": { "type": "array", "items": { "$ref": "#/components/schemas/magic_interconnect" } } } } }, "type": "object" } ] }, "magic_connector-id": { "description": "Magic Connector identifier tag.", "type": "string", "example": "ac60d3d0435248289d446cedd870bcf4", "x-auditable": true }, "magic_create_bgp_filter_profile_request": { "type": "object", "properties": { "description": { "description": "Description of the filter profile", "type": "string", "example": "Allowed corporate subnets from on-premises", "default": "", "maxLength": 1024 }, "match_action": { "$ref": "#/components/schemas/magic_bgp_filter_match_action" }, "name": { "description": "Friendly name for the filter profile", "type": "string", "example": "Allowed On-Prem Imports", "maxLength": 255, "minLength": 1 }, "targets": { "description": "List of CIDR prefixes. Each entry may carry an optional suffix that specifies which prefix lengths to match relative to the prefix length N: '{X,Y}' matches prefix lengths in the inclusive range [X, Y] where N <= X <= Y <= max (max is 32 for IPv4, 128 for IPv6), '{X}' matches exactly length X (equivalent to {X,X}), '+' is shorthand for {N, max} (the prefix and all more-specific subnets, including at length N itself; valid even when N is the maximum length). Omit the suffix to match the prefix exactly at length N.", "type": "array", "items": { "description": "CIDR notation prefix with optional + or {X,Y} suffix", "example": "10.0.0.0/8{8,32}", "type": "string" }, "maxItems": 1000 } }, "required": [ "name", "match_action", "targets" ] }, "magic_create_gre_tunnel_request": { "type": "object", "properties": { "automatic_return_routing": { "$ref": "#/components/schemas/magic_automatic_return_routing" }, "bgp": { "$ref": "#/components/schemas/magic_bgp_config" }, "cloudflare_gre_endpoint": { "$ref": "#/components/schemas/magic_cloudflare_gre_endpoint" }, "customer_gre_endpoint": { "$ref": "#/components/schemas/magic_customer_gre_endpoint" }, "description": { "$ref": "#/components/schemas/magic_schemas-description" }, "health_check": { "$ref": "#/components/schemas/magic_tunnel_health_check" }, "interface_address": { "$ref": "#/components/schemas/magic_interface_address" }, "interface_address6": { "$ref": "#/components/schemas/magic_interface_address6" }, "mtu": { "$ref": "#/components/schemas/magic_mtu" }, "name": { "$ref": "#/components/schemas/magic_gre_tunnel_name" }, "ttl": { "$ref": "#/components/schemas/magic_ttl" } }, "required": [ "name", "customer_gre_endpoint", "cloudflare_gre_endpoint", "interface_address" ] }, "magic_create_gre_tunnel_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_gre-tunnel" } }, "type": "object" } ] }, "magic_create_redundancy_group_request": { "type": "object", "properties": { "description": { "description": "Optional description", "type": "string", "default": "", "maxLength": 1024 }, "members": { "description": "Tunnels to add to the group", "type": "array", "items": { "$ref": "#/components/schemas/magic_redundancy_member_request" }, "default": [] }, "name": { "description": "Human-readable name for the redundancy group", "type": "string", "example": "primary-group", "maxLength": 255, "minLength": 1 } }, "required": [ "name" ] }, "magic_create_route_request": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/magic_description" }, "nexthop": { "$ref": "#/components/schemas/magic_nexthop" }, "prefix": { "$ref": "#/components/schemas/magic_prefix" }, "priority": { "$ref": "#/components/schemas/magic_priority" }, "scope": { "$ref": "#/components/schemas/magic_scope" }, "weight": { "$ref": "#/components/schemas/magic_weight" } }, "required": [ "prefix", "nexthop", "priority" ] }, "magic_create_route_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_route" } }, "type": "object" } ] }, "magic_created_on": { "description": "When the route was created.", "type": "string", "format": "date-time", "example": "2017-06-14T00:00:00Z", "readOnly": true, "x-auditable": true }, "magic_custom_remote_identities": { "type": "object", "properties": { "fqdn_id": { "description": "A custom IKE ID of type FQDN that may be used to identity the IPsec tunnel. The\ngenerated IKE IDs can still be used even if this custom value is specified.\n\nMust be of the form `..custom.ipsec.cloudflare.com`.\n\nThis custom ID does not need to be unique. Two IPsec tunnels may have the same custom\nfqdn_id. However, if another IPsec tunnel has the same value then the two tunnels\ncannot have the same cloudflare_endpoint.", "type": "string" } } }, "magic_customer_gre_endpoint": { "description": "The IP address assigned to the customer side of the GRE tunnel.", "type": "string", "example": "203.0.113.1", "x-auditable": true }, "magic_customer_ipsec_endpoint": { "description": "The IP address assigned to the customer side of the IPsec tunnel. Not required, but must be set for proactive traceroutes to work.", "type": "string", "example": "203.0.113.1" }, "magic_delete_redundancy_group_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "deleted_redundancy_group": { "$ref": "#/components/schemas/magic_redundancy_group" } }, "required": [ "deleted", "deleted_redundancy_group" ] } }, "type": "object" } ] }, "magic_description": { "description": "An optional human provided description of the static route.", "type": "string", "example": "New route for new prefix 203.0.113.1", "x-auditable": true }, "magic_dhcp_option": { "description": "A custom DHCP option to include in DHCP responses.", "type": "object", "properties": { "code": { "description": "DHCP option number (1-254). Options 0 and 255 are reserved by RFC 2132. Options 3, 6, and 51 are not allowed because they conflict with connector-managed configuration.", "type": "integer", "maximum": 254, "minimum": 1 }, "type": { "description": "The type of the option value. text: a string (max 255 bytes). hex: colon-separated hex bytes (e.g. \"01:04:aa:bb:cc\", max 255 bytes). ip: an IPv4 address (e.g. \"10.20.30.40\"). byte: an unsigned integer 0-255 (1 byte). short: an unsigned integer 0-65535 (2 bytes). integer: an unsigned integer 0-4294967295 (4 bytes).\n", "type": "string", "enum": [ "text", "hex", "ip", "byte", "short", "integer" ] }, "value": { "description": "The option value, interpreted according to the type field.", "type": "string" } }, "example": { "code": 66, "type": "ip", "value": "10.20.30.40" }, "required": [ "code", "type", "value" ] }, "magic_forward_locally": { "description": "The desired forwarding action for this ACL policy. If set to \"false\", the policy will forward traffic to Cloudflare. If set to \"true\", the policy will forward traffic locally on the Magic Connector. If not included in request, will default to false.", "type": "boolean" }, "magic_gre": { "description": "The configuration specific to GRE interconnects. Omitted in responses for version 1.5 interconnects.", "type": "object", "properties": { "cloudflare_endpoint": { "description": "The IP address assigned to the Cloudflare side of the GRE tunnel created as part of the Interconnect.", "type": "string", "example": "203.0.113.1" } } }, "magic_gre-tunnel": { "type": "object", "properties": { "automatic_return_routing": { "$ref": "#/components/schemas/magic_automatic_return_routing" }, "bgp": { "$ref": "#/components/schemas/magic_bgp_config" }, "bgp_status": { "$ref": "#/components/schemas/magic_bgp_status_with_state" }, "cloudflare_gre_endpoint": { "$ref": "#/components/schemas/magic_cloudflare_gre_endpoint" }, "created_on": { "$ref": "#/components/schemas/magic_schemas-created_on" }, "customer_gre_endpoint": { "$ref": "#/components/schemas/magic_customer_gre_endpoint" }, "description": { "$ref": "#/components/schemas/magic_schemas-description" }, "health_check": { "$ref": "#/components/schemas/magic_tunnel_health_check" }, "id": { "$ref": "#/components/schemas/magic_schemas-identifier" }, "interface_address": { "$ref": "#/components/schemas/magic_interface_address" }, "interface_address6": { "$ref": "#/components/schemas/magic_interface_address6" }, "modified_on": { "$ref": "#/components/schemas/magic_schemas-modified_on" }, "mtu": { "$ref": "#/components/schemas/magic_mtu" }, "name": { "$ref": "#/components/schemas/magic_gre_tunnel_name" }, "ttl": { "$ref": "#/components/schemas/magic_ttl" } }, "required": [ "id", "name", "customer_gre_endpoint", "cloudflare_gre_endpoint", "interface_address" ] }, "magic_gre_tunnel_add_single_request": { "type": "object", "properties": { "automatic_return_routing": { "$ref": "#/components/schemas/magic_automatic_return_routing" }, "cloudflare_gre_endpoint": { "$ref": "#/components/schemas/magic_cloudflare_gre_endpoint" }, "customer_gre_endpoint": { "$ref": "#/components/schemas/magic_customer_gre_endpoint" }, "description": { "$ref": "#/components/schemas/magic_schemas-description" }, "health_check": { "$ref": "#/components/schemas/magic_tunnel_health_check" }, "interface_address": { "$ref": "#/components/schemas/magic_interface_address" }, "interface_address6": { "$ref": "#/components/schemas/magic_interface_address6" }, "mtu": { "$ref": "#/components/schemas/magic_mtu" }, "name": { "$ref": "#/components/schemas/magic_gre_tunnel_name" }, "ttl": { "$ref": "#/components/schemas/magic_ttl" } }, "required": [ "name", "customer_gre_endpoint", "cloudflare_gre_endpoint", "interface_address" ] }, "magic_gre_tunnel_name": { "description": "The name of the tunnel. The name cannot contain spaces or special characters, must be 15 characters or less, and cannot share a name with another GRE tunnel.", "type": "string", "example": "GRE_1", "x-auditable": true }, "magic_gre_tunnel_update_request": { "allOf": [ { "$ref": "#/components/schemas/magic_gre_tunnel_add_single_request" } ] }, "magic_health_check_base": { "type": "object", "properties": { "enabled": { "description": "Determines whether to run healthchecks for a tunnel.", "type": "boolean", "example": true, "default": true, "x-auditable": true }, "rate": { "description": "How frequent the health check is run. The default value is `mid`.", "type": "string", "example": "low", "default": "mid", "enum": [ "low", "mid", "high" ], "x-auditable": true }, "target": { "description": "The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to `customer_gre_endpoint address`. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target. Must be in object form if the x-magic-new-hc-target header is set to true and string form if x-magic-new-hc-target is absent or set to false.", "oneOf": [ { "$ref": "#/components/schemas/magic_health_check_target" }, { "type": "string" } ] }, "type": { "description": "The type of healthcheck to run, reply or request. The default value is `reply`.", "type": "string", "example": "request", "default": "reply", "enum": [ "reply", "request" ], "x-auditable": true } } }, "magic_health_check_target": { "description": "The destination address in a request type health check. After the healthcheck is decapsulated at the customer end of the tunnel, the ICMP echo will be forwarded to this address. This field defaults to `customer_gre_endpoint address`. This field is ignored for bidirectional healthchecks as the interface_address (not assigned to the Cloudflare side of the tunnel) is used as the target.", "type": "object", "properties": { "effective": { "description": "The effective health check target. If 'saved' is empty, then this field will be populated with the calculated default value on GET requests. Ignored in POST, PUT, and PATCH requests.", "type": "string", "example": "203.0.113.1", "readOnly": true, "x-auditable": true }, "saved": { "description": "The saved health check target. Setting the value to the empty string indicates that the calculated default value will be used.", "type": "string", "example": "203.0.113.1", "x-auditable": true } } }, "magic_identifier": { "description": "Identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "magic_interconnect": { "type": "object", "properties": { "automatic_return_routing": { "$ref": "#/components/schemas/magic_automatic_return_routing" }, "bgp": { "$ref": "#/components/schemas/magic_interconnect_bgp_config" }, "colo_name": { "$ref": "#/components/schemas/magic_components-schemas-name" }, "created_on": { "$ref": "#/components/schemas/magic_schemas-created_on" }, "description": { "$ref": "#/components/schemas/magic_interconnect_components-schemas-description" }, "gre": { "allOf": [ { "$ref": "#/components/schemas/magic_gre" }, { "description": "Omitted in responses for version 1.5 interconnects.", "type": "object" } ] }, "health_check": { "$ref": "#/components/schemas/magic_interconnect_health_check" }, "id": { "$ref": "#/components/schemas/magic_schemas-identifier" }, "interface_address": { "$ref": "#/components/schemas/magic_interface_address_interconnect" }, "interface_address6": { "$ref": "#/components/schemas/magic_interface_address6" }, "modified_on": { "$ref": "#/components/schemas/magic_schemas-modified_on" }, "mtu": { "$ref": "#/components/schemas/magic_schemas-mtu" }, "name": { "$ref": "#/components/schemas/magic_components-schemas-name" }, "version": { "description": "Immutable interconnect version configured at creation time. One of:\n- \"1\"\n- \"1.5\"\n- \"2\"\n", "type": "string", "example": "1.5" }, "virtual_port_reservation_id": { "allOf": [ { "$ref": "#/components/schemas/magic_schemas-identifier" }, { "description": "An identifier that correlates this interconnect with the corresponding V2 CNI interconnect resource.", "readOnly": true, "type": "string" } ] } } }, "magic_interconnect_bgp_config": { "type": "object", "properties": { "as_no": { "description": "Deprecated. Use customer_asn.", "type": "integer", "format": "int32", "deprecated": true }, "cloudflare_endpoint": { "description": "Read-only for v1.5; derived from interface_address.", "type": "string", "format": "ipv4", "deprecated": true }, "customer_asn": { "description": "ASN used on the customer end of the BGP session.", "type": "integer", "format": "int32" }, "customer_endpoint": { "description": "Read-only for v1.5; derived from interface_address.", "type": "string", "format": "ipv4", "deprecated": true }, "export_filter_id": { "description": "ID of the BGP filter profile applied to routes advertised to the customer.", "type": "string", "example": "a1b2c3d4e5f647890a1b2c3d4e5f6789" }, "extra_prefixes": { "description": "Prefixes in this list will be advertised to the customer device, in addition to the routes in the Magic routing table.", "type": "array", "items": { "format": "cidr", "type": "string" } }, "import_filter_id": { "description": "ID of the BGP filter profile applied to routes received from the customer.", "type": "string", "example": "a1b2c3d4e5f647890a1b2c3d4e5f6789" }, "md5_key": { "description": "MD5 key to use for session authentication.\n\nNote that *this is not a security measure*. MD5 is not a valid security mechanism, and the\nkey is not treated as a secret value. This is *only* supported for preventing\nmisconfiguration, not for defending against malicious attacks.\n\nThe MD5 key, if set, must be of non-zero length and consist only of the following types of\ncharacter:\n\n* ASCII alphanumerics: `[a-zA-Z0-9]`\n* Special characters in the set `'!@#$%^&*()+[]{}<>/.,;:_-~`= \\|`\n\nIn other words, MD5 keys may contain any printable ASCII character aside from newline (0x0A),\nquotation mark (`\"`), vertical tab (0x0B), carriage return (0x0D), tab (0x09), form feed\n(0x0C), and the question mark (`?`). Requests specifying an MD5 key with one or more of\nthese disallowed characters will be rejected.", "type": "string" } } }, "magic_interconnect_components-schemas-description": { "description": "An optional description of the interconnect.", "type": "string", "example": "Tunnel for Interconnect to ORD" }, "magic_interconnect_health_check": { "allOf": [ { "$ref": "#/components/schemas/magic_health_check_base" }, { "properties": { "direction": { "description": "The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the interconnect and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the interconnect.", "type": "string", "example": "bidirectional", "default": "unidirectional", "enum": [ "unidirectional", "bidirectional" ] }, "source": { "description": "The source IPv4 address used for bidirectional health checks. Supported only for version 1.5 interconnects. It is required when `direction` is `bidirectional` and must be omitted (and is cleared) when `direction` is `unidirectional`. The address must be within RFC1918 space, the approved link-local range 169.254.240.0/20, or the Cloudflare reserved range 198.41.199.224/27.", "type": "string", "example": "198.41.199.225", "x-auditable": true } }, "type": "object" } ] }, "magic_interconnect_tunnel_update_request": { "type": "object", "properties": { "automatic_return_routing": { "$ref": "#/components/schemas/magic_automatic_return_routing" }, "bgp": { "$ref": "#/components/schemas/magic_interconnect_bgp_config" }, "description": { "$ref": "#/components/schemas/magic_interconnect_components-schemas-description" }, "gre": { "allOf": [ { "$ref": "#/components/schemas/magic_gre" }, { "description": "Not configurable for version 1.5 interconnects; supplying it returns an error.", "type": "object" } ] }, "health_check": { "$ref": "#/components/schemas/magic_interconnect_health_check" }, "interface_address": { "$ref": "#/components/schemas/magic_interface_address_interconnect" }, "interface_address6": { "$ref": "#/components/schemas/magic_interface_address6" }, "mtu": { "$ref": "#/components/schemas/magic_schemas-mtu" }, "name": { "$ref": "#/components/schemas/magic_components-schemas-name" } } }, "magic_interface_address": { "description": "A 31-bit prefix (/31 in CIDR notation) supporting two hosts, one for each side of the tunnel. Select the subnet from the following private IP space: 10.0.0.0–10.255.255.255, 172.16.0.0–172.31.255.255, 192.168.0.0–192.168.255.255.", "type": "string", "example": "192.0.2.0/31", "x-auditable": true }, "magic_interface_address6": { "description": "A 127 bit IPV6 prefix from within the virtual_subnet6 prefix space with the address being the first IP of the subnet and not same as the address of virtual_subnet6. Eg if virtual_subnet6 is 2606:54c1:7:0:a9fe:12d2::/127 , interface_address6 could be 2606:54c1:7:0:a9fe:12d2:1:200/127", "type": "string", "example": "2606:54c1:7:0:a9fe:12d2:1:200/127", "x-auditable": true }, "magic_interface_address_interconnect": { "description": "The IPv4 interface address for the interconnect. For MPLS Interconnects,\nuse a /30 or /31 prefix. For GRE Interconnects, a /30 or /31 prefix\nmay be used. Version 1.5 interconnects require a /31 prefix and may\nalso use a prefix from the account's authorized prefixes; otherwise,\nselect the subnet from RFC 1918 or the approved link-local ranges.\n", "type": "string", "example": "192.0.2.0/31", "x-auditable": true }, "magic_ip-address": { "description": "A valid IPv4 address.", "type": "string", "example": "192.0.2.1" }, "magic_ipsec-tunnel": { "type": "object", "properties": { "allow_null_cipher": { "$ref": "#/components/schemas/magic_allow_null_cipher" }, "automatic_return_routing": { "$ref": "#/components/schemas/magic_automatic_return_routing" }, "bgp": { "$ref": "#/components/schemas/magic_bgp_config" }, "bgp_status": { "$ref": "#/components/schemas/magic_bgp_status_with_state" }, "cloudflare_endpoint": { "$ref": "#/components/schemas/magic_cloudflare_ipsec_endpoint" }, "created_on": { "$ref": "#/components/schemas/magic_schemas-created_on" }, "custom_remote_identities": { "$ref": "#/components/schemas/magic_custom_remote_identities" }, "customer_endpoint": { "$ref": "#/components/schemas/magic_customer_ipsec_endpoint" }, "description": { "$ref": "#/components/schemas/magic_components-schemas-description" }, "health_check": { "$ref": "#/components/schemas/magic_tunnel_health_check" }, "id": { "$ref": "#/components/schemas/magic_schemas-identifier" }, "interface_address": { "$ref": "#/components/schemas/magic_interface_address" }, "interface_address6": { "$ref": "#/components/schemas/magic_interface_address6" }, "modified_on": { "$ref": "#/components/schemas/magic_schemas-modified_on" }, "name": { "$ref": "#/components/schemas/magic_ipsec_tunnel_name" }, "psk_metadata": { "$ref": "#/components/schemas/magic_psk_metadata" }, "replay_protection": { "$ref": "#/components/schemas/magic_replay_protection" } }, "required": [ "id", "name", "cloudflare_endpoint", "interface_address" ] }, "magic_ipsec_tunnel_add_request": { "allOf": [ { "$ref": "#/components/schemas/magic_ipsec_tunnel_add_single_request" } ] }, "magic_ipsec_tunnel_add_single_request": { "type": "object", "properties": { "automatic_return_routing": { "$ref": "#/components/schemas/magic_automatic_return_routing" }, "bgp": { "$ref": "#/components/schemas/magic_bgp_config" }, "cloudflare_endpoint": { "$ref": "#/components/schemas/magic_cloudflare_ipsec_endpoint" }, "custom_remote_identities": { "$ref": "#/components/schemas/magic_custom_remote_identities" }, "customer_endpoint": { "$ref": "#/components/schemas/magic_customer_ipsec_endpoint" }, "description": { "$ref": "#/components/schemas/magic_components-schemas-description" }, "health_check": { "$ref": "#/components/schemas/magic_tunnel_health_check" }, "interface_address": { "$ref": "#/components/schemas/magic_interface_address" }, "interface_address6": { "$ref": "#/components/schemas/magic_interface_address6" }, "name": { "$ref": "#/components/schemas/magic_ipsec_tunnel_name" }, "psk": { "$ref": "#/components/schemas/magic_psk" }, "replay_protection": { "$ref": "#/components/schemas/magic_replay_protection" } }, "required": [ "name", "cloudflare_endpoint", "interface_address" ] }, "magic_ipsec_tunnel_applied_psk": { "description": "A successfully applied PSK for an IPsec tunnel.", "type": "object", "properties": { "ipsec_id": { "description": "The IKE identifier used for this tunnel on the Cloudflare edge.", "type": "string", "example": "12345_abc123def4567890abcdef1234567890" }, "ipsec_tunnel_id": { "$ref": "#/components/schemas/magic_identifier" }, "psk": { "$ref": "#/components/schemas/magic_psk" }, "psk_metadata": { "$ref": "#/components/schemas/magic_psk_metadata" } }, "required": [ "ipsec_tunnel_id", "ipsec_id", "psk", "psk_metadata" ] }, "magic_ipsec_tunnel_name": { "description": "The name of the IPsec tunnel. The name cannot share a name with other tunnels.", "type": "string", "example": "IPsec_1" }, "magic_ipsec_tunnel_psk_entry": { "description": "A PSK entry for a specific IPsec tunnel.", "type": "object", "properties": { "id": { "description": "The ID of the IPsec tunnel.", "allOf": [ { "$ref": "#/components/schemas/magic_identifier" } ] }, "psk": { "$ref": "#/components/schemas/magic_psk" } }, "required": [ "id", "psk" ] }, "magic_ipsec_tunnels_psk_request": { "description": "Request body for setting PSKs for multiple IPsec tunnels.", "type": "object", "properties": { "psks": { "description": "List of tunnel ID and PSK pairs.", "type": "array", "items": { "$ref": "#/components/schemas/magic_ipsec_tunnel_psk_entry" } } }, "required": [ "psks" ] }, "magic_ipsec_tunnels_psk_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "successfully_applied_psks": { "description": "Map of tunnel IDs to successfully applied PSK details.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/magic_ipsec_tunnel_applied_psk" } }, "unapplied_psks": { "description": "Map of tunnel IDs to failure reasons for PSKs that could not be applied.", "type": "object", "additionalProperties": { "type": "string" } } } } }, "type": "object" } ] }, "magic_lan": { "type": "object", "properties": { "bond_id": { "$ref": "#/components/schemas/magic_bond_id" }, "ha_link": { "description": "mark true to use this LAN for HA probing. only works for site with HA turned on. only one LAN can be set as the ha_link.", "type": "boolean" }, "id": { "$ref": "#/components/schemas/magic_identifier" }, "is_breakout": { "description": "mark true to use this LAN for source-based breakout traffic", "type": "boolean" }, "is_prioritized": { "description": "mark true to use this LAN for source-based prioritized traffic", "type": "boolean" }, "name": { "type": "string" }, "nat": { "$ref": "#/components/schemas/magic_nat" }, "physport": { "$ref": "#/components/schemas/magic_port" }, "routed_subnets": { "type": "array", "items": { "$ref": "#/components/schemas/magic_routed_subnet" } }, "site_id": { "$ref": "#/components/schemas/magic_identifier" }, "static_addressing": { "$ref": "#/components/schemas/magic_lan_static_addressing" }, "vlan_tag": { "$ref": "#/components/schemas/magic_vlan_tag" } } }, "magic_lan-acl-configuration": { "type": "object", "properties": { "lan_id": { "description": "The identifier for the LAN you want to create an ACL policy with.", "type": "string" }, "lan_name": { "description": "The name of the LAN based on the provided lan_id.", "type": "string" }, "port_ranges": { "description": "Array of port ranges on the provided LAN that will be included in the ACL. If no ports or port rangess are provided, communication on any port on this LAN is allowed.", "type": "array", "items": { "$ref": "#/components/schemas/magic_acl-port-range" } }, "ports": { "description": "Array of ports on the provided LAN that will be included in the ACL. If no ports or port ranges are provided, communication on any port on this LAN is allowed.", "type": "array", "items": { "$ref": "#/components/schemas/magic_port" } }, "subnets": { "description": "Array of subnet IPs within the LAN that will be included in the ACL. If no subnets are provided, communication on any subnets on this LAN are allowed.", "type": "array", "items": { "$ref": "#/components/schemas/magic_acl-subnet" } } }, "required": [ "lan_id" ] }, "magic_lan_deleted_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_lan" } }, "type": "object" } ] }, "magic_lan_dhcp_relay": { "type": "object", "properties": { "server_addresses": { "description": "List of DHCP server IPs.", "type": "array", "items": { "$ref": "#/components/schemas/magic_ip-address" } } } }, "magic_lan_dhcp_server": { "type": "object", "properties": { "dhcp_options": { "description": "Optional list of custom DHCP options to include in DHCP responses. Only valid when DHCP server is enabled.", "type": "array", "items": { "$ref": "#/components/schemas/magic_dhcp_option" } }, "dhcp_pool_end": { "$ref": "#/components/schemas/magic_ip-address" }, "dhcp_pool_start": { "$ref": "#/components/schemas/magic_ip-address" }, "dns_server": { "allOf": [ { "$ref": "#/components/schemas/magic_ip-address" } ], "deprecated": true }, "dns_servers": { "type": "array", "items": { "$ref": "#/components/schemas/magic_ip-address" } }, "reservations": { "description": "Mapping of MAC addresses to IP addresses", "type": "object", "example": { "00:11:22:33:44:55": "192.0.2.100", "AA:BB:CC:DD:EE:FF": "192.168.1.101" }, "additionalProperties": { "description": "IP address associated with the MAC address", "type": "string" } } } }, "magic_lan_modified_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_lan" } }, "type": "object" } ] }, "magic_lan_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_lan" } }, "type": "object" } ] }, "magic_lan_static_addressing": { "description": "If the site is not configured in high availability mode, this configuration is optional (if omitted, use DHCP). However, if in high availability mode, static_address is required along with secondary and virtual address.", "type": "object", "properties": { "address": { "$ref": "#/components/schemas/magic_cidr" }, "dhcp_relay": { "$ref": "#/components/schemas/magic_lan_dhcp_relay" }, "dhcp_server": { "$ref": "#/components/schemas/magic_lan_dhcp_server" }, "secondary_address": { "$ref": "#/components/schemas/magic_cidr" }, "virtual_address": { "$ref": "#/components/schemas/magic_cidr" } }, "required": [ "address" ] }, "magic_lan_update_request": { "type": "object", "properties": { "bond_id": { "$ref": "#/components/schemas/magic_bond_id" }, "is_breakout": { "description": "mark true to use this LAN for source-based breakout traffic", "type": "boolean" }, "is_prioritized": { "description": "mark true to use this LAN for source-based prioritized traffic", "type": "boolean" }, "name": { "type": "string" }, "nat": { "$ref": "#/components/schemas/magic_nat" }, "physport": { "$ref": "#/components/schemas/magic_port" }, "routed_subnets": { "type": "array", "items": { "$ref": "#/components/schemas/magic_routed_subnet" } }, "static_addressing": { "$ref": "#/components/schemas/magic_lan_static_addressing" }, "vlan_tag": { "$ref": "#/components/schemas/magic_vlan_tag" } } }, "magic_lans_add_single_request": { "type": "object", "properties": { "bond_id": { "$ref": "#/components/schemas/magic_bond_id" }, "ha_link": { "description": "mark true to use this LAN for HA probing. only works for site with HA turned on. only one LAN can be set as the ha_link.", "type": "boolean" }, "is_breakout": { "description": "mark true to use this LAN for source-based breakout traffic", "type": "boolean" }, "is_prioritized": { "description": "mark true to use this LAN for source-based prioritized traffic", "type": "boolean" }, "name": { "type": "string" }, "nat": { "$ref": "#/components/schemas/magic_nat" }, "physport": { "$ref": "#/components/schemas/magic_port" }, "routed_subnets": { "type": "array", "items": { "$ref": "#/components/schemas/magic_routed_subnet" } }, "static_addressing": { "$ref": "#/components/schemas/magic_lan_static_addressing" }, "vlan_tag": { "$ref": "#/components/schemas/magic_vlan_tag" } } }, "magic_lans_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/magic_lan" } } }, "type": "object" } ] }, "magic_magic_bgp_filter_profile_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_bgp_filter_profile" } }, "type": "object" } ] }, "magic_magic_bgp_filter_profiles_list_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/magic_bgp_filter_profile" } } }, "type": "object" } ] }, "magic_magic_bgp_settings_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_bgp_settings" } }, "type": "object" } ] }, "magic_managed_app": { "description": "Managed app defined by Cloudflare.", "type": "object", "properties": { "hostnames": { "$ref": "#/components/schemas/magic_app_hostnames" }, "ip_subnets": { "$ref": "#/components/schemas/magic_app_subnets" }, "managed_app_id": { "$ref": "#/components/schemas/magic_managed_app_id" }, "name": { "$ref": "#/components/schemas/magic_app_name" }, "source_subnets": { "$ref": "#/components/schemas/magic_app_source_subnets" }, "type": { "$ref": "#/components/schemas/magic_app_type" } }, "required": [ "managed_app_id" ], "title": "Managed App" }, "magic_managed_app_id": { "description": "Managed app ID.", "type": "string", "example": "cloudflare" }, "magic_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "magic_modified_on": { "description": "When the route was last modified.", "type": "string", "format": "date-time", "example": "2017-06-14T05:20:00Z", "readOnly": true, "x-auditable": true }, "magic_modified_tunnels_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "modified": { "type": "boolean", "example": true }, "modified_gre_tunnels": { "type": "array", "items": { "$ref": "#/components/schemas/magic_gre-tunnel" } } } } }, "type": "object" } ] }, "magic_mtu": { "description": "Maximum Transmission Unit (MTU) in bytes for the GRE tunnel. The minimum value is 576.", "type": "integer", "default": 1476, "x-auditable": true }, "magic_multiple_route_delete_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true }, "deleted_routes": { "type": "array", "items": { "$ref": "#/components/schemas/magic_route" } } } } }, "type": "object" } ] }, "magic_multiple_route_modified_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "modified": { "type": "boolean", "example": true }, "modified_routes": { "type": "array", "items": { "$ref": "#/components/schemas/magic_route" } } } } }, "type": "object" } ] }, "magic_nat": { "type": "object", "properties": { "static_prefix": { "$ref": "#/components/schemas/magic_cidr" } } }, "magic_netflow_config": { "description": "NetFlow configuration for a site.", "type": "object", "properties": { "active_timeout": { "description": "Timeout in seconds for active flows (defaults to 30).", "type": "integer", "example": 30, "maximum": 5400, "minimum": 1 }, "collector_ip": { "description": "IPv4 address of the NetFlow collector.", "type": "string", "example": "162.159.65.1" }, "collector_port": { "description": "UDP port of the NetFlow collector (defaults to 2055).", "type": "integer", "example": 2055, "maximum": 65535, "minimum": 1 }, "inactive_timeout": { "description": "Timeout in seconds for inactive flows (defaults to 15).", "type": "integer", "example": 15, "maximum": 5400, "minimum": 1 }, "sampling_rate": { "description": "Sampling rate for NetFlow records (1 = every packet, 1000 = 1 in 1000 packets). Defaults to 1.", "type": "integer", "example": 100, "maximum": 10000, "minimum": 1 } }, "required": [ "collector_ip" ] }, "magic_netflow_config_request": { "type": "object", "properties": { "active_timeout": { "description": "Timeout in seconds for active flows.", "type": "integer", "example": 30, "maximum": 5400, "minimum": 1 }, "collector_ip": { "description": "IPv4 address of the NetFlow collector.", "type": "string", "example": "162.159.65.1" }, "collector_port": { "description": "UDP port of the NetFlow collector.", "type": "integer", "example": 2055, "maximum": 65535, "minimum": 1 }, "inactive_timeout": { "description": "Timeout in seconds for inactive flows.", "type": "integer", "example": 15, "maximum": 5400, "minimum": 1 }, "sampling_rate": { "description": "Sampling rate for NetFlow records (1 = every packet).", "type": "integer", "example": 100, "maximum": 10000, "minimum": 1 } } }, "magic_netflow_config_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_netflow_config" } }, "type": "object" } ] }, "magic_nexthop": { "description": "The next-hop IP Address for the static route.", "type": "string", "example": "203.0.113.1", "x-auditable": true }, "magic_port": { "type": "integer", "example": 1 }, "magic_prefix": { "description": "IP Prefix in Classless Inter-Domain Routing format.", "type": "string", "example": "192.0.2.0/24", "x-auditable": true }, "magic_priority": { "description": "Priority of the static route.", "type": "integer", "x-auditable": true }, "magic_psk": { "description": "A randomly generated or provided string for use in the IPsec tunnel.", "type": "string", "example": "O3bwKSjnaoCxDoUxjcq4Rk8ZKkezQUiy", "x-sensitive": true }, "magic_psk_generation_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "ipsec_tunnel_id": { "$ref": "#/components/schemas/magic_identifier" }, "psk": { "$ref": "#/components/schemas/magic_psk" }, "psk_metadata": { "$ref": "#/components/schemas/magic_psk_metadata" } } } }, "type": "object" } ] }, "magic_psk_metadata": { "description": "The PSK metadata that includes when the PSK was generated.", "type": "object", "properties": { "last_generated_on": { "$ref": "#/components/schemas/magic_schemas-modified_on" } } }, "magic_redundancy_group": { "type": "object", "properties": { "created_on": { "type": "string", "format": "date-time" }, "description": { "description": "Optional description", "type": "string", "example": "Primary tunnel redundancy group" }, "id": { "description": "Redundancy group identifier", "type": "string", "example": "a1b2c3d4e5f647890a1b2c3d4e5f6789" }, "modified_on": { "type": "string", "format": "date-time" }, "name": { "description": "Human-readable name", "type": "string", "example": "primary-group" } } }, "magic_redundancy_group_single_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_redundancy_group" } }, "type": "object" } ] }, "magic_redundancy_group_with_members": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/magic_redundancy_group" }, { "properties": { "member_data": { "type": "array", "items": { "$ref": "#/components/schemas/magic_redundancy_member_data" } } }, "type": "object" } ] }, "magic_redundancy_group_with_members_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_redundancy_group_with_members" } }, "type": "object" } ] }, "magic_redundancy_groups_collection_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "redundancy_groups": { "type": "array", "items": { "$ref": "#/components/schemas/magic_redundancy_group_with_members" } } } } }, "type": "object" } ] }, "magic_redundancy_member_data": { "type": "object", "properties": { "data": { "description": "Full tunnel object as returned by the corresponding endpoint", "type": "object" }, "type": { "description": "Tunnel type", "type": "string", "enum": [ "gre", "ipsec", "cni" ] } }, "required": [ "type", "data" ] }, "magic_redundancy_member_request": { "type": "object", "properties": { "id": { "description": "UUID of the tunnel or interconnect", "type": "string", "example": "a1b2c3d4e5f647890a1b2c3d4e5f6789", "maxLength": 36, "pattern": "^[a-fA-F0-9\\-]{32,36}$" }, "type": { "description": "Tunnel type: gre, ipsec, or cni", "type": "string", "enum": [ "gre", "ipsec", "cni" ] } }, "required": [ "id", "type" ] }, "magic_replay_protection": { "description": "If `true`, then IPsec replay protection will be supported in the Cloudflare-to-customer direction.", "type": "boolean", "example": false, "default": false }, "magic_route": { "type": "object", "properties": { "created_on": { "$ref": "#/components/schemas/magic_created_on" }, "description": { "$ref": "#/components/schemas/magic_description" }, "id": { "$ref": "#/components/schemas/magic_identifier" }, "modified_on": { "$ref": "#/components/schemas/magic_modified_on" }, "nexthop": { "$ref": "#/components/schemas/magic_nexthop" }, "prefix": { "$ref": "#/components/schemas/magic_prefix" }, "priority": { "$ref": "#/components/schemas/magic_priority" }, "scope": { "$ref": "#/components/schemas/magic_scope" }, "weight": { "$ref": "#/components/schemas/magic_weight" } }, "required": [ "id", "prefix", "nexthop", "priority" ] }, "magic_route_add_single_request": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/magic_description" }, "nexthop": { "$ref": "#/components/schemas/magic_nexthop" }, "prefix": { "$ref": "#/components/schemas/magic_prefix" }, "priority": { "$ref": "#/components/schemas/magic_priority" }, "scope": { "$ref": "#/components/schemas/magic_scope" }, "weight": { "$ref": "#/components/schemas/magic_weight" } }, "required": [ "prefix", "nexthop", "priority" ] }, "magic_route_delete_id": { "allOf": [ { "properties": { "id": { "$ref": "#/components/schemas/magic_identifier" } }, "required": [ "id" ], "type": "object" } ] }, "magic_route_delete_many_request": { "type": "object", "properties": { "routes": { "type": "array", "items": { "$ref": "#/components/schemas/magic_route_delete_id" } } }, "required": [ "routes" ] }, "magic_route_deleted_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true }, "deleted_route": { "$ref": "#/components/schemas/magic_route" } } } }, "type": "object" } ] }, "magic_route_modified_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "modified": { "type": "boolean", "example": true }, "modified_route": { "$ref": "#/components/schemas/magic_route" } } } }, "type": "object" } ] }, "magic_route_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "route": { "$ref": "#/components/schemas/magic_route" } } } }, "type": "object" } ] }, "magic_route_update_many_request": { "type": "object", "properties": { "routes": { "type": "array", "items": { "$ref": "#/components/schemas/magic_route_update_single_request" } } }, "required": [ "routes" ] }, "magic_route_update_request": { "allOf": [ { "$ref": "#/components/schemas/magic_route_add_single_request" } ] }, "magic_route_update_single_request": { "allOf": [ { "properties": { "id": { "$ref": "#/components/schemas/magic_identifier" } }, "required": [ "id" ], "type": "object" }, { "$ref": "#/components/schemas/magic_route_add_single_request" } ] }, "magic_routed_subnet": { "type": "object", "properties": { "nat": { "$ref": "#/components/schemas/magic_nat" }, "next_hop": { "$ref": "#/components/schemas/magic_ip-address" }, "prefix": { "$ref": "#/components/schemas/magic_cidr" } }, "required": [ "prefix", "next_hop" ] }, "magic_routes_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "routes": { "type": "array", "items": { "$ref": "#/components/schemas/magic_route" } } } } }, "type": "object" } ] }, "magic_schemas-create_ipsec_tunnel_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_ipsec-tunnel" } }, "type": "object" } ] }, "magic_schemas-created_on": { "description": "The date and time the tunnel was created.", "type": "string", "format": "date-time", "example": "2017-06-14T00:00:00Z", "readOnly": true, "x-auditable": true }, "magic_schemas-description": { "description": "An optional description of the GRE tunnel.", "type": "string", "example": "Tunnel for ISP X", "x-auditable": true }, "magic_schemas-identifier": { "description": "Identifier", "type": "string", "example": "c4a7362d577a6c3019a474fd6f485821", "maxLength": 32, "readOnly": true, "x-auditable": true }, "magic_schemas-modified_on": { "description": "The date and time the tunnel was last modified.", "type": "string", "format": "date-time", "example": "2017-06-14T05:20:00Z", "readOnly": true, "x-auditable": true }, "magic_schemas-modified_tunnels_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "modified": { "type": "boolean", "example": true }, "modified_ipsec_tunnels": { "type": "array", "items": { "$ref": "#/components/schemas/magic_ipsec-tunnel" } } } } }, "type": "object" } ] }, "magic_schemas-mtu": { "description": "The Maximum Transmission Unit (MTU) in bytes for the interconnect. The minimum value is 576.", "type": "integer", "default": 1476 }, "magic_schemas-tunnel_deleted_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true }, "deleted_ipsec_tunnel": { "$ref": "#/components/schemas/magic_ipsec-tunnel" } } } }, "type": "object" } ] }, "magic_schemas-tunnel_modified_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "modified": { "type": "boolean", "example": true }, "modified_ipsec_tunnel": { "$ref": "#/components/schemas/magic_ipsec-tunnel" } } } }, "type": "object" } ] }, "magic_schemas-tunnel_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "ipsec_tunnel": { "$ref": "#/components/schemas/magic_ipsec-tunnel" } } } }, "type": "object" } ] }, "magic_schemas-tunnels_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "ipsec_tunnels": { "type": "array", "items": { "$ref": "#/components/schemas/magic_ipsec-tunnel" } } } } }, "type": "object" } ] }, "magic_scope": { "description": "Used only for ECMP routes.", "type": "object", "properties": { "colo_names": { "$ref": "#/components/schemas/magic_colo_names" }, "colo_regions": { "$ref": "#/components/schemas/magic_colo_regions" } } }, "magic_secondary-connector-id": { "description": "Magic Connector identifier tag. Used when high availability mode is on.", "type": "string", "example": "8d67040d3835dbcf46ce29da440dc482", "x-auditable": true }, "magic_site": { "type": "object", "properties": { "connector_id": { "$ref": "#/components/schemas/magic_connector-id" }, "description": { "type": "string" }, "ha_mode": { "description": "Site high availability mode. If set to true, the site can have two connectors and runs in high availability mode.", "type": "boolean", "example": true }, "id": { "$ref": "#/components/schemas/magic_identifier" }, "location": { "$ref": "#/components/schemas/magic_site-location" }, "name": { "$ref": "#/components/schemas/magic_site-name" }, "secondary_connector_id": { "$ref": "#/components/schemas/magic_secondary-connector-id" } } }, "magic_site-location": { "description": "Location of site in latitude and longitude.", "type": "object", "properties": { "lat": { "description": "Latitude", "type": "string", "example": 37.6192, "x-auditable": true }, "lon": { "description": "Longitude", "type": "string", "example": 122.3816, "x-auditable": true } } }, "magic_site-name": { "description": "The name of the site.", "type": "string", "example": "site_1", "x-auditable": true }, "magic_site_deleted_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_site" } }, "type": "object" } ] }, "magic_site_modified_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_site" } }, "type": "object" } ] }, "magic_site_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_site" } }, "type": "object" } ] }, "magic_site_update_request": { "type": "object", "properties": { "connector_id": { "$ref": "#/components/schemas/magic_connector-id" }, "description": { "type": "string" }, "location": { "$ref": "#/components/schemas/magic_site-location" }, "name": { "$ref": "#/components/schemas/magic_site-name" }, "secondary_connector_id": { "$ref": "#/components/schemas/magic_secondary-connector-id" } } }, "magic_sites_add_single_request": { "type": "object", "properties": { "connector_id": { "$ref": "#/components/schemas/magic_connector-id" }, "description": { "type": "string" }, "ha_mode": { "description": "Site high availability mode. If set to true, the site can have two connectors and runs in high availability mode.", "type": "boolean", "example": true }, "location": { "$ref": "#/components/schemas/magic_site-location" }, "name": { "$ref": "#/components/schemas/magic_site-name" }, "secondary_connector_id": { "$ref": "#/components/schemas/magic_secondary-connector-id" } }, "required": [ "name" ] }, "magic_sites_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/magic_site" } } }, "type": "object" } ] }, "magic_ttl": { "description": "Time To Live (TTL) in number of hops of the GRE tunnel.", "type": "integer", "default": 64, "x-auditable": true }, "magic_tunnel_deleted_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true }, "deleted_gre_tunnel": { "$ref": "#/components/schemas/magic_gre-tunnel" } } } }, "type": "object" } ] }, "magic_tunnel_health_check": { "allOf": [ { "$ref": "#/components/schemas/magic_health_check_base" }, { "properties": { "direction": { "description": "The direction of the flow of the healthcheck. Either unidirectional, where the probe comes to you via the tunnel and the result comes back to Cloudflare via the open Internet, or bidirectional where both the probe and result come and go via the tunnel.", "type": "string", "example": "bidirectional", "default": "unidirectional", "enum": [ "unidirectional", "bidirectional" ] } }, "type": "object" } ] }, "magic_tunnel_modified_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "modified": { "type": "boolean", "example": true }, "modified_gre_tunnel": { "$ref": "#/components/schemas/magic_gre-tunnel" } } } }, "type": "object" } ] }, "magic_tunnel_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "gre_tunnel": { "$ref": "#/components/schemas/magic_gre-tunnel" } } } }, "type": "object" } ] }, "magic_tunnels_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "gre_tunnels": { "type": "array", "items": { "$ref": "#/components/schemas/magic_gre-tunnel" } } } } }, "type": "object" } ] }, "magic_unidirectional": { "description": "The desired traffic direction for this ACL policy. If set to \"false\", the policy will allow bidirectional traffic. If set to \"true\", the policy will only allow traffic in one direction. If not included in request, will default to false.", "type": "boolean" }, "magic_update_bgp_filter_profile_request": { "description": "Partial update for a BGP filter profile. At least one property must be provided; omitted properties are left unchanged. To clear an existing description send `description: \"\"`.", "type": "object", "properties": { "description": { "description": "Description of the filter profile", "type": "string", "example": "Allowed corporate subnets from on-premises", "maxLength": 1024 }, "match_action": { "$ref": "#/components/schemas/magic_bgp_filter_match_action" }, "name": { "description": "Friendly name for the filter profile", "type": "string", "example": "Allowed On-Prem Imports", "maxLength": 255, "minLength": 1 }, "targets": { "description": "List of CIDR prefixes. Each entry may carry an optional suffix that specifies which prefix lengths to match relative to the prefix length N: '{X,Y}' matches prefix lengths in the inclusive range [X, Y] where N <= X <= Y <= max (max is 32 for IPv4, 128 for IPv6), '{X}' matches exactly length X (equivalent to {X,X}), '+' is shorthand for {N, max} (the prefix and all more-specific subnets, including at length N itself; valid even when N is the maximum length). Omit the suffix to match the prefix exactly at length N.", "type": "array", "items": { "description": "CIDR notation prefix with optional + or {X,Y} suffix", "example": "10.0.0.0/8{8,32}", "type": "string" }, "maxItems": 1000 } }, "minProperties": 1 }, "magic_update_bgp_settings_redistribute_sources": { "description": "Per-source toggles controlling which route sources are redistributed into BGP. Each property enables redistribution for one route source.", "type": "object", "properties": { "static:wan": { "description": "Redistribute static WAN routes into BGP", "type": "boolean" } } }, "magic_update_bgp_settings_request": { "type": "object", "properties": { "cloudflare_asn": { "description": "Route advertisements from Cloudflare to ramps in this account will use this ASN.", "type": "integer", "format": "uint32", "example": 13335, "minimum": 1 }, "redistribute": { "$ref": "#/components/schemas/magic_update_bgp_settings_redistribute_sources" } } }, "magic_vlan_tag": { "description": "VLAN ID. Use zero for untagged.", "type": "integer", "example": 42, "x-auditable": true }, "magic_wan": { "type": "object", "properties": { "health_check_rate": { "description": "Magic WAN health check rate for tunnels created on this link. The default value is `mid`.", "type": "string", "example": "low", "default": "mid", "enum": [ "low", "mid", "high" ] }, "id": { "$ref": "#/components/schemas/magic_identifier" }, "name": { "type": "string" }, "physport": { "$ref": "#/components/schemas/magic_port" }, "priority": { "description": "Priority of WAN for traffic loadbalancing.", "type": "integer" }, "site_id": { "$ref": "#/components/schemas/magic_identifier" }, "static_addressing": { "$ref": "#/components/schemas/magic_wan_static_addressing" }, "vlan_tag": { "$ref": "#/components/schemas/magic_vlan_tag" } } }, "magic_wan_deleted_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_wan" } }, "type": "object" } ] }, "magic_wan_modified_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_wan" } }, "type": "object" } ] }, "magic_wan_single_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/magic_wan" } }, "type": "object" } ] }, "magic_wan_static_addressing": { "description": "(optional) if omitted, use DHCP. Submit secondary_address when site is in high availability mode.", "type": "object", "properties": { "address": { "$ref": "#/components/schemas/magic_cidr" }, "gateway_address": { "$ref": "#/components/schemas/magic_ip-address" }, "secondary_address": { "$ref": "#/components/schemas/magic_cidr" } }, "required": [ "address", "gateway_address" ] }, "magic_wan_update_request": { "type": "object", "properties": { "name": { "type": "string" }, "physport": { "$ref": "#/components/schemas/magic_port" }, "priority": { "type": "integer" }, "static_addressing": { "$ref": "#/components/schemas/magic_wan_static_addressing" }, "vlan_tag": { "$ref": "#/components/schemas/magic_vlan_tag" } } }, "magic_wans_add_single_request": { "type": "object", "properties": { "name": { "type": "string" }, "physport": { "$ref": "#/components/schemas/magic_port" }, "priority": { "type": "integer" }, "static_addressing": { "$ref": "#/components/schemas/magic_wan_static_addressing" }, "vlan_tag": { "$ref": "#/components/schemas/magic_vlan_tag" } }, "required": [ "physport" ] }, "magic_wans_collection_response": { "allOf": [ { "$ref": "#/components/schemas/magic_api-response-single" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/magic_wan" } } }, "type": "object" } ] }, "magic_weight": { "description": "Optional weight of the ECMP scope - if provided.", "type": "integer", "x-auditable": true }, "mcn_account_id": { "type": "string", "x-auditable": true }, "mcn_apply_progress": { "type": "object", "properties": { "done": { "type": "integer", "x-auditable": true }, "total": { "type": "integer", "x-auditable": true } }, "required": [ "done", "total" ] }, "mcn_aws_trust_policy": { "type": "object", "properties": { "aws_trust_policy": { "type": "string" }, "item_type": { "type": "string", "x-auditable": true } }, "required": [ "item_type", "aws_trust_policy" ] }, "mcn_azure_setup": { "type": "object", "properties": { "azure_consent_url": { "type": "string" }, "integration_identity_tag": { "type": "string", "x-auditable": true }, "item_type": { "type": "string", "x-auditable": true }, "tag_cli_command": { "type": "string" } }, "required": [ "item_type", "azure_consent_url", "integration_identity_tag", "tag_cli_command" ] }, "mcn_bad_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_response" }, { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_error" }, "minLength": 1 }, "result": { "type": "object", "enum": [ null ], "nullable": true } }, "type": "object" } ] }, "mcn_catalog_sync": { "type": "object", "properties": { "description": { "type": "string" }, "destination_id": { "$ref": "#/components/schemas/mcn_catalog_sync_destination_id" }, "destination_type": { "$ref": "#/components/schemas/mcn_catalog_sync_destination_type" }, "errors": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/mcn_error" } }, "id": { "$ref": "#/components/schemas/mcn_catalog_sync_id" }, "includes_discoveries_until": { "type": "string" }, "last_attempted_update_at": { "type": "string" }, "last_successful_update_at": { "type": "string" }, "last_user_update_at": { "type": "string" }, "name": { "type": "string" }, "policy": { "type": "string" }, "update_mode": { "$ref": "#/components/schemas/mcn_catalog_sync_update_mode" } }, "required": [ "id", "name", "description", "policy", "destination_type", "destination_id", "destination_url", "update_mode", "last_user_update_at" ] }, "mcn_catalog_sync_destination_id": { "type": "string", "format": "uuid", "x-auditable": true }, "mcn_catalog_sync_destination_type": { "type": "string", "enum": [ "NONE", "ZERO_TRUST_LIST" ], "x-auditable": true }, "mcn_catalog_sync_id": { "type": "string", "format": "uuid" }, "mcn_catalog_sync_update_mode": { "type": "string", "enum": [ "AUTO", "MANUAL" ], "x-auditable": true }, "mcn_catalog_syncs_prebuilt_policies_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_catalog_syncs_prebuilt_policy" } } }, "type": "object" } ] }, "mcn_catalog_syncs_prebuilt_policy": { "type": "object", "properties": { "applicable_destinations": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_catalog_sync_destination_type" } }, "policy_description": { "type": "string" }, "policy_name": { "type": "string" }, "policy_string": { "type": "string" } }, "required": [ "policy_name", "policy_description", "policy_string", "applicable_destinations" ] }, "mcn_cidr_prefix": { "description": "An IP address prefix in CIDR format.", "type": "string", "example": "192.168.0.0/16", "x-auditable": true }, "mcn_cloud_platform_client": { "type": "object", "properties": { "client_type": { "type": "string", "enum": [ "MAGIC_WAN_CLOUD_ONRAMP" ], "x-auditable": true }, "id": { "$ref": "#/components/schemas/mcn_platform_client_id" }, "name": { "type": "string", "x-auditable": true } }, "required": [ "client_type", "name", "id" ] }, "mcn_cloud_type": { "type": "string", "enum": [ "AWS", "AZURE", "GOOGLE", "CLOUDFLARE" ], "x-auditable": true }, "mcn_conduit_route_id": { "type": "string", "format": "uuid", "x-auditable": true }, "mcn_conduit_tunnel_id": { "type": "string", "format": "uuid", "x-auditable": true }, "mcn_cost": { "type": "object", "properties": { "currency": { "type": "string", "x-auditable": true }, "monthly_cost": { "type": "number", "format": "double" } }, "required": [ "monthly_cost", "currency" ] }, "mcn_cost_diff": { "type": "object", "properties": { "currency": { "type": "string", "x-auditable": true }, "current_monthly_cost": { "type": "number", "format": "double" }, "diff": { "type": "number", "format": "double" }, "proposed_monthly_cost": { "type": "number", "format": "double" } }, "required": [ "current_monthly_cost", "proposed_monthly_cost", "diff", "currency" ] }, "mcn_create_catalog_sync_request": { "type": "object", "properties": { "description": { "type": "string" }, "destination_type": { "$ref": "#/components/schemas/mcn_catalog_sync_destination_type" }, "name": { "type": "string" }, "policy": { "type": "string" }, "update_mode": { "$ref": "#/components/schemas/mcn_catalog_sync_update_mode" } }, "required": [ "name", "update_mode", "destination_type" ] }, "mcn_create_catalog_sync_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_catalog_sync" } }, "type": "object" } ] }, "mcn_create_onramp_request": { "type": "object", "properties": { "adopted_hub_id": { "$ref": "#/components/schemas/mcn_resource_id" }, "attached_hubs": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_resource_id" } }, "attached_vpcs": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_resource_id" } }, "cloud_asn": { "description": "Sets the cloud-side ASN. If unset or zero, the cloud's default ASN takes effect.", "type": "integer", "format": "uint32", "x-auditable": true }, "cloud_type": { "$ref": "#/components/schemas/mcn_onramp_cloud_type" }, "description": { "type": "string" }, "dynamic_routing": { "description": "Enables BGP routing. When enabling this feature, set both install_routes_in_cloud and install_routes_in_magic_wan to false.", "type": "boolean", "x-auditable": true }, "hub_provider_id": { "$ref": "#/components/schemas/mcn_provider_id" }, "install_routes_in_cloud": { "type": "boolean", "x-auditable": true }, "install_routes_in_magic_wan": { "type": "boolean", "x-auditable": true }, "manage_hub_to_hub_attachments": { "type": "boolean", "x-auditable": true }, "manage_vpc_to_hub_attachments": { "type": "boolean", "x-auditable": true }, "name": { "type": "string" }, "region": { "type": "string", "x-auditable": true }, "type": { "$ref": "#/components/schemas/mcn_onramp_type" }, "vpc": { "$ref": "#/components/schemas/mcn_resource_id" } }, "required": [ "name", "type", "cloud_type", "install_routes_in_cloud", "install_routes_in_magic_wan", "dynamic_routing" ] }, "mcn_create_onramp_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_onramp" } }, "type": "object" } ] }, "mcn_create_provider_request": { "type": "object", "properties": { "cloud_type": { "$ref": "#/components/schemas/mcn_cloud_type" }, "description": { "type": "string", "x-auditable": true }, "friendly_name": { "type": "string", "x-auditable": true } }, "required": [ "friendly_name", "cloud_type" ] }, "mcn_create_provider_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_provider" } }, "type": "object" } ] }, "mcn_delete_catalog_sync_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_deleted_catalog_sync" } }, "type": "object" } ] }, "mcn_delete_onramp_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_deleted_onramp" } }, "type": "object" } ] }, "mcn_delete_provider_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_deleted_provider" } }, "type": "object" } ] }, "mcn_delete_resource_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_deleted_resource" } }, "type": "object" } ] }, "mcn_deleted_catalog_sync": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/mcn_catalog_sync_id" } }, "required": [ "id" ] }, "mcn_deleted_onramp": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/mcn_onramp_id" } }, "required": [ "id" ] }, "mcn_deleted_provider": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/mcn_provider_id" } }, "required": [ "id" ] }, "mcn_deleted_resource": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/mcn_resource_id" } }, "required": [ "id" ] }, "mcn_error": { "type": "object", "properties": { "code": { "type": "integer", "enum": [ 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008, 1009, 1010, 1011, 1012, 1013, 1014, 1015, 1016, 1017, 1018, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 3001, 3002, 3003, 3004, 3005, 3006, 3007, 4001, 4002, 4003, 4004, 4005, 4006, 4007, 4008, 4009, 4010, 4011, 4012, 4013, 4014, 4015, 4016, 4017, 4018, 4019, 4020, 4021, 4022, 4023, 5001, 5002, 5003, 5004, 102000, 102001, 102002, 102003, 102004, 102005, 102006, 102007, 102008, 102009, 102010, 102011, 102012, 102013, 102014, 102015, 102016, 102017, 102018, 102019, 102020, 102021, 102022, 102023, 102024, 102025, 102026, 102027, 102028, 102029, 102030, 102031, 102032, 102033, 102034, 102035, 102036, 102037, 102038, 102039, 102040, 102041, 102042, 102043, 102044, 102045, 102046, 102047, 102048, 102049, 102050, 102051, 102052, 102053, 102054, 102055, 102056, 102057, 102058, 102059, 102060, 102061, 102062, 102063, 102064, 102065, 102066, 102067, 102068, 102069, 102070, 102071, 102072, 103001, 103002, 103003, 103004, 103005, 103006, 103007, 103008 ], "x-auditable": true }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "meta": { "$ref": "#/components/schemas/mcn_error_meta" }, "source": { "$ref": "#/components/schemas/mcn_error_source" } }, "required": [ "code", "message" ] }, "mcn_error_meta": { "type": "object", "properties": { "l10n_key": { "type": "string", "x-auditable": true }, "loggable_error": { "type": "string" }, "template_data": { "type": "object" }, "trace_id": { "type": "string", "x-auditable": true } } }, "mcn_error_source": { "type": "object", "properties": { "parameter": { "type": "string", "x-auditable": true }, "parameter_value_index": { "type": "integer", "x-auditable": true }, "pointer": { "type": "string", "x-auditable": true } } }, "mcn_gcp_setup": { "type": "object", "properties": { "integration_identity_tag": { "type": "string", "x-auditable": true }, "item_type": { "type": "string", "x-auditable": true }, "tag_cli_command": { "type": "string" } }, "required": [ "item_type", "integration_identity_tag", "tag_cli_command" ] }, "mcn_get_magic_wan_address_space_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_magic_wan_address_space" } }, "type": "object" } ] }, "mcn_get_onramp_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_onramp" } }, "type": "object" } ] }, "mcn_good_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_response" }, { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_error" }, "maxLength": 0 } }, "type": "object" } ] }, "mcn_good_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_response_collection" }, { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_error" }, "maxLength": 0 } }, "type": "object" } ] }, "mcn_list_item": { "type": "object", "properties": { "item_type": { "type": "string" }, "list": { "type": "array", "items": { "discriminator": { "propertyName": "item_type" }, "oneOf": [ { "$ref": "#/components/schemas/mcn_string_item" }, { "$ref": "#/components/schemas/mcn_resource_preview_item" } ], "type": "object" } } }, "required": [ "item_type", "list" ] }, "mcn_list_onramps_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_onramp" } } }, "type": "object" } ] }, "mcn_magic_wan_address_space": { "type": "object", "properties": { "prefixes": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_cidr_prefix" } } }, "required": [ "prefixes" ] }, "mcn_observation": { "type": "object", "properties": { "first_observed_at": { "type": "string", "x-auditable": true }, "last_observed_at": { "type": "string", "x-auditable": true }, "provider_id": { "$ref": "#/components/schemas/mcn_provider_id" }, "resource_id": { "$ref": "#/components/schemas/mcn_resource_id" } }, "required": [ "provider_id", "resource_id", "first_observed_at", "last_observed_at" ] }, "mcn_onramp": { "type": "object", "properties": { "attached_hubs": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_resource_id" } }, "attached_vpcs": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_resource_id" } }, "cloud_asn": { "type": "integer", "format": "uint32", "x-auditable": true }, "cloud_type": { "$ref": "#/components/schemas/mcn_onramp_cloud_type" }, "description": { "type": "string", "x-auditable": true }, "dynamic_routing": { "type": "boolean", "x-auditable": true }, "hub": { "$ref": "#/components/schemas/mcn_resource_id" }, "id": { "$ref": "#/components/schemas/mcn_onramp_id" }, "install_routes_in_cloud": { "type": "boolean", "x-auditable": true }, "install_routes_in_magic_wan": { "type": "boolean", "x-auditable": true }, "last_applied_at": { "type": "string", "x-auditable": true }, "last_exported_at": { "type": "string", "x-auditable": true }, "last_planned_at": { "type": "string", "x-auditable": true }, "manage_hub_to_hub_attachments": { "type": "boolean", "x-auditable": true }, "manage_vpc_to_hub_attachments": { "type": "boolean", "x-auditable": true }, "name": { "type": "string", "x-auditable": true }, "planned_monthly_cost_estimate": { "$ref": "#/components/schemas/mcn_cost_diff" }, "planned_resources": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_resource_diff" } }, "planned_resources_unavailable": { "type": "boolean", "x-auditable": true }, "post_apply_monthly_cost_estimate": { "$ref": "#/components/schemas/mcn_cost" }, "post_apply_resources": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/mcn_resource_details" } }, "post_apply_resources_unavailable": { "type": "boolean", "x-auditable": true }, "region": { "type": "string", "x-auditable": true }, "status": { "$ref": "#/components/schemas/mcn_onramp_status" }, "type": { "$ref": "#/components/schemas/mcn_onramp_type" }, "updated_at": { "type": "string" }, "vpc": { "$ref": "#/components/schemas/mcn_resource_id" }, "vpcs_by_id": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/mcn_resource_details" } }, "vpcs_by_id_unavailable": { "description": "The list of vpc IDs for which resource details failed to generate.", "type": "array", "items": { "$ref": "#/components/schemas/mcn_resource_id" } } }, "required": [ "id", "name", "type", "cloud_type", "install_routes_in_cloud", "install_routes_in_magic_wan", "dynamic_routing", "updated_at" ] }, "mcn_onramp_cloud_type": { "type": "string", "enum": [ "AWS", "AZURE", "GOOGLE" ], "x-auditable": true }, "mcn_onramp_id": { "type": "string", "format": "uuid", "x-auditable": true }, "mcn_onramp_lifecycle_state": { "type": "string", "enum": [ "OnrampNeedsApply", "OnrampPendingPlan", "OnrampPlanning", "OnrampPlanFailed", "OnrampPendingApproval", "OnrampPendingApply", "OnrampApplying", "OnrampApplyFailed", "OnrampActive", "OnrampPendingDestroy", "OnrampDestroying", "OnrampDestroyFailed" ], "x-auditable": true }, "mcn_onramp_status": { "type": "object", "properties": { "apply_progress": { "$ref": "#/components/schemas/mcn_apply_progress" }, "lifecycle_errors": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/mcn_error" } }, "lifecycle_state": { "$ref": "#/components/schemas/mcn_onramp_lifecycle_state" }, "plan_progress": { "$ref": "#/components/schemas/mcn_plan_progress" }, "routes": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_conduit_route_id" } }, "tunnels": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_conduit_tunnel_id" } } }, "required": [ "lifecycle_state", "tunnels", "routes", "plan_progress", "apply_progress" ] }, "mcn_onramp_type": { "type": "string", "enum": [ "OnrampTypeSingle", "OnrampTypeHub" ], "x-auditable": true }, "mcn_onramp_with_account": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_onramp" }, { "properties": { "account_id": { "$ref": "#/components/schemas/mcn_account_id" } }, "required": [ "account_id" ], "type": "object" } ] }, "mcn_plan_progress": { "type": "object", "properties": { "done": { "type": "integer", "x-auditable": true }, "total": { "type": "integer", "x-auditable": true } }, "required": [ "done", "total" ] }, "mcn_planned_action": { "type": "string", "enum": [ "no_op", "create", "update", "replace", "destroy" ], "x-auditable": true }, "mcn_platform_client_id": { "type": "string", "format": "uuid", "x-auditable": true }, "mcn_policy_result": { "type": "string" }, "mcn_provider": { "type": "object", "properties": { "aws_arn": { "type": "string", "x-auditable": true }, "azure_subscription_id": { "type": "string", "x-auditable": true }, "azure_tenant_id": { "type": "string", "x-auditable": true }, "cloud_type": { "$ref": "#/components/schemas/mcn_cloud_type" }, "description": { "type": "string" }, "friendly_name": { "type": "string" }, "gcp_project_id": { "type": "string", "x-auditable": true }, "gcp_service_account_email": { "type": "string", "x-auditable": true }, "id": { "$ref": "#/components/schemas/mcn_provider_id" }, "last_updated": { "type": "string", "x-auditable": true }, "lifecycle_state": { "$ref": "#/components/schemas/mcn_provider_lifecycle_state" }, "state": { "$ref": "#/components/schemas/mcn_provider_discovery_status" }, "state_v2": { "$ref": "#/components/schemas/mcn_provider_discovery_status" }, "status": { "$ref": "#/components/schemas/mcn_provider_status" } }, "required": [ "id", "friendly_name", "cloud_type", "last_updated", "state", "state_v2", "lifecycle_state" ] }, "mcn_provider_discovery_progress": { "type": "object", "properties": { "done": { "type": "integer", "x-auditable": true }, "total": { "type": "integer", "x-auditable": true }, "unit": { "type": "string", "x-auditable": true } }, "required": [ "unit", "done", "total" ] }, "mcn_provider_discovery_status": { "type": "string", "enum": [ "UNSPECIFIED", "PENDING", "DISCOVERING", "FAILED", "SUCCEEDED" ], "x-auditable": true }, "mcn_provider_id": { "type": "string", "format": "uuid", "x-auditable": true }, "mcn_provider_initial_setup_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "type": "object", "discriminator": { "propertyName": "item_type" }, "oneOf": [ { "$ref": "#/components/schemas/mcn_aws_trust_policy" }, { "$ref": "#/components/schemas/mcn_azure_setup" }, { "$ref": "#/components/schemas/mcn_gcp_setup" } ] } }, "type": "object" } ] }, "mcn_provider_lifecycle_state": { "type": "string", "enum": [ "ACTIVE", "PENDING_SETUP", "RETIRED" ], "x-auditable": true }, "mcn_provider_status": { "type": "object", "properties": { "credentials_good_since": { "type": "string", "x-auditable": true }, "credentials_missing_since": { "type": "string", "x-auditable": true }, "credentials_rejected_since": { "type": "string", "x-auditable": true }, "discovery_message": { "type": "string", "x-auditable": true }, "discovery_message_v2": { "type": "string", "x-auditable": true }, "discovery_progress": { "$ref": "#/components/schemas/mcn_provider_discovery_progress" }, "discovery_progress_v2": { "$ref": "#/components/schemas/mcn_provider_discovery_progress" }, "in_use_by": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_cloud_platform_client" } }, "last_discovery_completed_at": { "type": "string", "x-auditable": true }, "last_discovery_completed_at_v2": { "type": "string", "x-auditable": true }, "last_discovery_started_at": { "type": "string", "x-auditable": true }, "last_discovery_started_at_v2": { "type": "string", "x-auditable": true }, "last_discovery_status": { "$ref": "#/components/schemas/mcn_provider_discovery_status" }, "last_discovery_status_v2": { "$ref": "#/components/schemas/mcn_provider_discovery_status" }, "last_updated": { "type": "string", "x-auditable": true }, "regions": { "type": "array", "items": { "type": "string", "x-auditable": true } } }, "required": [ "last_discovery_status", "last_discovery_status_v2", "regions", "discovery_status", "discovery_status_v2", "discovery_progress", "discovery_progress_v2" ] }, "mcn_provider_with_account": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_provider" }, { "properties": { "account_id": { "$ref": "#/components/schemas/mcn_account_id" } }, "required": [ "account_id" ], "type": "object" } ] }, "mcn_read_account_catalog_sync_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_catalog_sync" } }, "type": "object" } ] }, "mcn_read_account_catalog_syncs_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_catalog_sync" } } }, "type": "object" } ] }, "mcn_read_account_provider_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_provider" } }, "type": "object" } ] }, "mcn_read_account_providers_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_provider" } } }, "type": "object" } ] }, "mcn_read_account_resource_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_resource_details" } }, "type": "object" } ] }, "mcn_read_account_resources_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response_collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_resource_details" } }, "result_info": { "$ref": "#/components/schemas/mcn_result_info" } }, "type": "object" } ] }, "mcn_refresh_catalog_sync_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_policy_result" } }, "type": "object" } ] }, "mcn_resource_details": { "type": "object", "properties": { "account_id": { "$ref": "#/components/schemas/mcn_account_id" }, "cloud_type": { "$ref": "#/components/schemas/mcn_cloud_type" }, "config": { "type": "object", "additionalProperties": true }, "deployment_provider": { "$ref": "#/components/schemas/mcn_provider_id" }, "id": { "$ref": "#/components/schemas/mcn_resource_id" }, "managed": { "type": "boolean", "x-auditable": true }, "managed_by": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_cloud_platform_client" } }, "monthly_cost_estimate": { "$ref": "#/components/schemas/mcn_cost" }, "name": { "type": "string" }, "native_id": { "type": "string" }, "observations": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/mcn_observation" } }, "provider_ids": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_provider_id" } }, "provider_names_by_id": { "type": "object", "additionalProperties": { "type": "string" } }, "region": { "type": "string", "x-auditable": true }, "resource_group": { "type": "string", "x-auditable": true }, "resource_type": { "$ref": "#/components/schemas/mcn_resource_type" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_resource_details_section" } }, "state": { "type": "object", "additionalProperties": true }, "tags": { "type": "object", "additionalProperties": { "type": "string" } }, "updated_at": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "native_id", "name", "account_id", "cloud_type", "resource_type", "managed", "provider_ids", "provider_names_by_id", "region", "resource_group", "tags", "updated_at", "url", "config", "state", "observations", "deployment_provider", "sections", "monthly_cost_estimate" ] }, "mcn_resource_details_section": { "type": "object", "properties": { "help_text": { "type": "string" }, "hidden_items": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_resource_details_section_item" } }, "name": { "type": "string" }, "visible_items": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_resource_details_section_item" } } }, "required": [ "name", "visible_items", "hidden_items" ] }, "mcn_resource_details_section_item": { "type": "object", "properties": { "helpText": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "object", "discriminator": { "propertyName": "item_type" }, "oneOf": [ { "$ref": "#/components/schemas/mcn_string_item" }, { "$ref": "#/components/schemas/mcn_yaml_item" }, { "$ref": "#/components/schemas/mcn_yaml_diff_item" }, { "$ref": "#/components/schemas/mcn_resource_preview_item" }, { "$ref": "#/components/schemas/mcn_list_item" } ] } } }, "mcn_resource_diff": { "type": "object", "properties": { "diff": { "$ref": "#/components/schemas/mcn_yaml_diff" }, "keys_require_replace": { "type": "array", "items": { "type": "string" } }, "monthly_cost_estimate_diff": { "$ref": "#/components/schemas/mcn_cost_diff" }, "planned_action": { "$ref": "#/components/schemas/mcn_planned_action" }, "resource": { "$ref": "#/components/schemas/mcn_resource_preview" } }, "required": [ "resource", "diff", "planned_action", "keys_require_replace", "monthly_cost_estimate_diff" ] }, "mcn_resource_id": { "type": "string", "format": "uuid", "x-auditable": true }, "mcn_resource_preview": { "type": "object", "properties": { "cloud_type": { "$ref": "#/components/schemas/mcn_cloud_type" }, "detail": { "type": "string" }, "id": { "$ref": "#/components/schemas/mcn_resource_id" }, "name": { "type": "string" }, "resource_type": { "$ref": "#/components/schemas/mcn_resource_type" }, "title": { "type": "string" } }, "required": [ "id", "cloud_type", "resource_type", "name", "title", "detail" ] }, "mcn_resource_preview_item": { "type": "object", "properties": { "item_type": { "type": "string", "x-auditable": true }, "resource_preview": { "$ref": "#/components/schemas/mcn_resource_preview" } }, "required": [ "item_type", "resource_preview" ] }, "mcn_resource_type": { "type": "string", "enum": [ "aws_customer_gateway", "aws_egress_only_internet_gateway", "aws_internet_gateway", "aws_instance", "aws_network_interface", "aws_route", "aws_route_table", "aws_route_table_association", "aws_subnet", "aws_vpc", "aws_vpc_ipv4_cidr_block_association", "aws_vpn_connection", "aws_vpn_connection_route", "aws_vpn_gateway", "aws_security_group", "aws_vpc_security_group_ingress_rule", "aws_vpc_security_group_egress_rule", "aws_ec2_managed_prefix_list", "aws_ec2_transit_gateway", "aws_ec2_transit_gateway_prefix_list_reference", "aws_ec2_transit_gateway_vpc_attachment", "azurerm_application_security_group", "azurerm_lb", "azurerm_lb_backend_address_pool", "azurerm_lb_nat_pool", "azurerm_lb_nat_rule", "azurerm_lb_rule", "azurerm_local_network_gateway", "azurerm_network_interface", "azurerm_network_interface_application_security_group_association", "azurerm_network_interface_backend_address_pool_association", "azurerm_network_interface_security_group_association", "azurerm_network_security_group", "azurerm_public_ip", "azurerm_route", "azurerm_route_table", "azurerm_subnet", "azurerm_subnet_route_table_association", "azurerm_virtual_machine", "azurerm_virtual_network_gateway_connection", "azurerm_virtual_network", "azurerm_virtual_network_gateway", "google_compute_network", "google_compute_subnetwork", "google_compute_vpn_gateway", "google_compute_vpn_tunnel", "google_compute_route", "google_compute_address", "google_compute_global_address", "google_compute_router", "google_compute_interconnect_attachment", "google_compute_ha_vpn_gateway", "google_compute_forwarding_rule", "google_compute_network_firewall_policy", "google_compute_network_firewall_policy_rule", "cloudflare_static_route", "cloudflare_ipsec_tunnel" ], "x-auditable": true }, "mcn_resources_catalog_policy_preview": { "type": "string" }, "mcn_resources_catalog_policy_preview_request": { "type": "object", "properties": { "policy": { "type": "string" } }, "required": [ "policy" ] }, "mcn_resources_catalog_policy_preview_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_resources_catalog_policy_preview" } }, "type": "object" } ] }, "mcn_response": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_error" } }, "success": { "type": "boolean", "x-auditable": true } }, "required": [ "result", "success", "errors", "messages" ] }, "mcn_response_collection": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_error" } }, "result_info": { "$ref": "#/components/schemas/mcn_result_info" }, "success": { "type": "boolean" } }, "required": [ "result", "success", "errors", "messages" ] }, "mcn_result_info": { "type": "object", "properties": { "count": { "description": "The number of items in the current result set.", "type": "integer", "example": 1 }, "page": { "description": "The current page (starts from zero).", "type": "integer", "example": 1 }, "per_page": { "description": "The maximum number of items per page.", "type": "integer", "example": 20 }, "total_count": { "description": "The total number of items in the entire result set.", "type": "integer", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "integer", "example": 200 } }, "required": [ "page", "per_page", "count", "total_count" ] }, "mcn_string_item": { "type": "object", "properties": { "item_type": { "type": "string" }, "string": { "type": "string" } }, "required": [ "item_type", "string" ] }, "mcn_update_catalog_sync_request": { "type": "object", "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "policy": { "type": "string" }, "update_mode": { "$ref": "#/components/schemas/mcn_catalog_sync_update_mode" } } }, "mcn_update_catalog_sync_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_catalog_sync" } }, "type": "object" } ] }, "mcn_update_magic_wan_address_space_request": { "type": "object", "properties": { "prefixes": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_cidr_prefix" } } }, "required": [ "prefixes" ] }, "mcn_update_magic_wan_address_space_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_magic_wan_address_space" } }, "type": "object" } ] }, "mcn_update_onramp_request": { "type": "object", "properties": { "attached_hubs": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_resource_id" } }, "attached_vpcs": { "type": "array", "items": { "$ref": "#/components/schemas/mcn_resource_id" } }, "description": { "type": "string" }, "install_routes_in_cloud": { "type": "boolean", "x-auditable": true }, "install_routes_in_magic_wan": { "type": "boolean", "x-auditable": true }, "manage_hub_to_hub_attachments": { "type": "boolean" }, "manage_vpc_to_hub_attachments": { "type": "boolean" }, "name": { "type": "string" }, "vpc": { "$ref": "#/components/schemas/mcn_resource_id" } } }, "mcn_update_onramp_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_onramp" } }, "type": "object" } ] }, "mcn_update_provider_request": { "type": "object", "properties": { "aws_arn": { "type": "string", "x-auditable": true }, "azure_subscription_id": { "type": "string", "x-auditable": true }, "azure_tenant_id": { "type": "string", "x-auditable": true }, "description": { "type": "string", "x-auditable": true }, "friendly_name": { "type": "string", "x-auditable": true }, "gcp_project_id": { "type": "string", "x-auditable": true }, "gcp_service_account_email": { "type": "string", "x-auditable": true } } }, "mcn_update_provider_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mcn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mcn_provider" } }, "type": "object" } ] }, "mcn_yaml_diff": { "type": "object", "properties": { "diff": { "type": "string" }, "left_description": { "type": "string" }, "left_yaml": { "type": "string" }, "right_description": { "type": "string" }, "right_yaml": { "type": "string" } }, "required": [ "left_yaml", "left_description", "right_yaml", "right_description", "diff" ] }, "mcn_yaml_diff_item": { "type": "object", "properties": { "item_type": { "type": "string" }, "yaml_diff": { "$ref": "#/components/schemas/mcn_yaml_diff" } }, "required": [ "item_type", "yaml_diff" ] }, "mcn_yaml_item": { "type": "object", "properties": { "item_type": { "type": "string" }, "yaml": { "type": "string" } }, "required": [ "item_type", "yaml" ] }, "mconn-telemetry_account_id": { "description": "Account identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "mconn-telemetry_coded_message": { "type": "object", "properties": { "code": { "type": "number" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "mconn-telemetry_customer_events_get_success": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn-telemetry_envelope" }, { "properties": { "result": { "$ref": "#/components/schemas/mconn-telemetry_recorded_event" } }, "required": [ "result" ], "type": "object" } ] }, "mconn-telemetry_customer_events_latest_get_result": { "type": "object", "properties": { "count": { "type": "number" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/mconn-telemetry_recorded_event" } } }, "required": [ "items", "count" ] }, "mconn-telemetry_customer_events_latest_get_success": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn-telemetry_envelope" }, { "properties": { "result": { "$ref": "#/components/schemas/mconn-telemetry_customer_events_latest_get_result" } }, "required": [ "result" ], "type": "object" } ] }, "mconn-telemetry_customer_events_list_result": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/mconn-telemetry_event_metadata" } } }, "required": [ "items", "count" ] }, "mconn-telemetry_customer_events_list_success": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn-telemetry_envelope" }, { "properties": { "result": { "$ref": "#/components/schemas/mconn-telemetry_customer_events_list_result" } }, "required": [ "result" ], "type": "object" } ] }, "mconn-telemetry_customer_snapshots_get_success": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn-telemetry_envelope" }, { "properties": { "result": { "$ref": "#/components/schemas/mconn-telemetry_snapshot" } }, "required": [ "result" ], "type": "object" } ] }, "mconn-telemetry_customer_snapshots_latest_get_result": { "type": "object", "properties": { "count": { "type": "number" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/mconn-telemetry_snapshot" } } }, "required": [ "items", "count" ] }, "mconn-telemetry_customer_snapshots_latest_get_success": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn-telemetry_envelope" }, { "properties": { "result": { "$ref": "#/components/schemas/mconn-telemetry_customer_snapshots_latest_get_result" } }, "required": [ "result" ], "type": "object" } ] }, "mconn-telemetry_customer_snapshots_list_result": { "type": "object", "properties": { "count": { "type": "number" }, "cursor": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/mconn-telemetry_snapshot_metadata" } } }, "required": [ "items", "count" ] }, "mconn-telemetry_customer_snapshots_list_success": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn-telemetry_envelope" }, { "properties": { "result": { "$ref": "#/components/schemas/mconn-telemetry_customer_snapshots_list_result" } }, "required": [ "result" ], "type": "object" } ] }, "mconn-telemetry_envelope": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/mconn-telemetry_coded_message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/mconn-telemetry_coded_message" } }, "success": { "type": "boolean" } }, "required": [ "success" ] }, "mconn-telemetry_event": { "description": "Event kind plus event-specific payload fields.\n\nEvent kinds:\n- `Init`: Initialized process\n- `Leave`: Stopped process\n- `StartAttestation`: Started attestation\n- `FinishAttestationSuccess`: Finished attestation\n- `FinishAttestationFailure`: Failed attestation\n- `StartRotateCryptKey`: Started crypt key rotation\n- `FinishRotateCryptKeySuccess`: Finished crypt key rotation\n- `FinishRotateCryptKeyFailure`: Failed crypt key rotation\n- `StartRotatePki`: Started PKI rotation\n- `FinishRotatePkiSuccess`: Finished PKI rotation\n- `FinishRotatePkiFailure`: Failed PKI rotation\n- `StartUpgrade`: Started upgrade\n- `FinishUpgradeSuccess`: Finished upgrade\n- `FinishUpgradeFailure`: Failed upgrade\n- `BlessSlotSuccess`: Blessed boot entry slot\n- `BlessSlotPending`: Boot entry slot is not yet blessed\n- `BlessSlotFailure`: Failed to bless boot entry slot\n- `Reconcile`: Reconciled\n- `ConfigureCloudflaredTunnel`: Configured Cloudflared tunnel\n- `RekeyInstallBoth`: Installed initial inbound and outbound keys\n- `RekeyStart`: Installed new inbound key, kept old outbound\n- `RekeyRestart`: Restarted in-progress rekey with newer key material\n- `RekeyAdvance`: Confirmed traffic on new inbound key, swapped outbound to new\n- `RekeyComplete`: Deleted old keys\n- `RekeyReset`: Deleted all keys after receiving an unexpected key\n- `HaTransition`: Completed HA state transition\n- `HaError`: Received unexpected HA error\n- `HaInit`: Initialized HA subsystem\n- `HaLeave`: Stopped HA subsystem", "type": "object", "properties": { "k": { "description": "Event kind", "type": "string", "enum": [ "Init", "Leave", "StartAttestation", "FinishAttestationSuccess", "FinishAttestationFailure", "StartRotateCryptKey", "FinishRotateCryptKeySuccess", "FinishRotateCryptKeyFailure", "StartRotatePki", "FinishRotatePkiSuccess", "FinishRotatePkiFailure", "StartUpgrade", "FinishUpgradeSuccess", "FinishUpgradeFailure", "BlessSlotSuccess", "BlessSlotPending", "BlessSlotFailure", "Reconcile", "ConfigureCloudflaredTunnel", "RekeyInstallBoth", "RekeyStart", "RekeyRestart", "RekeyAdvance", "RekeyComplete", "RekeyReset", "HaTransition", "HaError", "HaInit", "HaLeave" ] } }, "additionalProperties": true, "required": [ "k" ] }, "mconn-telemetry_event_metadata": { "type": "object", "properties": { "a": { "description": "Time the Event was collected (seconds since the Unix epoch)", "type": "number" }, "k": { "description": "Kind", "type": "string" }, "n": { "description": "Sequence number, used to order events with the same timestamp", "type": "number" }, "t": { "description": "Time the Event was recorded (seconds since the Unix epoch)", "type": "number" } }, "required": [ "a", "t", "n", "k" ] }, "mconn-telemetry_recorded_event": { "description": "Recorded Event", "type": "object", "properties": { "e": { "$ref": "#/components/schemas/mconn-telemetry_event" }, "n": { "description": "Sequence number, used to order events with the same timestamp", "type": "number" }, "t": { "description": "Time the Event was recorded (seconds since the Unix epoch)", "type": "number" }, "v": { "description": "Version", "type": "string" } }, "required": [ "t", "n", "e" ] }, "mconn-telemetry_snapshot": { "description": "Snapshot", "type": "object", "properties": { "bonds": { "type": "array", "items": { "$ref": "#/components/schemas/mconn-telemetry_snapshot_bond" } }, "count_reclaim_failures": { "description": "Count of failures to reclaim space", "type": "number" }, "count_reclaimed_paths": { "description": "Count of reclaimed paths", "type": "number" }, "count_record_failed": { "description": "Count of failed snapshot recordings", "type": "number" }, "count_transmit_failures": { "description": "Count of failed snapshot transmissions", "type": "number" }, "cpu_count": { "description": "Count of processors/cores", "type": "number" }, "cpu_pressure_10s": { "description": "Percentage of time over a 10 second window that tasks were stalled", "type": "number" }, "cpu_pressure_300s": { "description": "Percentage of time over a 5 minute window that tasks were stalled", "type": "number" }, "cpu_pressure_60s": { "description": "Percentage of time over a 1 minute window that tasks were stalled", "type": "number" }, "cpu_pressure_total_us": { "description": "Total stall time (microseconds)", "type": "number" }, "cpu_time_guest_ms": { "description": "Time spent running a virtual CPU or guest OS (milliseconds)", "type": "number" }, "cpu_time_guest_nice_ms": { "description": "Time spent running a niced guest (milliseconds)", "type": "number" }, "cpu_time_idle_ms": { "description": "Time spent in idle state (milliseconds)", "type": "number" }, "cpu_time_iowait_ms": { "description": "Time spent wait for I/O to complete (milliseconds)", "type": "number" }, "cpu_time_irq_ms": { "description": "Time spent servicing interrupts (milliseconds)", "type": "number" }, "cpu_time_nice_ms": { "description": "Time spent in low-priority user mode (milliseconds)", "type": "number" }, "cpu_time_softirq_ms": { "description": "Time spent servicing softirqs (milliseconds)", "type": "number" }, "cpu_time_steal_ms": { "description": "Time stolen (milliseconds)", "type": "number" }, "cpu_time_system_ms": { "description": "Time spent in system mode (milliseconds)", "type": "number" }, "cpu_time_user_ms": { "description": "Time spent in user mode (milliseconds)", "type": "number" }, "delta": { "description": "Number of network operations applied during state transition", "type": "number" }, "dhcp_leases": { "type": "array", "items": { "$ref": "#/components/schemas/mconn-telemetry_snapshot_dhcp_lease" } }, "disks": { "type": "array", "items": { "$ref": "#/components/schemas/mconn-telemetry_snapshot_disk" } }, "epsilon": { "description": "Simulated number of network operations applied during state transition", "type": "number" }, "ha_state": { "description": "Name of high availability state", "type": "string" }, "ha_value": { "description": "Numeric value associated with high availability state (0 = disabled, 1 = active, 2 = standby, 3 = stopped, 4 = fault)", "type": "number" }, "interfaces": { "type": "array", "items": { "$ref": "#/components/schemas/mconn-telemetry_snapshot_interface" } }, "io_pressure_full_10s": { "description": "Percentage of time over a 10 second window that all tasks were stalled", "type": "number" }, "io_pressure_full_300s": { "description": "Percentage of time over a 5 minute window that all tasks were stalled", "type": "number" }, "io_pressure_full_60s": { "description": "Percentage of time over a 1 minute window that all tasks were stalled", "type": "number" }, "io_pressure_full_total_us": { "description": "Total stall time (microseconds)", "type": "number" }, "io_pressure_some_10s": { "description": "Percentage of time over a 10 second window that some tasks were stalled", "type": "number" }, "io_pressure_some_300s": { "description": "Percentage of time over a 3 minute window that some tasks were stalled", "type": "number" }, "io_pressure_some_60s": { "description": "Percentage of time over a 1 minute window that some tasks were stalled", "type": "number" }, "io_pressure_some_total_us": { "description": "Total stall time (microseconds)", "type": "number" }, "kernel_btime": { "description": "Boot time (seconds since Unix epoch)", "type": "number" }, "kernel_ctxt": { "description": "Number of context switches that the system underwent", "type": "number" }, "kernel_processes": { "description": "Number of forks since boot", "type": "number" }, "kernel_processes_blocked": { "description": "Number of processes blocked waiting for I/O", "type": "number" }, "kernel_processes_running": { "description": "Number of processes in runnable state", "type": "number" }, "load_average_15m": { "description": "The fifteen-minute load average", "type": "number" }, "load_average_1m": { "description": "The one-minute load average", "type": "number" }, "load_average_5m": { "description": "The five-minute load average", "type": "number" }, "load_average_cur": { "description": "Number of currently runnable kernel scheduling entities", "type": "number" }, "load_average_max": { "description": "Number of kernel scheduling entities that currently exist on the system", "type": "number" }, "memory_active_bytes": { "description": "Memory that has been used more recently", "type": "number" }, "memory_anon_hugepages_bytes": { "description": "Non-file backed huge pages mapped into user-space page tables", "type": "number" }, "memory_anon_pages_bytes": { "description": "Non-file backed pages mapped into user-space page tables", "type": "number" }, "memory_available_bytes": { "description": "Estimate of how much memory is available for starting new applications", "type": "number" }, "memory_bounce_bytes": { "description": "Memory used for block device bounce buffers", "type": "number" }, "memory_buffers_bytes": { "description": "Relatively temporary storage for raw disk blocks", "type": "number" }, "memory_cached_bytes": { "description": "In-memory cache for files read from the disk", "type": "number" }, "memory_cma_free_bytes": { "description": "Free CMA (Contiguous Memory Allocator) pages", "type": "number" }, "memory_cma_total_bytes": { "description": "Total CMA (Contiguous Memory Allocator) pages", "type": "number" }, "memory_commit_limit_bytes": { "description": "Total amount of memory currently available to be allocated on the system", "type": "number" }, "memory_committed_as_bytes": { "description": "Amount of memory presently allocated on the system", "type": "number" }, "memory_dirty_bytes": { "description": "Memory which is waiting to get written back to the disk", "type": "number" }, "memory_free_bytes": { "description": "The sum of LowFree and HighFree", "type": "number" }, "memory_high_free_bytes": { "description": "Amount of free highmem", "type": "number" }, "memory_high_total_bytes": { "description": "Total amount of highmem", "type": "number" }, "memory_hugepages_free": { "description": "The number of huge pages in the pool that are not yet allocated", "type": "number" }, "memory_hugepages_rsvd": { "description": "Number of huge pages for which a commitment has been made, but no allocation has yet been made", "type": "number" }, "memory_hugepages_surp": { "description": "Number of huge pages in the pool above the threshold", "type": "number" }, "memory_hugepages_total": { "description": "The size of the pool of huge pages", "type": "number" }, "memory_hugepagesize_bytes": { "description": "The size of huge pages", "type": "number" }, "memory_inactive_bytes": { "description": "Memory which has been less recently used", "type": "number" }, "memory_k_reclaimable_bytes": { "description": "Kernel allocations that the kernel will attempt to reclaim under memory pressure", "type": "number" }, "memory_kernel_stack_bytes": { "description": "Amount of memory allocated to kernel stacks", "type": "number" }, "memory_low_free_bytes": { "description": "Amount of free lowmem", "type": "number" }, "memory_low_total_bytes": { "description": "Total amount of lowmem", "type": "number" }, "memory_mapped_bytes": { "description": "Files which have been mapped into memory", "type": "number" }, "memory_page_tables_bytes": { "description": "Amount of memory dedicated to the lowest level of page tables", "type": "number" }, "memory_per_cpu_bytes": { "description": "Memory allocated to the per-cpu alloctor used to back per-cpu allocations", "type": "number" }, "memory_pressure_full_10s": { "description": "Percentage of time over a 10 second window that all tasks were stalled", "type": "number" }, "memory_pressure_full_300s": { "description": "Percentage of time over a 5 minute window that all tasks were stalled", "type": "number" }, "memory_pressure_full_60s": { "description": "Percentage of time over a 1 minute window that all tasks were stalled", "type": "number" }, "memory_pressure_full_total_us": { "description": "Total stall time (microseconds)", "type": "number" }, "memory_pressure_some_10s": { "description": "Percentage of time over a 10 second window that some tasks were stalled", "type": "number" }, "memory_pressure_some_300s": { "description": "Percentage of time over a 5 minute window that some tasks were stalled", "type": "number" }, "memory_pressure_some_60s": { "description": "Percentage of time over a 1 minute window that some tasks were stalled", "type": "number" }, "memory_pressure_some_total_us": { "description": "Total stall time (microseconds)", "type": "number" }, "memory_s_reclaimable_bytes": { "description": "Part of slab that can be reclaimed on memory pressure", "type": "number" }, "memory_s_unreclaim_bytes": { "description": "Part of slab that cannot be reclaimed on memory pressure", "type": "number" }, "memory_secondary_page_tables_bytes": { "description": "Amount of memory dedicated to the lowest level of page tables", "type": "number" }, "memory_shmem_bytes": { "description": "Amount of memory consumed by tmpfs", "type": "number" }, "memory_shmem_hugepages_bytes": { "description": "Memory used by shmem and tmpfs, allocated with huge pages", "type": "number" }, "memory_shmem_pmd_mapped_bytes": { "description": "Shared memory mapped into user space with huge pages", "type": "number" }, "memory_slab_bytes": { "description": "In-kernel data structures cache", "type": "number" }, "memory_swap_cached_bytes": { "description": "Memory swapped out and back in while still in swap file", "type": "number" }, "memory_swap_free_bytes": { "description": "Amount of swap space that is currently unused", "type": "number" }, "memory_swap_total_bytes": { "description": "Total amount of swap space available", "type": "number" }, "memory_total_bytes": { "description": "Total usable RAM", "type": "number" }, "memory_vmalloc_chunk_bytes": { "description": "Largest contiguous block of vmalloc area which is free", "type": "number" }, "memory_vmalloc_total_bytes": { "description": "Total size of vmalloc memory area", "type": "number" }, "memory_vmalloc_used_bytes": { "description": "Amount of vmalloc area which is used", "type": "number" }, "memory_writeback_bytes": { "description": "Memory which is actively being written back to the disk", "type": "number" }, "memory_writeback_tmp_bytes": { "description": "Memory used by FUSE for temporary writeback buffers", "type": "number" }, "memory_z_swap_bytes": { "description": "Memory consumed by the zswap backend, compressed", "type": "number" }, "memory_z_swapped_bytes": { "description": "Amount of anonymous memory stored in zswap, uncompressed", "type": "number" }, "mounts": { "type": "array", "items": { "$ref": "#/components/schemas/mconn-telemetry_snapshot_mount" } }, "netdevs": { "type": "array", "items": { "$ref": "#/components/schemas/mconn-telemetry_snapshot_netdev" } }, "platform": { "description": "Platform identifier", "type": "string" }, "routes": { "type": "array", "items": { "$ref": "#/components/schemas/mconn-telemetry_snapshot_route" } }, "site_id": { "description": "Site identifier", "type": "string" }, "snmp_icmp_in_addr_mask_reps": { "description": "Number of ICMP Address Mask Reply messages received", "type": "number" }, "snmp_icmp_in_addr_masks": { "description": "Number of ICMP Address Mask Request messages received", "type": "number" }, "snmp_icmp_in_csum_errors": { "description": "Number of ICMP messages received with bad checksums", "type": "number" }, "snmp_icmp_in_dest_unreachs": { "description": "Number of ICMP Destination Unreachable messages received", "type": "number" }, "snmp_icmp_in_echo_reps": { "description": "Number of ICMP Echo Reply messages received", "type": "number" }, "snmp_icmp_in_echos": { "description": "Number of ICMP Echo (request) messages received", "type": "number" }, "snmp_icmp_in_errors": { "description": "Number of ICMP messages received with ICMP-specific errors", "type": "number" }, "snmp_icmp_in_msgs": { "description": "Number of ICMP messages received", "type": "number" }, "snmp_icmp_in_parm_probs": { "description": "Number of ICMP Parameter Problem messages received", "type": "number" }, "snmp_icmp_in_redirects": { "description": "Number of ICMP Redirect messages received", "type": "number" }, "snmp_icmp_in_src_quenchs": { "description": "Number of ICMP Source Quench messages received", "type": "number" }, "snmp_icmp_in_time_excds": { "description": "Number of ICMP Time Exceeded messages received", "type": "number" }, "snmp_icmp_in_timestamp_reps": { "description": "Number of ICMP Address Mask Request messages received", "type": "number" }, "snmp_icmp_in_timestamps": { "description": "Number of ICMP Timestamp (request) messages received", "type": "number" }, "snmp_icmp_out_addr_mask_reps": { "description": "Number of ICMP Address Mask Reply messages sent", "type": "number" }, "snmp_icmp_out_addr_masks": { "description": "Number of ICMP Address Mask Request messages sent", "type": "number" }, "snmp_icmp_out_dest_unreachs": { "description": "Number of ICMP Destination Unreachable messages sent", "type": "number" }, "snmp_icmp_out_echo_reps": { "description": "Number of ICMP Echo Reply messages sent", "type": "number" }, "snmp_icmp_out_echos": { "description": "Number of ICMP Echo (request) messages sent", "type": "number" }, "snmp_icmp_out_errors": { "description": "Number of ICMP messages which this entity did not send due to ICMP-specific errors", "type": "number" }, "snmp_icmp_out_msgs": { "description": "Number of ICMP messages attempted to send", "type": "number" }, "snmp_icmp_out_parm_probs": { "description": "Number of ICMP Parameter Problem messages sent", "type": "number" }, "snmp_icmp_out_redirects": { "description": "Number of ICMP Redirect messages sent", "type": "number" }, "snmp_icmp_out_src_quenchs": { "description": "Number of ICMP Source Quench messages sent", "type": "number" }, "snmp_icmp_out_time_excds": { "description": "Number of ICMP Time Exceeded messages sent", "type": "number" }, "snmp_icmp_out_timestamp_reps": { "description": "Number of ICMP Timestamp Reply messages sent", "type": "number" }, "snmp_icmp_out_timestamps": { "description": "Number of ICMP Timestamp (request) messages sent", "type": "number" }, "snmp_ip_default_ttl": { "description": "Default value of the Time-To-Live field of the IP header", "type": "number" }, "snmp_ip_forw_datagrams": { "description": "Number of datagrams forwarded to their final destination", "type": "number" }, "snmp_ip_forwarding_enabled": { "description": "Set when acting as an IP gateway", "type": "boolean" }, "snmp_ip_frag_creates": { "description": "Number of datagrams generated by fragmentation", "type": "number" }, "snmp_ip_frag_fails": { "description": "Number of datagrams discarded because fragmentation failed", "type": "number" }, "snmp_ip_frag_oks": { "description": "Number of datagrams successfully fragmented", "type": "number" }, "snmp_ip_in_addr_errors": { "description": "Number of input datagrams discarded due to errors in the IP address", "type": "number" }, "snmp_ip_in_delivers": { "description": "Number of input datagrams successfully delivered to IP user-protocols", "type": "number" }, "snmp_ip_in_discards": { "description": "Number of input datagrams otherwise discarded", "type": "number" }, "snmp_ip_in_hdr_errors": { "description": "Number of input datagrams discarded due to errors in the IP header", "type": "number" }, "snmp_ip_in_receives": { "description": "Number of input datagrams received from interfaces", "type": "number" }, "snmp_ip_in_unknown_protos": { "description": "Number of input datagrams discarded due unknown or unsupported protocol", "type": "number" }, "snmp_ip_out_discards": { "description": "Number of output datagrams otherwise discarded", "type": "number" }, "snmp_ip_out_no_routes": { "description": "Number of output datagrams discarded because no route matched", "type": "number" }, "snmp_ip_out_requests": { "description": "Number of datagrams supplied for transmission", "type": "number" }, "snmp_ip_reasm_fails": { "description": "Number of failures detected by the reassembly algorithm", "type": "number" }, "snmp_ip_reasm_oks": { "description": "Number of datagrams successfully reassembled", "type": "number" }, "snmp_ip_reasm_reqds": { "description": "Number of fragments received which needed to be reassembled", "type": "number" }, "snmp_ip_reasm_timeout": { "description": "Number of seconds fragments are held while awaiting reassembly", "type": "number" }, "snmp_tcp_active_opens": { "description": "Number of times TCP transitions to SYN-SENT from CLOSED", "type": "number" }, "snmp_tcp_attempt_fails": { "description": "Number of times TCP transitions to CLOSED from SYN-SENT or SYN-RCVD, plus transitions to LISTEN from SYN-RCVD", "type": "number" }, "snmp_tcp_curr_estab": { "description": "Number of TCP connections in ESTABLISHED or CLOSE-WAIT", "type": "number" }, "snmp_tcp_estab_resets": { "description": "Number of times TCP transitions to CLOSED from ESTABLISHED or CLOSE-WAIT", "type": "number" }, "snmp_tcp_in_csum_errors": { "description": "Number of TCP segments received with checksum errors", "type": "number" }, "snmp_tcp_in_errs": { "description": "Number of TCP segments received in error", "type": "number" }, "snmp_tcp_in_segs": { "description": "Number of TCP segments received", "type": "number" }, "snmp_tcp_max_conn": { "description": "Limit on the total number of TCP connections", "type": "number" }, "snmp_tcp_out_rsts": { "description": "Number of TCP segments sent with RST flag", "type": "number" }, "snmp_tcp_out_segs": { "description": "Number of TCP segments sent", "type": "number" }, "snmp_tcp_passive_opens": { "description": "Number of times TCP transitions to SYN-RCVD from LISTEN", "type": "number" }, "snmp_tcp_retrans_segs": { "description": "Number of TCP segments retransmitted", "type": "number" }, "snmp_tcp_rto_max": { "description": "Maximum value permitted by a TCP implementation for the retransmission timeout (milliseconds)", "type": "number" }, "snmp_tcp_rto_min": { "description": "Minimum value permitted by a TCP implementation for the retransmission timeout (milliseconds)", "type": "number" }, "snmp_udp_in_datagrams": { "description": "Number of UDP datagrams delivered to UDP applications", "type": "number" }, "snmp_udp_in_errors": { "description": "Number of UDP datagrams failed to be delivered for reasons other than lack of application at the destination port", "type": "number" }, "snmp_udp_no_ports": { "description": "Number of UDP datagrams received for which there was not application at the destination port", "type": "number" }, "snmp_udp_out_datagrams": { "description": "Number of UDP datagrams sent", "type": "number" }, "system_boot_time_s": { "description": "Boottime of the system (seconds since the Unix epoch)", "type": "number" }, "t": { "description": "Time the Snapshot was recorded (seconds since the Unix epoch)", "type": "number" }, "thermals": { "type": "array", "items": { "$ref": "#/components/schemas/mconn-telemetry_snapshot_thermal" } }, "tunnels": { "type": "array", "items": { "$ref": "#/components/schemas/mconn-telemetry_snapshot_tunnel" } }, "uptime_idle_ms": { "description": "Sum of how much time each core has spent idle", "type": "number" }, "uptime_total_ms": { "description": "Uptime of the system, including time spent in suspend", "type": "number" }, "v": { "description": "Version", "type": "string" } }, "required": [ "t", "v", "count_reclaim_failures", "count_reclaimed_paths", "count_record_failed", "count_transmit_failures" ] }, "mconn-telemetry_snapshot_bond": { "description": "Snapshot Bond", "type": "object", "properties": { "name": { "description": "Name of the network interface", "type": "string" }, "status": { "description": "Current status of the network interface", "type": "string" } }, "required": [ "name", "status" ] }, "mconn-telemetry_snapshot_dhcp_lease": { "description": "Snapshot DHCP lease", "type": "object", "properties": { "client_id": { "description": "Client ID of the device the IP Address was leased to", "type": "string" }, "expiry_time": { "description": "Expiry time of the DHCP lease (seconds since the Unix epoch)", "type": "number" }, "hostname": { "description": "Hostname of the device the IP Address was leased to", "type": "string" }, "interface_name": { "description": "Name of the network interface", "type": "string" }, "ip_address": { "description": "IP Address that was leased", "type": "string" }, "mac_address": { "description": "MAC Address of the device the IP Address was leased to", "type": "string" } }, "required": [ "interface_name", "expiry_time", "mac_address", "ip_address", "hostname", "client_id" ] }, "mconn-telemetry_snapshot_disk": { "description": "Snapshot Disk", "type": "object", "properties": { "discards": { "description": "Discards completed successfully", "type": "number" }, "discards_merged": { "description": "Discards merged", "type": "number" }, "flushes": { "description": "Flushes completed successfully", "type": "number" }, "in_progress": { "description": "I/Os currently in progress", "type": "number" }, "major": { "description": "Device major number", "type": "number" }, "merged": { "description": "Reads merged", "type": "number" }, "minor": { "description": "Device minor number", "type": "number" }, "name": { "description": "Device name", "type": "string" }, "reads": { "description": "Reads completed successfully", "type": "number" }, "sectors_discarded": { "description": "Sectors discarded", "type": "number" }, "sectors_read": { "description": "Sectors read successfully", "type": "number" }, "sectors_written": { "description": "Sectors written successfully", "type": "number" }, "time_discarding_ms": { "description": "Time spent discarding (milliseconds)", "type": "number" }, "time_flushing_ms": { "description": "Time spent flushing (milliseconds)", "type": "number" }, "time_in_progress_ms": { "description": "Time spent doing I/Os (milliseconds)", "type": "number" }, "time_reading_ms": { "description": "Time spent reading (milliseconds)", "type": "number" }, "time_writing_ms": { "description": "Time spent writing (milliseconds)", "type": "number" }, "weighted_time_in_progress_ms": { "description": "Weighted time spent doing I/Os (milliseconds)", "type": "number" }, "writes": { "description": "Writes completed", "type": "number" }, "writes_merged": { "description": "Writes merged", "type": "number" } }, "required": [ "in_progress", "major", "merged", "minor", "name", "reads", "sectors_read", "sectors_written", "time_in_progress_ms", "time_reading_ms", "time_writing_ms", "weighted_time_in_progress_ms", "writes", "writes_merged" ] }, "mconn-telemetry_snapshot_interface": { "description": "Snapshot Interface", "type": "object", "properties": { "ip_addresses": { "type": "array", "items": { "$ref": "#/components/schemas/mconn-telemetry_snapshot_interface_address" } }, "name": { "description": "Name of the network interface", "type": "string" }, "operstate": { "description": "UP/DOWN state of the network interface", "type": "string" }, "speed": { "description": "Speed of the network interface (bits per second)", "type": "number" } }, "required": [ "name", "operstate" ] }, "mconn-telemetry_snapshot_interface_address": { "description": "Snapshot Interface Address", "type": "object", "properties": { "interface_name": { "description": "Name of the network interface", "type": "string" }, "ip_address": { "description": "IP address of the network interface", "type": "string" } }, "required": [ "interface_name", "ip_address" ] }, "mconn-telemetry_snapshot_metadata": { "type": "object", "properties": { "a": { "description": "Time the Snapshot was collected (seconds since the Unix epoch)", "type": "number" }, "t": { "description": "Time the Snapshot was recorded (seconds since the Unix epoch)", "type": "number" } }, "required": [ "a", "t" ] }, "mconn-telemetry_snapshot_mount": { "description": "Snapshot Mount", "type": "object", "properties": { "available_bytes": { "description": "Available disk size (bytes)", "type": "number" }, "available_inodes": { "description": "Available inodes on filesystem", "type": "number" }, "file_system": { "description": "File system on disk (EXT4, NTFS, etc.)", "type": "string" }, "is_read_only": { "description": "Determines whether the disk is read-only", "type": "boolean" }, "is_removable": { "description": "Determines whether the disk is removable", "type": "boolean" }, "kind": { "description": "Kind of disk (HDD, SSD, etc.)", "type": "string" }, "mount_point": { "description": "Path where disk is mounted", "type": "string" }, "name": { "description": "Name of the disk mount", "type": "string" }, "total_bytes": { "description": "Total disk size (bytes)", "type": "number" }, "total_inodes": { "description": "Total inodes on filesystem", "type": "number" } }, "required": [ "name", "kind", "file_system", "mount_point" ] }, "mconn-telemetry_snapshot_netdev": { "description": "Snapshot Netdev", "type": "object", "properties": { "name": { "description": "Name of the network device", "type": "string" }, "recv_bytes": { "description": "Total bytes received", "type": "number" }, "recv_compressed": { "description": "Compressed packets received", "type": "number" }, "recv_drop": { "description": "Packets dropped", "type": "number" }, "recv_errs": { "description": "Bad packets received", "type": "number" }, "recv_fifo": { "description": "FIFO overruns", "type": "number" }, "recv_frame": { "description": "Frame alignment errors", "type": "number" }, "recv_multicast": { "description": "Multicast packets received", "type": "number" }, "recv_packets": { "description": "Total packets received", "type": "number" }, "sent_bytes": { "description": "Total bytes transmitted", "type": "number" }, "sent_carrier": { "description": "Number of packets not sent due to carrier errors", "type": "number" }, "sent_colls": { "description": "Number of collisions", "type": "number" }, "sent_compressed": { "description": "Number of compressed packets transmitted", "type": "number" }, "sent_drop": { "description": "Number of packets dropped during transmission", "type": "number" }, "sent_errs": { "description": "Number of transmission errors", "type": "number" }, "sent_fifo": { "description": "FIFO overruns", "type": "number" }, "sent_packets": { "description": "Total packets transmitted", "type": "number" } }, "required": [ "name", "recv_bytes", "recv_packets", "recv_errs", "recv_drop", "recv_fifo", "recv_frame", "recv_compressed", "recv_multicast", "sent_bytes", "sent_packets", "sent_errs", "sent_drop", "sent_fifo", "sent_colls", "sent_carrier", "sent_compressed" ] }, "mconn-telemetry_snapshot_route": { "description": "Snapshot Route", "type": "object", "properties": { "destination": { "description": "Route destination as default or an IPv4 CIDR", "type": "string" }, "gateway": { "description": "Gateway address for the next hop", "type": "string" }, "interface_name": { "description": "Interface used by the next hop", "type": "string" }, "kind": { "description": "Routing decision type: tunnel, breakout, or lan", "type": "string" }, "metric": { "description": "Route metric; lower metrics are preferred", "type": "number" }, "weight": { "description": "Relative weight within an equal-cost route", "type": "number" } }, "required": [ "kind", "destination", "metric", "interface_name" ] }, "mconn-telemetry_snapshot_thermal": { "description": "Snapshot Thermal", "type": "object", "properties": { "critical_celcius": { "description": "Critical failure temperature of the component (degrees Celsius)", "type": "number" }, "current_celcius": { "description": "Current temperature of the component (degrees Celsius)", "type": "number" }, "label": { "description": "Sensor identifier for the component", "type": "string" }, "max_celcius": { "description": "Maximum temperature of the component (degrees Celsius)", "type": "number" } }, "required": [ "label" ] }, "mconn-telemetry_snapshot_tunnel": { "description": "Snapshot Tunnels", "type": "object", "properties": { "health_state": { "description": "Name of tunnel health state (unknown, healthy, degraded, down)", "type": "string" }, "health_value": { "description": "Numeric value associated with tunnel state (0 = unknown, 1 = healthy, 2 = degraded, 3 = down)", "type": "number" }, "interface_name": { "description": "The tunnel interface name (i.e. xfrm1, xfrm3.99, etc.)", "type": "string" }, "jitter_ms": { "description": "Tunnel round-trip latency variation in milliseconds", "type": "number" }, "latency_ms": { "description": "50th percentile tunnel round-trip latency in milliseconds", "type": "number" }, "natd_result": { "description": "Public socket address returned by the NAT detector", "type": "string" }, "natd_state": { "description": "Numeric NAT detector state (0 = detected, 1 = missing result, 2 = stale result)", "type": "number" }, "natd_target": { "description": "Target socket address probed by the NAT detector, using the detector source port", "type": "string" }, "probed_mtu": { "description": "MTU as measured between the two ends of the tunnel", "type": "number" }, "recent_healthy_pings": { "description": "Number of recent healthy pings for this tunnel", "type": "number" }, "recent_unhealthy_pings": { "description": "Number of recent unhealthy pings for this tunnel", "type": "number" }, "tunnel_id": { "description": "Tunnel identifier", "type": "string" } }, "required": [ "tunnel_id", "interface_name", "health_state", "health_value" ] }, "mconn_account_id": { "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "mconn_bad_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn_response" }, { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/mconn_coded_message" }, "minLength": 1 }, "result": { "$ref": "#/components/schemas/mconn_none" } }, "type": "object" } ] }, "mconn_coded_message": { "type": "object", "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "mconn_connector_interrupts_create_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mconn_connector_interrupts_result" } }, "type": "object" } ] }, "mconn_connector_interrupts_list_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn_good_response" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/mconn_connector_interrupts_result" } } }, "type": "object" } ] }, "mconn_connector_interrupts_result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn_interrupt" }, { "properties": { "submitted_at": { "type": "string" }, "triggered_at": { "type": "string" } }, "required": [ "submitted_at" ], "type": "object" } ] }, "mconn_customer_connector": { "type": "object", "properties": { "activated": { "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "device": { "$ref": "#/components/schemas/mconn_customer_device" }, "id": { "$ref": "#/components/schemas/mconn_uuid" }, "interrupt_window_days_of_week": { "description": "Allowed days of the week for upgrades. Default is all days.", "type": "array", "items": { "$ref": "#/components/schemas/mconn_day_of_week" }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "interrupt_window_duration_hours": { "type": "number", "maximum": 24, "minimum": 1, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "interrupt_window_embargo_dates": { "description": "List of dates (YYYY-MM-DD) when upgrades are blocked.", "type": "array", "items": { "$ref": "#/components/schemas/mconn_embargo_date" }, "maxItems": 100, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "interrupt_window_hour_of_day": { "type": "number", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "last_heartbeat": { "type": "string", "x-auditable": true }, "last_seen_version": { "type": "string", "x-auditable": true }, "last_updated": { "type": "string", "x-auditable": true }, "license_key": { "type": "string", "x-stainless-terraform-configurability": "computed_optional" }, "notes": { "type": "string", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "primary": { "type": "boolean", "default": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "site_id": { "type": "string", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "timezone": { "type": "string", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "id", "notes", "activated", "last_updated", "timezone", "interrupt_window_hour_of_day", "interrupt_window_duration_hours", "interrupt_window_days_of_week", "interrupt_window_embargo_dates", "primary" ] }, "mconn_customer_connector_fields": { "type": "object", "properties": { "activated": { "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "interrupt_window_days_of_week": { "description": "Allowed days of the week for upgrades. Default is all days.", "type": "array", "items": { "$ref": "#/components/schemas/mconn_day_of_week" }, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "interrupt_window_duration_hours": { "type": "number", "maximum": 24, "minimum": 1, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "interrupt_window_embargo_dates": { "description": "List of dates (YYYY-MM-DD) when upgrades are blocked.", "type": "array", "items": { "$ref": "#/components/schemas/mconn_embargo_date" }, "maxItems": 100, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "interrupt_window_hour_of_day": { "type": "number", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "notes": { "type": "string", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "primary": { "type": "boolean", "default": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "site_id": { "type": "string", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "timezone": { "type": "string", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } } }, "mconn_customer_connectors_create_request": { "type": "object", "allOf": [ { "properties": { "device": { "$ref": "#/components/schemas/mconn_customer_device_options" } }, "required": [ "device" ], "type": "object" }, { "$ref": "#/components/schemas/mconn_customer_connector_fields" } ] }, "mconn_customer_connectors_create_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mconn_customer_connector" } }, "type": "object" } ] }, "mconn_customer_connectors_delete_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mconn_customer_connector" } }, "type": "object" } ] }, "mconn_customer_connectors_edit_request": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn_customer_connector_fields" }, { "properties": { "provision_license": { "description": "When true, regenerate license key for the connector.", "type": "boolean" } }, "type": "object" } ] }, "mconn_customer_connectors_edit_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mconn_customer_connector" } }, "type": "object" } ] }, "mconn_customer_connectors_get_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mconn_customer_connector" } }, "type": "object" } ] }, "mconn_customer_connectors_list_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn_good_response" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/mconn_customer_connector" } } }, "type": "object" } ] }, "mconn_customer_connectors_update_request": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn_customer_connector_fields" }, { "properties": { "provision_license": { "description": "When true, regenerate license key for the connector.", "type": "boolean" } }, "type": "object" } ] }, "mconn_customer_connectors_update_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn_good_response" }, { "properties": { "result": { "$ref": "#/components/schemas/mconn_customer_connector" } }, "type": "object" } ] }, "mconn_customer_device": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/mconn_uuid" }, "serial_number": { "type": "string", "x-auditable": true }, "type": { "type": "string", "enum": [ "MANAGED", "LICENSED" ], "x-auditable": true } }, "required": [ "id" ] }, "mconn_customer_device_options": { "description": "Exactly one of id, serial_number, or provision_license must be provided.", "type": "object", "properties": { "id": { "type": "string", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "provision_license": { "description": "When true, create and provision a new licence key for the connector.", "type": "boolean" }, "serial_number": { "type": "string", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "maxProperties": 1, "minProperties": 1 }, "mconn_day_of_week": { "type": "string", "enum": [ "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday" ] }, "mconn_embargo_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "mconn_good_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/mconn_response" }, { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/mconn_coded_message" }, "maxLength": 0 } }, "type": "object" } ] }, "mconn_interrupt": { "description": "Interrupt action for a connector.", "type": "object", "properties": { "reboot": { "type": "object", "additionalProperties": false, "properties": { "purge": { "description": "Purge connector state.", "type": "boolean", "default": false } } }, "restart": { "type": "object", "additionalProperties": false, "properties": { "purge": { "description": "Purge connector state.", "type": "boolean", "default": false } } }, "shutdown": { "type": "object", "additionalProperties": false, "properties": { "purge": { "description": "Purge connector state.", "type": "boolean", "default": false } } } }, "additionalProperties": false, "maxProperties": 1, "minProperties": 1 }, "mconn_none": { "type": "object", "nullable": true }, "mconn_response": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/mconn_coded_message" } }, "success": { "type": "boolean" } }, "required": [ "result", "success", "errors", "messages" ] }, "mconn_uuid": { "type": "string", "x-auditable": true }, "monolith_health_response": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/monolith_message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/monolith_message" } }, "result": { "$ref": "#/components/schemas/monolith_health_result" }, "success": { "type": "boolean" } }, "required": [ "result", "success", "errors", "messages" ] }, "monolith_health_result": { "type": "object", "properties": { "healthy": { "description": "Whether the API monolith is healthy.", "type": "boolean" } }, "required": [ "healthy" ] }, "monolith_message": { "type": "object", "properties": { "code": { "type": "integer", "format": "int64" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "moq_account_identifier": { "description": "Cloudflare account identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353" }, "moq_api-response-common": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "type": "object" } }, "messages": { "type": "array", "items": { "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "type": "object" } }, "success": { "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages" ] }, "moq_api-response-error": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "description": "Error codes:\n- 21001: Request body too large (HTTP 413)\n- 21002: Request body too small / missing name (HTTP 400)\n- 21003: Relay ID should be 32 hex characters (HTTP 400)\n- 21004: Failed to decode body — invalid JSON (HTTP 400)\n- 21005: Failed to read body (HTTP 400)\n- 21006: Unexpected server error (HTTP 500)\n- 21007: Relay not found (HTTP 404)\n- 21008: Relay limit exceeded for this account (HTTP 409)\n- 21009: Token limit reached — max 10 tokens per relay (HTTP 409)\n- 21010: Invalid operations — must be a non-empty subset of \"publish\" and \"subscribe\" (HTTP 400)\n- 21011: Invalid relay name — name must not be empty (HTTP 400)\n- 21012: Token expiry too long — expires must be no more than 1 year out (HTTP 400)\n- 21013: Invalid upstream URL — must be an absolute moqt:// or https:// URL with a host (HTTP 400)\n- 21014: Config cannot be set on create — set it via PUT after the relay exists (HTTP 400)\n", "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "example": [ { "code": 21007, "message": "A MoQ relay with this ID was not found." } ] }, "messages": { "type": "array", "items": { "type": "object" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "example": false } }, "required": [ "success", "errors", "messages" ] }, "moq_cloudflare_jwt_issuer": { "description": "Cloudflare-managed, Ed25519-signed JWT tokens (the only V1 type).", "type": "object", "properties": { "cloudflare_tokens": { "description": "Always present ([] when empty).", "type": "array", "items": { "$ref": "#/components/schemas/moq_cloudflare_jwt_token" } }, "issuer": { "type": "string", "enum": [ "cloudflare" ] }, "type": { "type": "string", "enum": [ "cloudflare_jwt" ] } }, "required": [ "type", "issuer", "cloudflare_tokens" ] }, "moq_cloudflare_jwt_token": { "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "expires": { "description": "Mandatory; no more than 1 year after `created`.", "type": "string", "format": "date-time" }, "jti": { "description": "Token identity and registry key (32 hex chars).", "type": "string", "example": "f3a1b2c3d4e5f67890a1b2c3d4e5f678" }, "label": { "description": "Optional, customer-set.", "type": "string", "example": "primary-encoder" }, "operations": { "description": "Signed allowlist of what the token may do. V1 coarse roles; the array\nform extends to fine-grained MoQT message names later without a\nbreaking change.\n", "type": "array", "items": { "enum": [ "publish", "subscribe" ], "type": "string" }, "example": [ "publish", "subscribe" ], "minItems": 1 }, "secret": { "description": "The signed JWT. Present ONLY in create / auto-create responses (shown\nonce); never returned by list, never stored.\n", "type": "string", "example": "eyJhbGciOiJFZDI1NTE5...", "x-sensitive": true } }, "required": [ "jti", "operations", "created", "expires" ] }, "moq_issuer": { "description": "One arm of the discriminated-union token collection.", "discriminator": { "mapping": { "cloudflare_jwt": "#/components/schemas/moq_cloudflare_jwt_issuer" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/moq_cloudflare_jwt_issuer" } ] }, "moq_relay": { "description": "Full relay details (no tokens).", "type": "object", "properties": { "config": { "$ref": "#/components/schemas/moq_relay_config" }, "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" }, "name": { "type": "string", "example": "Production Live Stream" }, "status": { "description": "\"connected\" when active, omitted otherwise.", "type": "string", "enum": [ "connected" ] }, "uid": { "type": "string", "example": "a1b2c3d4e5f67890a1b2c3d4e5f67890" } }, "required": [ "uid", "created", "modified", "name", "config" ] }, "moq_relay_config": { "type": "object", "properties": { "upstreams": { "$ref": "#/components/schemas/moq_upstreams" } } }, "moq_relay_create_response": { "description": "Relay with its auto-created default token pair (one full-access\n[publish, subscribe] and one [subscribe]-only), each with its one-time\nsecret, wrapped in the issuers envelope.\n", "type": "object", "properties": { "config": { "$ref": "#/components/schemas/moq_relay_config" }, "created": { "type": "string", "format": "date-time" }, "issuers": { "description": "Token collection (discriminated union on `type`). On create this\nholds the auto-created default pair, each including its one-time\nsecret.\n", "type": "array", "items": { "$ref": "#/components/schemas/moq_issuer" } }, "modified": { "type": "string", "format": "date-time" }, "name": { "type": "string", "example": "Production Live Stream" }, "uid": { "description": "Server-generated unique identifier (32 hex chars).", "type": "string", "example": "a1b2c3d4e5f67890a1b2c3d4e5f67890" } }, "required": [ "uid", "created", "modified", "name", "issuers", "config" ] }, "moq_relay_list_item": { "description": "Abbreviated relay for list responses.", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "uid": { "type": "string", "example": "a1b2c3d4e5f67890a1b2c3d4e5f67890" } }, "required": [ "uid", "created", "modified", "name" ] }, "moq_result_info": { "type": "object", "properties": { "count": { "type": "integer" }, "total": { "type": "integer" } } }, "moq_tokens_envelope": { "description": "A relay's token collection, keyed on issuer `type` (a discriminated\nunion). V1 ships exactly one arm (`cloudflare_jwt`). Clients iterate\n`issuers`, switch on `type`, and ignore unknown types — that contract is\nwhat makes adding or removing an arm non-breaking.\n", "type": "object", "properties": { "issuers": { "type": "array", "items": { "$ref": "#/components/schemas/moq_issuer" } } }, "required": [ "issuers" ] }, "moq_upstream": { "description": "A single upstream MOQT server publisher.", "type": "object", "properties": { "url": { "description": "Upstream MOQT server publisher URL. Must be an absolute URL with a\nhost and a scheme the relay can dial: moqt:// (raw QUIC) or https://\n(WebTransport). Validated on update (PUT); rejected with 21013.\n", "type": "string", "format": "uri" } }, "required": [ "url" ] }, "moq_upstreams": { "description": "Upstreams are external MOQT server publishers that a relay falls back\nto when it has no local publisher for a requested namespace/track.\n", "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "upstreams": { "description": "Ordered list of upstream MOQT server publishers. Each entry is an\nobject (not a bare string) so per-upstream configuration can be\nadded in the future without another breaking change.\n", "type": "array", "items": { "$ref": "#/components/schemas/moq_upstream" }, "default": [] } } }, "mq_api-v4-error": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000, "x-auditable": true }, "message": { "type": "string", "x-auditable": true } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [ { "code": 7003, "message": "No route for the URI" } ], "minLength": 1 }, "mq_api-v4-failure": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/mq_api-v4-error" }, "messages": { "$ref": "#/components/schemas/mq_api-v4-message" }, "success": { "description": "Indicates if the API call was successful or not.", "type": "boolean", "example": false, "enum": [ false ], "x-auditable": true } } }, "mq_api-v4-message": { "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [] }, "mq_api-v4-success": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/mq_api-v4-error" }, "messages": { "$ref": "#/components/schemas/mq_api-v4-message" }, "success": { "description": "Indicates if the API call was successful or not.", "type": "boolean", "enum": [ true ], "x-auditable": true } } }, "mq_batch-size": { "description": "The maximum number of messages to include in a batch.", "type": "number", "example": 50, "x-auditable": true }, "mq_consumer-request": { "description": "Request body for creating or updating a consumer", "type": "object", "discriminator": { "mapping": { "http_pull": "#/components/schemas/mq_http-consumer-request", "worker": "#/components/schemas/mq_worker-consumer-request" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/mq_worker-consumer-request" }, { "$ref": "#/components/schemas/mq_http-consumer-request" } ] }, "mq_consumer-response": { "description": "Response body representing a consumer", "type": "object", "discriminator": { "mapping": { "http_pull": "#/components/schemas/mq_http-consumer-response", "worker": "#/components/schemas/mq_worker-consumer-response" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/mq_worker-consumer-response" }, { "$ref": "#/components/schemas/mq_http-consumer-response" } ] }, "mq_event-destination": { "description": "Destination configuration for the subscription", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/mq_event-destination-queue" } ] }, "mq_event-destination-queue": { "type": "object", "properties": { "queue_id": { "description": "ID of the target queue", "type": "string", "x-auditable": true }, "type": { "description": "Type of destination", "type": "string", "enum": [ "queues.queue" ], "x-auditable": true } }, "required": [ "type", "queue_id" ] }, "mq_event-source": { "description": "Source configuration for the subscription", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/mq_event-source-images" }, { "$ref": "#/components/schemas/mq_event-source-kv" }, { "$ref": "#/components/schemas/mq_event-source-r2" }, { "$ref": "#/components/schemas/mq_event-source-super-slurper" }, { "$ref": "#/components/schemas/mq_event-source-vectorize" }, { "$ref": "#/components/schemas/mq_event-source-workers-ai-model" }, { "$ref": "#/components/schemas/mq_event-source-workers-builds-worker" }, { "$ref": "#/components/schemas/mq_event-source-workers-script" }, { "$ref": "#/components/schemas/mq_event-source-workflows-workflow" } ] }, "mq_event-source-images": { "type": "object", "properties": { "type": { "description": "Type of source", "type": "string", "enum": [ "images" ], "x-auditable": true } } }, "mq_event-source-kv": { "type": "object", "properties": { "type": { "description": "Type of source", "type": "string", "enum": [ "kv" ], "x-auditable": true } } }, "mq_event-source-r2": { "type": "object", "properties": { "type": { "description": "Type of source", "type": "string", "enum": [ "r2" ], "x-auditable": true } } }, "mq_event-source-super-slurper": { "type": "object", "properties": { "type": { "description": "Type of source", "type": "string", "enum": [ "superSlurper" ], "x-auditable": true } } }, "mq_event-source-vectorize": { "type": "object", "properties": { "type": { "description": "Type of source", "type": "string", "enum": [ "vectorize" ], "x-auditable": true } } }, "mq_event-source-workers-ai-model": { "type": "object", "properties": { "model_name": { "description": "Name of the Workers AI model", "type": "string", "x-auditable": true }, "type": { "description": "Type of source", "type": "string", "enum": [ "workersAi.model" ], "x-auditable": true } } }, "mq_event-source-workers-builds-worker": { "type": "object", "properties": { "type": { "description": "Type of source", "type": "string", "enum": [ "workersBuilds.worker" ], "x-auditable": true }, "worker_name": { "description": "Name of the worker", "type": "string", "x-auditable": true } } }, "mq_event-source-workers-script": { "type": "object", "properties": { "script_tag": { "description": "Tag of the Worker script", "type": "string", "x-auditable": true }, "type": { "description": "Type of source", "type": "string", "enum": [ "workers.script" ], "x-auditable": true } } }, "mq_event-source-workflows-workflow": { "type": "object", "properties": { "type": { "description": "Type of source", "type": "string", "enum": [ "workflows.workflow" ], "x-auditable": true }, "workflow_name": { "description": "Name of the workflow", "type": "string", "x-auditable": true } } }, "mq_event-subscription": { "type": "object", "properties": { "created_at": { "description": "When the subscription was created", "type": "string", "format": "date-time", "x-auditable": true }, "destination": { "$ref": "#/components/schemas/mq_event-destination" }, "enabled": { "description": "Whether the subscription is active", "type": "boolean", "x-auditable": true }, "events": { "description": "List of event types this subscription handles", "type": "array", "items": { "type": "string" }, "minItems": 1, "x-auditable": true }, "id": { "description": "Unique identifier for the subscription", "type": "string", "x-auditable": true }, "modified_at": { "description": "When the subscription was last modified", "type": "string", "format": "date-time", "x-auditable": true }, "name": { "description": "Name of the subscription", "type": "string", "x-auditable": true }, "source": { "$ref": "#/components/schemas/mq_event-source" } }, "required": [ "id", "created_at", "modified_at", "name", "enabled", "source", "destination", "events" ] }, "mq_http-consumer-request": { "type": "object", "properties": { "dead_letter_queue": { "$ref": "#/components/schemas/mq_queue-name" }, "settings": { "type": "object", "properties": { "batch_size": { "$ref": "#/components/schemas/mq_batch-size" }, "max_retries": { "$ref": "#/components/schemas/mq_max-retries" }, "retry_delay": { "$ref": "#/components/schemas/mq_retry-delay" }, "visibility_timeout_ms": { "$ref": "#/components/schemas/mq_visibility-timeout" } } }, "type": { "type": "string", "enum": [ "http_pull" ], "x-auditable": true } }, "required": [ "type" ] }, "mq_http-consumer-response": { "type": "object", "properties": { "consumer_id": { "$ref": "#/components/schemas/mq_identifier" }, "created_on": { "type": "string", "format": "date-time", "x-auditable": true }, "dead_letter_queue": { "description": "Name of the dead letter queue, or empty string if not configured", "type": "string", "x-auditable": true }, "queue_name": { "$ref": "#/components/schemas/mq_queue-name" }, "settings": { "type": "object", "properties": { "batch_size": { "$ref": "#/components/schemas/mq_batch-size" }, "max_retries": { "$ref": "#/components/schemas/mq_max-retries" }, "retry_delay": { "$ref": "#/components/schemas/mq_retry-delay" }, "visibility_timeout_ms": { "$ref": "#/components/schemas/mq_visibility-timeout" } } }, "type": { "type": "string", "enum": [ "http_pull" ], "x-auditable": true } } }, "mq_identifier": { "description": "A Resource identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "mq_jurisdiction": { "type": "string", "example": "eu", "enum": [ "eu", "us", "fedramp" ], "x-auditable": true }, "mq_lease-id": { "description": "An ID that represents an \"in-flight\" message that has been pulled from a Queue. You must hold on to this ID and use it to acknowledge this message.", "type": "string", "example": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIn0..Q8p21d7dceR6vUfwftONdQ.JVqZgAS-Zk7MqmqccYtTHeeMElNHaOMigeWdb8LyMOg.T2_HV99CYzGaQuhTyW8RsgbnpTRZHRM6N7UoSaAKeK0", "x-auditable": true }, "mq_max-concurrency": { "description": "Maximum number of concurrent consumers that may consume from this Queue. Set to `null` to automatically opt in to the platform's maximum (recommended).", "type": "number", "example": 10, "x-auditable": true }, "mq_max-retries": { "description": "The maximum number of retries", "type": "number", "example": 3, "x-auditable": true }, "mq_max-wait-time": { "description": "The number of milliseconds to wait for a batch to fill up before attempting to deliver it", "type": "number", "example": 5000, "x-auditable": true }, "mq_producer": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/mq_worker-producer" }, { "$ref": "#/components/schemas/mq_r2-producer" } ] }, "mq_queue": { "type": "object", "properties": { "consumers": { "type": "array", "items": { "$ref": "#/components/schemas/mq_consumer-response" }, "readOnly": true }, "consumers_total_count": { "type": "number", "readOnly": true }, "created_on": { "type": "string", "readOnly": true, "x-auditable": true }, "jurisdiction": { "$ref": "#/components/schemas/mq_jurisdiction" }, "modified_on": { "type": "string", "readOnly": true, "x-auditable": true }, "producers": { "type": "array", "items": { "$ref": "#/components/schemas/mq_producer" }, "readOnly": true }, "producers_total_count": { "type": "number", "readOnly": true, "x-auditable": true }, "queue_id": { "type": "string", "readOnly": true, "x-auditable": true }, "queue_name": { "$ref": "#/components/schemas/mq_queue-name" }, "settings": { "$ref": "#/components/schemas/mq_queue-settings" } } }, "mq_queue-batch": { "type": "object", "properties": { "delay_seconds": { "description": "The number of seconds to wait for attempting to deliver this batch to consumers", "type": "number", "example": "text", "x-auditable": true }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/mq_queue-message" } } } }, "mq_queue-message": { "allOf": [ { "properties": { "delay_seconds": { "description": "The number of seconds to wait for attempting to deliver this message to consumers", "type": "number", "example": "text", "x-auditable": true } }, "type": "object" }, { "oneOf": [ { "$ref": "#/components/schemas/mq_queue-message-text" }, { "$ref": "#/components/schemas/mq_queue-message-json" } ] } ] }, "mq_queue-message-json": { "type": "object", "properties": { "body": { "type": "object" }, "content_type": { "type": "string", "enum": [ "json" ], "x-auditable": true } } }, "mq_queue-message-text": { "type": "object", "properties": { "body": { "type": "string" }, "content_type": { "type": "string", "enum": [ "text" ], "x-auditable": true } } }, "mq_queue-metrics": { "description": "Best-effort metrics for the queue. Values may be approximate due to the distributed nature of queues.", "type": "object", "properties": { "backlog_bytes": { "description": "The size in bytes of unacknowledged messages in the queue.", "type": "number", "example": 1024, "x-auditable": true }, "backlog_count": { "description": "The number of unacknowledged messages in the queue.", "type": "number", "example": 5, "x-auditable": true }, "oldest_message_timestamp_ms": { "description": "Unix timestamp in milliseconds of the oldest unacknowledged message in the queue. Returns 0 if unknown.", "type": "number", "example": 1710950954154, "x-auditable": true } }, "required": [ "backlog_count", "backlog_bytes", "oldest_message_timestamp_ms" ] }, "mq_queue-name": { "type": "string", "example": "example-queue", "x-auditable": true }, "mq_queue-peek-batch": { "type": "array", "items": { "properties": { "attempts": { "type": "number", "example": 1, "readOnly": true, "x-auditable": true }, "body": { "type": "string", "example": "hello world", "readOnly": true }, "id": { "type": "string", "example": "b01b5594f784d0165c2985833f5660dd", "readOnly": true, "x-auditable": true }, "metadata": { "type": "object", "example": { "CF-Content-Type": "text", "CF-sourceMessageSource": "dash" }, "readOnly": true }, "ref": { "$ref": "#/components/schemas/mq_ref" }, "timestamp_ms": { "type": "number", "example": 1710950954154, "readOnly": true, "x-auditable": true } }, "type": "object" } }, "mq_queue-pull-batch": { "type": "array", "items": { "properties": { "attempts": { "type": "number", "example": 1, "readOnly": true, "x-auditable": true }, "body": { "type": "string", "example": "hello world", "readOnly": true }, "id": { "type": "string", "example": "b01b5594f784d0165c2985833f5660dd", "readOnly": true, "x-auditable": true }, "lease_id": { "$ref": "#/components/schemas/mq_lease-id" }, "metadata": { "type": "object", "example": { "CF-Content-Type": "text", "CF-sourceMessageSource": "dash" }, "readOnly": true }, "timestamp_ms": { "type": "number", "example": 1710950954154, "readOnly": true, "x-auditable": true } }, "type": "object" } }, "mq_queue-settings": { "type": "object", "properties": { "delivery_delay": { "description": "Number of seconds to delay delivery of all messages to consumers.", "type": "number", "example": 5, "x-auditable": true }, "delivery_paused": { "description": "Indicates if message delivery to consumers is currently paused.", "type": "boolean", "example": true, "x-auditable": true }, "message_retention_period": { "description": "Number of seconds after which an unconsumed message will be delayed.", "type": "number", "example": 345600, "x-auditable": true } } }, "mq_r2-producer": { "type": "object", "properties": { "bucket_name": { "type": "string", "x-auditable": true }, "type": { "type": "string", "enum": [ "r2_bucket" ], "x-auditable": true } } }, "mq_ref": { "description": "An opaque reference to a peeked message. You must hold on to this value and use it to purge the message.", "type": "string", "example": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIn0..Q8p21d7dceR6vUfwftONdQ.JVqZgAS-Zk7MqmqccYtTHeeMElNHaOMigeWdb8LyMOg.T2_HV99CYzGaQuhTyW8RsgbnpTRZHRM6N7UoSaAKeK0", "x-auditable": true }, "mq_retry-delay": { "description": "The number of seconds to delay before making the message available for another attempt.", "type": "number", "example": 10, "x-auditable": true }, "mq_script-name": { "description": "Name of a Worker", "type": "string", "example": "my-consumer-worker", "x-auditable": true }, "mq_visibility-timeout": { "description": "The number of milliseconds that a message is exclusively leased. After the timeout, the message becomes available for another attempt.", "type": "number", "example": 6000, "x-auditable": true }, "mq_worker-consumer-request": { "type": "object", "properties": { "dead_letter_queue": { "$ref": "#/components/schemas/mq_queue-name" }, "script_name": { "$ref": "#/components/schemas/mq_script-name" }, "settings": { "type": "object", "properties": { "batch_size": { "$ref": "#/components/schemas/mq_batch-size" }, "max_concurrency": { "$ref": "#/components/schemas/mq_max-concurrency" }, "max_retries": { "$ref": "#/components/schemas/mq_max-retries" }, "max_wait_time_ms": { "$ref": "#/components/schemas/mq_max-wait-time" }, "retry_delay": { "$ref": "#/components/schemas/mq_retry-delay" } } }, "type": { "type": "string", "enum": [ "worker" ], "x-auditable": true } }, "required": [ "type", "script_name" ] }, "mq_worker-consumer-response": { "type": "object", "properties": { "consumer_id": { "$ref": "#/components/schemas/mq_identifier" }, "created_on": { "type": "string", "format": "date-time", "x-auditable": true }, "dead_letter_queue": { "description": "Name of the dead letter queue, or empty string if not configured", "type": "string", "x-auditable": true }, "queue_name": { "$ref": "#/components/schemas/mq_queue-name" }, "script_name": { "$ref": "#/components/schemas/mq_script-name" }, "settings": { "type": "object", "properties": { "batch_size": { "$ref": "#/components/schemas/mq_batch-size" }, "max_concurrency": { "$ref": "#/components/schemas/mq_max-concurrency" }, "max_retries": { "$ref": "#/components/schemas/mq_max-retries" }, "max_wait_time_ms": { "$ref": "#/components/schemas/mq_max-wait-time" }, "retry_delay": { "$ref": "#/components/schemas/mq_retry-delay" } } }, "type": { "type": "string", "enum": [ "worker" ], "x-auditable": true } } }, "mq_worker-producer": { "type": "object", "properties": { "script": { "type": "string", "x-auditable": true }, "type": { "type": "string", "enum": [ "worker" ], "x-auditable": true } } }, "nel-config_api_message": { "description": "An API response message or error.", "type": "object", "properties": { "code": { "description": "Error or message code.", "type": "integer", "example": 1001 }, "message": { "description": "Human-readable message.", "type": "string", "example": "missing_value" } }, "required": [ "code", "message" ] }, "nel-config_api_response_failure": { "description": "API error response envelope.", "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/nel-config_api_message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/nel-config_api_message" }, "example": [] }, "result": { "description": "Always null for error responses.", "type": "object", "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false } }, "required": [ "success", "errors", "messages" ] }, "nel-config_nel_setting": { "description": "A zone-scoped NEL configuration setting.", "type": "object", "properties": { "editable": { "description": "Whether the setting is editable. This is false when the zone's plan does not include NEL or the NEL product feature is not enabled.\n", "type": "boolean", "example": true, "readOnly": true }, "id": { "description": "Zone setting identifier.", "type": "string", "example": "nel", "enum": [ "nel" ], "readOnly": true }, "modified_on": { "description": "When the setting was last modified. A zero value (0001-01-01T00:00:00Z) indicates the setting has never been explicitly set and is using the default value.\n", "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z", "readOnly": true }, "value": { "$ref": "#/components/schemas/nel-config_nel_value" } }, "required": [ "id", "editable", "value", "modified_on" ] }, "nel-config_nel_setting_patch": { "description": "Request body for updating the NEL setting.", "type": "object", "properties": { "value": { "$ref": "#/components/schemas/nel-config_nel_value" } }, "additionalProperties": false, "required": [ "value" ] }, "nel-config_nel_setting_response": { "description": "Response envelope for a single NEL setting.", "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/nel-config_api_message" }, "example": [] }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/nel-config_api_message" }, "example": [] }, "result": { "$ref": "#/components/schemas/nel-config_nel_setting" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true } }, "required": [ "success", "result", "errors", "messages" ] }, "nel-config_nel_value": { "description": "The NEL configuration value.", "type": "object", "properties": { "enabled": { "description": "Whether Network Error Logging is enabled for the zone. When enabled, browsers report network errors to Cloudflare's NEL endpoint.\n", "type": "boolean", "example": true } }, "required": [ "enabled" ] }, "nel-config_zone_identifier": { "description": "Identifier of the zone.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "nsc_AccountTag": { "description": "Customer account tag", "type": "string" }, "nsc_ApiBandwidth": { "description": "Bandwidth structure as visible through the customer-facing API.", "type": "string", "enum": [ "50M", "100M", "200M", "300M", "400M", "500M", "1G", "2G", "5G", "10G", "20G", "50G" ] }, "nsc_BgpControl": { "type": "object", "properties": { "customer_asn": { "description": "ASN used on the customer end of the BGP session", "type": "integer", "format": "int32", "minimum": 0 }, "extra_prefixes": { "description": "Extra set of static prefixes to advertise to the customer's end of the session", "type": "array", "items": { "format": "A.B.C.D/N", "type": "string" }, "example": "192.168.3.4/31" }, "md5_key": { "description": "MD5 key to use for session authentication.\n\nNote that *this is not a security measure*. MD5 is not a valid security mechanism, and the\nkey is not treated as a secret value. This is *only* supported for preventing\nmisconfiguration, not for defending against malicious attacks.\n\nThe MD5 key, if set, must be of non-zero length and consist only of the following types of\ncharacter:\n\n* ASCII alphanumerics: `[a-zA-Z0-9]`\n* Special characters in the set `'!@#$%^&*()+[]{}<>/.,;:_-~`= \\|`\n\nIn other words, MD5 keys may contain any printable ASCII character aside from newline\n(0x0A), quotation mark (`\"`), vertical tab (0x0B), carriage return (0x0D), tab (0x09),\nform feed (0x0C), and the question mark (`?`). Requests specifying an MD5 key with one\nor more of these disallowed characters will be rejected.", "type": "string", "nullable": true } }, "required": [ "customer_asn", "extra_prefixes" ] }, "nsc_BgpMode": { "description": "The BGP mode for a CNI.\n\nControls the customer-facing data path:\n* `DynamicRouteExchange` — Full BGP: routes flow through to conduit via CRE / bgp-bridge /\nbgp-bridge-receiver.\n* `AdvertiseOnly` — static advertisement via taserver, no routes exchanged with Conduit", "type": "string", "enum": [ "dynamic_route_exchange", "advertise_only" ] }, "nsc_CloudflareSite": { "description": "A Cloudflare site name.", "type": "string" }, "nsc_Cni": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/nsc_AccountTag" }, "bgp": { "$ref": "#/components/schemas/nsc_BgpControl" }, "bgp_mode": { "$ref": "#/components/schemas/nsc_BgpMode" }, "cust_ip": { "description": "Customer end of the point-to-point link\n\nThis should always be inside the same prefix as `p2p_ip`.", "type": "string", "format": "A.B.C.D/N", "example": "192.168.3.4/31" }, "id": { "type": "string", "format": "uuid" }, "interconnect": { "description": "Interconnect identifier hosting this CNI", "type": "string" }, "magic": { "$ref": "#/components/schemas/nsc_MagicSettings" }, "p2p_ip": { "description": "Cloudflare end of the point-to-point link", "type": "string", "format": "A.B.C.D/N", "example": "192.168.3.4/31" } }, "required": [ "id", "interconnect", "account", "p2p_ip", "cust_ip", "magic" ] }, "nsc_CniCreate": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/nsc_AccountTag" }, "bgp": { "$ref": "#/components/schemas/nsc_BgpControl" }, "interconnect": { "type": "string" }, "magic": { "$ref": "#/components/schemas/nsc_MagicSettings" } }, "required": [ "interconnect", "account", "magic" ] }, "nsc_CniList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/nsc_Cni" } }, "next": { "type": "integer", "format": "int32", "nullable": true } }, "required": [ "items" ] }, "nsc_DefaultNameResponse": { "type": "object", "properties": { "name": { "description": "The default customer name for the interconnect", "type": "string" } }, "required": [ "name" ] }, "nsc_FacilityInfo": { "type": "object", "properties": { "address": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" } }, "required": [ "name", "address" ] }, "nsc_Interconnect": { "type": "object", "discriminator": { "mapping": { "direct": "#/components/schemas/nsc_Interconnect_Physical_Body", "gcp_partner": "#/components/schemas/nsc_Interconnect_GcpPartner_Body" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/nsc_Interconnect_Physical_Body" }, { "$ref": "#/components/schemas/nsc_Interconnect_GcpPartner_Body" } ] }, "nsc_InterconnectCreate": { "type": "object", "discriminator": { "mapping": { "direct": "#/components/schemas/nsc_InterconnectCreate_Physical_Body", "gcp_partner": "#/components/schemas/nsc_InterconnectCreate_GcpPartner_Body" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/nsc_InterconnectCreate_Physical_Body" }, { "$ref": "#/components/schemas/nsc_InterconnectCreate_GcpPartner_Body" } ] }, "nsc_InterconnectCreate_GcpPartner_Body": { "type": "object", "allOf": [ { "properties": { "account": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "account" ], "type": "object" }, { "properties": { "bandwidth": { "$ref": "#/components/schemas/nsc_ApiBandwidth" }, "pairing_key": { "description": "Pairing key provided by GCP", "type": "string" } }, "required": [ "pairing_key", "bandwidth" ], "type": "object" } ], "title": "GcpPartner" }, "nsc_InterconnectCreate_Physical_Body": { "type": "object", "allOf": [ { "properties": { "account": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "account" ], "type": "object" }, { "properties": { "slot_id": { "type": "string", "format": "uuid" }, "speed": { "type": "string", "nullable": true } }, "required": [ "slot_id" ], "type": "object" } ], "title": "Physical" }, "nsc_InterconnectList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/nsc_Interconnect" } }, "next": { "type": "integer", "format": "int32", "nullable": true } }, "required": [ "items" ] }, "nsc_Interconnect_GcpPartner_Body": { "type": "object", "allOf": [ { "properties": { "account": { "type": "string" }, "name": { "type": "string" }, "owner": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "name", "account" ], "type": "object" }, { "properties": { "region": { "type": "string" }, "speed": { "$ref": "#/components/schemas/nsc_ApiBandwidth" }, "virtual_port_reservation_id": { "type": "string", "format": "uuid" } }, "required": [ "virtual_port_reservation_id", "region" ], "type": "object" } ], "title": "GcpPartner" }, "nsc_Interconnect_Physical_Body": { "type": "object", "allOf": [ { "properties": { "account": { "type": "string" }, "name": { "type": "string" }, "owner": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "name", "account" ], "type": "object" }, { "properties": { "ccr_device_name": { "type": "string", "nullable": true }, "facility": { "$ref": "#/components/schemas/nsc_FacilityInfo" }, "site": { "$ref": "#/components/schemas/nsc_CloudflareSite" }, "slot_id": { "type": "string", "format": "uuid" }, "speed": { "type": "string" }, "virtual_port_reservation_id": { "type": "string", "format": "uuid" } }, "required": [ "virtual_port_reservation_id", "slot_id", "site", "speed", "facility" ], "type": "object" } ], "title": "Physical" }, "nsc_MagicSettings": { "type": "object", "properties": { "conduit_name": { "type": "string" }, "description": { "type": "string" }, "mtu": { "type": "integer", "format": "int32", "minimum": 0 } }, "required": [ "conduit_name", "description", "mtu" ] }, "nsc_Settings": { "type": "object", "properties": { "default_asn": { "type": "integer", "format": "int32", "minimum": 0 } }, "required": [ "default_asn" ] }, "nsc_SettingsRequest": { "type": "object", "properties": { "default_asn": { "type": "integer", "format": "int32", "minimum": 0, "nullable": true } } }, "nsc_SlotInfo": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/nsc_AccountTag" }, "ccr_device_name": { "type": "string", "nullable": true }, "facility": { "$ref": "#/components/schemas/nsc_FacilityInfo" }, "id": { "description": "Slot ID", "type": "string", "format": "uuid" }, "occupied": { "description": "Whether the slot is occupied or not", "type": "boolean" }, "site": { "type": "string" }, "speed": { "type": "string" } }, "required": [ "id", "occupied", "site", "speed", "facility" ] }, "nsc_SlotList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/nsc_SlotInfo" } }, "next": { "type": "integer", "format": "int32", "nullable": true } }, "required": [ "items" ] }, "nsc_StatusInfo": { "type": "object", "discriminator": { "propertyName": "state" }, "oneOf": [ { "properties": { "state": { "type": "string", "enum": [ "Pending" ] } }, "required": [ "state" ], "type": "object" }, { "properties": { "reason": { "description": "Diagnostic information, if available", "type": "string", "nullable": true }, "state": { "type": "string", "enum": [ "Down" ] } }, "required": [ "state" ], "type": "object" }, { "properties": { "reason": { "description": "Diagnostic information, if available", "type": "string", "nullable": true }, "state": { "type": "string", "enum": [ "Unhealthy" ] } }, "required": [ "state" ], "type": "object" }, { "properties": { "state": { "type": "string", "enum": [ "Healthy" ] } }, "required": [ "state" ], "type": "object" } ] }, "observatory_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/observatory_api-response-common" } ] }, "observatory_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/observatory_messages" }, "messages": { "$ref": "#/components/schemas/observatory_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "x-auditable": true } }, "required": [ "success", "errors", "messages" ] }, "observatory_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/observatory_messages-2" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/observatory_messages-2" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "observatory_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/observatory_api-response-common" } ] }, "observatory_availabilities": { "type": "object", "properties": { "quota": { "type": "object", "properties": { "plan": { "description": "Cloudflare plan.", "type": "string", "example": "free", "x-auditable": true }, "quotasPerPlan": { "description": "The number of tests available per plan.", "type": "object", "properties": { "value": { "$ref": "#/components/schemas/observatory_plan-properties-info" } } }, "remainingSchedules": { "description": "The number of remaining schedules available.", "type": "number", "example": 1, "x-auditable": true }, "remainingTests": { "description": "The number of remaining tests available.", "type": "number", "example": 30, "x-auditable": true }, "scheduleQuotasPerPlan": { "description": "The number of schedules available per plan.", "type": "object", "properties": { "value": { "$ref": "#/components/schemas/observatory_plan-properties-info" } } } } }, "regions": { "type": "array", "items": { "$ref": "#/components/schemas/observatory_labeled_region" } }, "regionsPerPlan": { "description": "Available regions.", "type": "object", "properties": { "business": { "type": "array", "items": { "$ref": "#/components/schemas/observatory_labeled_region" } }, "enterprise": { "type": "array", "items": { "$ref": "#/components/schemas/observatory_labeled_region" } }, "free": { "type": "array", "items": { "$ref": "#/components/schemas/observatory_labeled_region" } }, "pro": { "type": "array", "items": { "$ref": "#/components/schemas/observatory_labeled_region" } } } } } }, "observatory_availabilities-response": { "allOf": [ { "$ref": "#/components/schemas/observatory_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/observatory_availabilities" } }, "type": "object" } ] }, "observatory_count-response": { "allOf": [ { "$ref": "#/components/schemas/observatory_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "count": { "description": "Number of items affected.", "type": "number", "example": 1, "x-auditable": true } } } }, "type": "object" } ] }, "observatory_create-schedule-response": { "allOf": [ { "$ref": "#/components/schemas/observatory_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "schedule": { "$ref": "#/components/schemas/observatory_schedule" }, "test": { "$ref": "#/components/schemas/observatory_page_test" } } } }, "type": "object" } ] }, "observatory_device_type": { "description": "The type of device.", "type": "string", "example": "DESKTOP", "enum": [ "DESKTOP", "MOBILE" ], "x-auditable": true }, "observatory_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "observatory_labeled_region": { "description": "A test region with a label.", "type": "object", "properties": { "label": { "type": "string", "example": "Iowa, USA", "x-auditable": true }, "value": { "$ref": "#/components/schemas/observatory_region" } } }, "observatory_lighthouse_error_code": { "description": "The error code of the Lighthouse result.", "type": "string", "example": "NOT_REACHABLE", "enum": [ "NOT_REACHABLE", "DNS_FAILURE", "NOT_HTML", "LIGHTHOUSE_TIMEOUT", "UNKNOWN" ], "x-auditable": true }, "observatory_lighthouse_report": { "description": "The Lighthouse report.", "type": "object", "properties": { "cls": { "description": "Cumulative Layout Shift.", "type": "number", "example": 100, "x-auditable": true }, "deviceType": { "$ref": "#/components/schemas/observatory_device_type" }, "error": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/observatory_lighthouse_error_code" }, "detail": { "description": "Detailed error message.", "type": "string", "example": "Details: net::ERR_CONNECTION_CLOSED", "x-auditable": true }, "finalDisplayedUrl": { "description": "The final URL displayed to the user.", "type": "string", "example": "example.com", "x-auditable": true } } }, "fcp": { "description": "First Contentful Paint.", "type": "number", "example": 100, "x-auditable": true }, "jsonReportUrl": { "description": "The URL to the full Lighthouse JSON report.", "type": "string", "x-auditable": true }, "lcp": { "description": "Largest Contentful Paint.", "type": "number", "example": 100, "x-auditable": true }, "performanceScore": { "description": "The Lighthouse performance score.", "type": "number", "example": 90, "x-auditable": true }, "si": { "description": "Speed Index.", "type": "number", "example": 100, "x-auditable": true }, "state": { "$ref": "#/components/schemas/observatory_lighthouse_state" }, "tbt": { "description": "Total Blocking Time.", "type": "number", "example": 100, "x-auditable": true }, "ttfb": { "description": "Time To First Byte.", "type": "number", "example": 100, "x-auditable": true }, "tti": { "description": "Time To Interactive.", "type": "number", "example": 100, "x-auditable": true } } }, "observatory_lighthouse_state": { "description": "The state of the Lighthouse report.", "type": "string", "example": "COMPLETE", "enum": [ "RUNNING", "COMPLETE", "FAILED" ], "x-auditable": true }, "observatory_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000, "x-auditable": true }, "message": { "type": "string", "x-auditable": true } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "observatory_messages-2": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "observatory_page-test-response-collection": { "allOf": [ { "$ref": "#/components/schemas/observatory_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/observatory_page_test" } } }, "type": "object" }, { "properties": { "result_info": { "$ref": "#/components/schemas/observatory_result_info" } }, "type": "object" } ] }, "observatory_page-test-response-single": { "allOf": [ { "$ref": "#/components/schemas/observatory_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/observatory_page_test" } }, "type": "object" } ] }, "observatory_page_test": { "type": "object", "properties": { "date": { "$ref": "#/components/schemas/observatory_timestamp" }, "desktopReport": { "$ref": "#/components/schemas/observatory_lighthouse_report" }, "id": { "$ref": "#/components/schemas/observatory_uuid" }, "mobileReport": { "$ref": "#/components/schemas/observatory_lighthouse_report" }, "region": { "$ref": "#/components/schemas/observatory_labeled_region" }, "scheduleFrequency": { "$ref": "#/components/schemas/observatory_schedule_frequency" }, "url": { "$ref": "#/components/schemas/observatory_url" } } }, "observatory_pages-response-collection": { "allOf": [ { "$ref": "#/components/schemas/observatory_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "properties": { "region": { "$ref": "#/components/schemas/observatory_labeled_region" }, "scheduleFrequency": { "$ref": "#/components/schemas/observatory_schedule_frequency" }, "tests": { "type": "array", "items": { "$ref": "#/components/schemas/observatory_page_test" } }, "url": { "$ref": "#/components/schemas/observatory_url" } }, "type": "object" } } }, "type": "object" } ] }, "observatory_plan-properties-info": { "description": "Counts per account plan.", "type": "object", "properties": { "business": { "type": "integer", "example": 1, "x-auditable": true }, "enterprise": { "type": "integer", "example": 1, "x-auditable": true }, "free": { "type": "integer", "example": 1, "x-auditable": true }, "pro": { "type": "integer", "example": 1, "x-auditable": true } } }, "observatory_region": { "description": "A test region.", "type": "string", "example": "us-central1", "enum": [ "asia-east1", "asia-northeast1", "asia-northeast2", "asia-south1", "asia-southeast1", "australia-southeast1", "europe-north1", "europe-southwest1", "europe-west1", "europe-west2", "europe-west3", "europe-west4", "europe-west8", "europe-west9", "me-west1", "southamerica-east1", "us-central1", "us-east1", "us-east4", "us-south1", "us-west1" ], "x-auditable": true }, "observatory_result_info": { "type": "object", "properties": { "count": { "type": "integer", "example": 5, "x-auditable": true }, "page": { "type": "integer", "example": 1, "x-auditable": true }, "per_page": { "type": "integer", "example": 5, "x-auditable": true }, "total_count": { "type": "integer", "example": 3, "x-auditable": true } } }, "observatory_schedule": { "description": "The test schedule.", "type": "object", "properties": { "frequency": { "$ref": "#/components/schemas/observatory_schedule_frequency" }, "region": { "$ref": "#/components/schemas/observatory_region" }, "url": { "$ref": "#/components/schemas/observatory_url" } } }, "observatory_schedule-response-single": { "allOf": [ { "$ref": "#/components/schemas/observatory_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/observatory_schedule" } }, "type": "object" } ] }, "observatory_schedule_frequency": { "description": "The frequency of the test.", "type": "string", "example": "DAILY", "enum": [ "DAILY", "WEEKLY" ], "x-auditable": true }, "observatory_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "x-auditable": true }, "observatory_trend": { "type": "object", "properties": { "cls": { "description": "Cumulative Layout Shift trend.", "type": "array", "items": { "nullable": true, "type": "number", "x-auditable": true } }, "fcp": { "description": "First Contentful Paint trend.", "type": "array", "items": { "nullable": true, "type": "number", "x-auditable": true } }, "lcp": { "description": "Largest Contentful Paint trend.", "type": "array", "items": { "nullable": true, "type": "number", "x-auditable": true } }, "performanceScore": { "description": "The Lighthouse score trend.", "type": "array", "items": { "nullable": true, "type": "number", "x-auditable": true } }, "si": { "description": "Speed Index trend.", "type": "array", "items": { "nullable": true, "type": "number", "x-auditable": true } }, "tbt": { "description": "Total Blocking Time trend.", "type": "array", "items": { "nullable": true, "type": "number", "x-auditable": true } }, "ttfb": { "description": "Time To First Byte trend.", "type": "array", "items": { "nullable": true, "type": "number", "x-auditable": true } }, "tti": { "description": "Time To Interactive trend.", "type": "array", "items": { "nullable": true, "type": "number", "x-auditable": true } } } }, "observatory_trend-response": { "allOf": [ { "$ref": "#/components/schemas/observatory_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/observatory_trend" } }, "type": "object" } ] }, "observatory_url": { "description": "A URL.", "type": "string", "example": "example.com", "x-auditable": true }, "observatory_uuid": { "description": "UUID.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "x-auditable": true }, "one_ApplicationDetail": { "description": "Full application detail for onboarding UI.", "type": "object", "properties": { "auth_methods": { "description": "Available authentication methods.", "type": "array", "items": { "$ref": "#/components/schemas/one_AuthMethod" } }, "category": { "description": "Vendor category.", "type": "string" }, "description": { "description": "Brief description.", "type": "string" }, "display_name": { "description": "Human-readable vendor name.", "type": "string" }, "dlp_enabled": { "description": "Whether DLP scanning is supported.", "type": "boolean" }, "id": { "description": "Vendor identifier.\n\n* `ANTHROPIC` - ANTHROPIC\n* `AWS` - AWS\n* `BITBUCKET` - BITBUCKET\n* `BOX` - BOX\n* `CONFLUENCE` - CONFLUENCE\n* `DROPBOX` - DROPBOX\n* `GITHUB` - GITHUB\n* `GOOGLE_CLOUD_PLATFORM` - GOOGLE_CLOUD_PLATFORM\n* `GOOGLE_WORKSPACE` - GOOGLE_WORKSPACE\n* `JIRA` - JIRA\n* `MICROSOFT_INTERNAL` - MICROSOFT_INTERNAL\n* `OPENAI` - OPENAI\n* `SALESFORCE` - SALESFORCE\n* `SERVICENOW` - SERVICENOW\n* `SLACK` - SLACK", "type": "string", "enum": [ "ANTHROPIC", "AWS", "BITBUCKET", "BOX", "CONFLUENCE", "DROPBOX", "GITHUB", "GOOGLE_CLOUD_PLATFORM", "GOOGLE_WORKSPACE", "JIRA", "MICROSOFT_INTERNAL", "OPENAI", "SALESFORCE", "SERVICENOW", "SLACK" ] }, "instructions": { "description": "Setup instructions for the user.", "type": "string", "nullable": true }, "logo": { "description": "Logo path.", "type": "string", "nullable": true }, "use_cases": { "description": "Use cases with full scope details.", "type": "array", "items": { "$ref": "#/components/schemas/one_UseCaseDetail" } } }, "required": [ "auth_methods", "category", "description", "display_name", "dlp_enabled", "id", "instructions", "logo", "use_cases" ] }, "one_ApplicationDetailResponse": { "type": "object", "properties": { "errors": { "description": "List of errors.", "type": "array", "items": { "additionalProperties": true, "type": "object" }, "default": [] }, "messages": { "description": "List of messages.", "type": "array", "items": { "type": "string" }, "default": [] }, "result": { "description": "The requested item.", "allOf": [ { "$ref": "#/components/schemas/one_ApplicationDetail" } ] }, "success": { "description": "Whether the request succeeded.", "type": "boolean" } }, "required": [ "result", "success" ] }, "one_ApplicationList": { "description": "Application item in list response.", "type": "object", "properties": { "auth_methods": { "description": "Available auth methods.", "type": "array", "items": { "$ref": "#/components/schemas/one_AuthMethodSummary" } }, "category": { "description": "Vendor category (e.g. Productivity, AI).", "type": "string" }, "description": { "description": "Brief description of the integration.", "type": "string" }, "display_name": { "description": "Human-readable vendor name.", "type": "string" }, "dlp_enabled": { "description": "Whether DLP scanning is supported.", "type": "boolean" }, "id": { "description": "Vendor identifier (e.g. microsoft_internal, google_workspace).\n\n* `ANTHROPIC` - ANTHROPIC\n* `AWS` - AWS\n* `BITBUCKET` - BITBUCKET\n* `BOX` - BOX\n* `CONFLUENCE` - CONFLUENCE\n* `DROPBOX` - DROPBOX\n* `GITHUB` - GITHUB\n* `GOOGLE_CLOUD_PLATFORM` - GOOGLE_CLOUD_PLATFORM\n* `GOOGLE_WORKSPACE` - GOOGLE_WORKSPACE\n* `JIRA` - JIRA\n* `MICROSOFT_INTERNAL` - MICROSOFT_INTERNAL\n* `OPENAI` - OPENAI\n* `SALESFORCE` - SALESFORCE\n* `SERVICENOW` - SERVICENOW\n* `SLACK` - SLACK", "type": "string", "enum": [ "ANTHROPIC", "AWS", "BITBUCKET", "BOX", "CONFLUENCE", "DROPBOX", "GITHUB", "GOOGLE_CLOUD_PLATFORM", "GOOGLE_WORKSPACE", "JIRA", "MICROSOFT_INTERNAL", "OPENAI", "SALESFORCE", "SERVICENOW", "SLACK" ] }, "logo": { "description": "Logo path.", "type": "string", "nullable": true }, "permissions": { "description": "All permissions with severity.", "type": "array", "items": { "$ref": "#/components/schemas/one_Permission" } }, "supported_environments": { "description": "Environments this vendor supports (standard, fedramp).", "type": "array", "items": { "type": "string" } }, "use_cases": { "description": "Supported use cases.", "type": "array", "items": { "$ref": "#/components/schemas/one_UseCaseSummary" } } }, "required": [ "auth_methods", "category", "description", "display_name", "dlp_enabled", "id", "logo", "permissions", "supported_environments", "use_cases" ] }, "one_AuthConfig": { "description": "OAuth configuration for setup flows that use OAuth.", "type": "object", "properties": { "authorization_url": { "description": "Full OAuth authorization URL with query parameters.", "type": "string", "nullable": true }, "client_id": { "description": "OAuth client ID.", "type": "string", "nullable": true }, "requires_pkce": { "description": "Whether PKCE is required.", "type": "boolean" }, "scopes": { "description": "OAuth scopes to request.", "type": "array", "items": { "type": "string" } }, "url_placeholders": { "description": "Placeholders in authorization URL that frontend must fill.", "type": "array", "items": { "type": "string" } } }, "required": [ "authorization_url", "client_id", "requires_pkce", "scopes", "url_placeholders" ] }, "one_AuthMethod": { "description": "Authentication method available for a vendor.", "type": "object", "properties": { "display_name": { "description": "Human-readable auth method name.", "type": "string" }, "id": { "description": "Auth method identifier.", "type": "string" }, "is_default": { "description": "Whether this is the default auth method.", "type": "boolean" }, "supported_environments": { "description": "Environments this auth method supports.", "type": "array", "items": { "type": "string" } } }, "required": [ "display_name", "id", "is_default", "supported_environments" ] }, "one_AuthMethodDetail": { "description": "Detailed auth method info including credentials schema and instructions.", "type": "object", "properties": { "display_name": { "description": "Human-readable auth method name.", "type": "string" }, "human_interaction_required": { "description": "Whether setup requires human interaction or integration can be created purely using API (e.g., For OAuth can not be created without user interaction).", "type": "boolean" }, "id": { "description": "Auth method identifier.", "type": "string" }, "instructions": { "description": "Step-by-step instructions for obtaining credentials.", "allOf": [ { "$ref": "#/components/schemas/one_Instructions" } ] }, "payload_example": { "description": "Example credentials payload with placeholder values.", "type": "object", "additionalProperties": true, "nullable": true }, "payload_schema": { "description": "JSON Schema for the credentials object in POST /v2/integrations request.", "type": "object", "additionalProperties": true, "nullable": true }, "redirect_url": { "description": "OAuth redirect URL for vendors requiring human interaction.", "type": "string", "nullable": true } }, "required": [ "display_name", "human_interaction_required", "id", "instructions", "payload_example", "payload_schema", "redirect_url" ] }, "one_AuthMethodSummary": { "description": "Auth method summary for list endpoint.", "type": "object", "properties": { "display_name": { "description": "Human-readable auth method name.", "type": "string" }, "id": { "description": "Auth method identifier.", "type": "string" } }, "required": [ "display_name", "id" ] }, "one_DynamicContent": { "description": "Dynamic content for instruction/form_input steps.", "type": "object", "properties": { "label": { "description": "Display label.", "type": "string" }, "type": { "description": "Content type.\n\n* `copy_block` - copy_block\n* `external_link` - external_link", "type": "string", "enum": [ "copy_block", "external_link" ] }, "url_template": { "description": "URL template with {{ variable }} interpolation (for external_link).", "type": "string", "nullable": true }, "value_from": { "description": "Field path to get value from (for copy_block).", "type": "string", "nullable": true } }, "required": [ "label", "type" ] }, "one_FeatureScope": { "description": "A feature with its additional scopes.", "type": "object", "properties": { "description": { "description": "Feature description.", "type": "string" }, "display_name": { "description": "Human-readable feature name.", "type": "string" }, "id": { "description": "Feature identifier.", "type": "string" }, "scopes": { "description": "Additional scopes when feature is enabled.", "type": "array", "items": { "$ref": "#/components/schemas/one_Permission" } } }, "required": [ "description", "display_name", "id", "scopes" ] }, "one_FormField": { "description": "A form field within a form_input step.", "type": "object", "properties": { "label": { "description": "Human-readable field label.", "type": "string" }, "name": { "description": "Field identifier (maps to credentials key).", "type": "string" }, "placeholder": { "description": "Placeholder text.", "type": "string", "nullable": true }, "required": { "description": "Whether field is required.", "type": "boolean" }, "supported_file_types": { "description": "Allowed file extensions for file_upload type.", "type": "array", "items": { "type": "string" }, "nullable": true }, "type": { "description": "Field input type.\n\n* `text` - text\n* `password` - password\n* `email` - email\n* `file_upload` - file_upload", "type": "string", "enum": [ "text", "password", "email", "file_upload" ] } }, "required": [ "label", "name", "placeholder", "required", "supported_file_types", "type" ] }, "one_Instructions": { "description": "Instructions for obtaining credentials.", "type": "object", "properties": { "markdown": { "description": "Detailed instructions in markdown format.", "type": "string" } }, "required": [ "markdown" ] }, "one_IntegrationCreateResponse": { "type": "object", "properties": { "errors": { "description": "List of errors.", "type": "array", "items": { "additionalProperties": true, "type": "object" }, "default": [] }, "messages": { "description": "List of messages.", "type": "array", "items": { "type": "string" }, "default": [] }, "result": { "description": "The requested item.", "allOf": [ { "$ref": "#/components/schemas/one_IntegrationV2Detail" } ] }, "success": { "description": "Whether the request succeeded.", "type": "boolean" } }, "required": [ "result", "success" ] }, "one_IntegrationDetailResponse": { "type": "object", "properties": { "errors": { "description": "List of errors.", "type": "array", "items": { "additionalProperties": true, "type": "object" }, "default": [] }, "messages": { "description": "List of messages.", "type": "array", "items": { "type": "string" }, "default": [] }, "result": { "description": "The requested item.", "allOf": [ { "$ref": "#/components/schemas/one_IntegrationV2Detail" } ] }, "success": { "description": "Whether the request succeeded.", "type": "boolean" } }, "required": [ "result", "success" ] }, "one_IntegrationPauseResponse": { "type": "object", "properties": { "errors": { "description": "List of errors.", "type": "array", "items": { "additionalProperties": true, "type": "object" }, "default": [] }, "messages": { "description": "List of messages.", "type": "array", "items": { "type": "string" }, "default": [] }, "result": { "description": "The requested item.", "allOf": [ { "$ref": "#/components/schemas/one_IntegrationV2Detail" } ] }, "success": { "description": "Whether the request succeeded.", "type": "boolean" } }, "required": [ "result", "success" ] }, "one_IntegrationResumeResponse": { "type": "object", "properties": { "errors": { "description": "List of errors.", "type": "array", "items": { "additionalProperties": true, "type": "object" }, "default": [] }, "messages": { "description": "List of messages.", "type": "array", "items": { "type": "string" }, "default": [] }, "result": { "description": "The requested item.", "allOf": [ { "$ref": "#/components/schemas/one_IntegrationV2Detail" } ] }, "success": { "description": "Whether the request succeeded.", "type": "boolean" } }, "required": [ "result", "success" ] }, "one_IntegrationUpdateResponse": { "type": "object", "properties": { "errors": { "description": "List of errors.", "type": "array", "items": { "additionalProperties": true, "type": "object" }, "default": [] }, "messages": { "description": "List of messages.", "type": "array", "items": { "type": "string" }, "default": [] }, "result": { "description": "The requested item.", "allOf": [ { "$ref": "#/components/schemas/one_IntegrationV2Detail" } ] }, "success": { "description": "Whether the request succeeded.", "type": "boolean" } }, "required": [ "result", "success" ] }, "one_IntegrationV2CreateRequest": { "description": "Serializer for v2 integration create requests.", "type": "object", "properties": { "application": { "description": "Vendor/application slug (e.g., GOOGLE_WORKSPACE).\n\n* `ANTHROPIC` - ANTHROPIC\n* `AWS` - AWS\n* `BITBUCKET` - BITBUCKET\n* `BOX` - BOX\n* `CONFLUENCE` - CONFLUENCE\n* `DROPBOX` - DROPBOX\n* `GITHUB` - GITHUB\n* `GOOGLE_CLOUD_PLATFORM` - GOOGLE_CLOUD_PLATFORM\n* `GOOGLE_WORKSPACE` - GOOGLE_WORKSPACE\n* `JIRA` - JIRA\n* `MICROSOFT_INTERNAL` - MICROSOFT_INTERNAL\n* `OPENAI` - OPENAI\n* `SALESFORCE` - SALESFORCE\n* `SERVICENOW` - SERVICENOW\n* `SLACK` - SLACK", "type": "string", "enum": [ "ANTHROPIC", "AWS", "BITBUCKET", "BOX", "CONFLUENCE", "DROPBOX", "GITHUB", "GOOGLE_CLOUD_PLATFORM", "GOOGLE_WORKSPACE", "JIRA", "MICROSOFT_INTERNAL", "OPENAI", "SALESFORCE", "SERVICENOW", "SLACK" ] }, "auth_method": { "description": "Authentication method slug (uses default if omitted).", "type": "string", "minLength": 1, "nullable": true }, "credentials": { "description": "Credentials for the integration.", "type": "object", "additionalProperties": true }, "dlp_profiles": { "description": "List of DLP profile IDs to associate.", "type": "array", "items": { "format": "uuid", "type": "string" }, "maxItems": 20 }, "name": { "description": "Name of the integration.", "type": "string", "maxLength": 256, "minLength": 1 }, "permissions": { "description": "List of permission scopes (uses policy defaults if empty).", "type": "array", "items": { "minLength": 1, "type": "string" } }, "use_cases": { "description": "List of use case or feature slugs to enroll (e.g., ['casb', 'ces', 'auto_remediation']).", "type": "array", "items": { "description": "* `casb` - casb\n* `ces` - ces\n* `auto_remediation` - auto_remediation", "enum": [ "casb", "ces", "auto_remediation" ], "type": "string" } } }, "required": [ "application", "credentials", "name" ] }, "one_IntegrationV2Detail": { "description": "Serializer for v2 integration detail response with use cases.", "type": "object", "properties": { "application": { "type": "object", "additionalProperties": { "nullable": true, "type": "string" }, "readOnly": true }, "auth_method": { "description": "The integration's authentication method.", "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "readOnly": true }, "authorization_link": { "description": "Authorization link for the integration.", "type": "object", "nullable": true, "properties": { "components": { "additionalProperties": true, "nullable": true, "type": "object" }, "link": { "type": "string", "nullable": true } }, "readOnly": true, "required": [ "link", "components" ] }, "created": { "description": "When the integration was created.", "type": "string", "format": "date-time", "readOnly": true }, "credentials_expiry": { "description": "Credentials expiry time.", "type": "string", "format": "date-time", "readOnly": true }, "dlp_profiles": { "description": "DLP Profiles enabled for the integration.", "type": "array", "items": { "format": "uuid", "type": "string" }, "readOnly": true }, "health_details": { "description": "Health details with remediation hints.", "type": "array", "items": { "additionalProperties": true, "type": "object" }, "readOnly": true }, "id": { "description": "Integration ID.", "type": "string", "format": "uuid", "readOnly": true }, "is_paused": { "description": "Whether the user paused the integration.", "type": "boolean", "readOnly": true }, "last_hydrated": { "description": "Last time the integration was hydrated.", "type": "string", "format": "date-time", "readOnly": true }, "name": { "description": "Name of the integration.", "type": "string", "readOnly": true }, "status": { "description": "Integration status.", "type": "string" }, "updated": { "description": "When the integration was last updated.", "type": "string", "format": "date-time", "readOnly": true }, "use_cases": { "description": "Use cases enabled for the integration.", "type": "array", "items": { "additionalProperties": true, "type": "object" }, "readOnly": true } }, "required": [ "application", "auth_method", "authorization_link", "created", "credentials_expiry", "dlp_profiles", "health_details", "id", "is_paused", "last_hydrated", "name", "status", "updated", "use_cases" ] }, "one_IntegrationV2ListItem": { "description": "Serializer for v2 integration list responses.", "type": "object", "properties": { "application": { "type": "object", "additionalProperties": { "nullable": true, "type": "string" }, "readOnly": true }, "created": { "description": "When the integration was created.", "type": "string", "format": "date-time", "readOnly": true }, "id": { "description": "Integration ID.", "type": "string", "format": "uuid", "readOnly": true }, "is_paused": { "description": "Whether the user paused the integration.", "type": "boolean", "readOnly": true }, "name": { "description": "Name of the integration.", "type": "string", "readOnly": true }, "status": { "description": "Integration status.", "type": "string" }, "updated": { "description": "When the integration was last updated.", "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "application", "created", "id", "is_paused", "name", "status", "updated" ] }, "one_PaginatedApplicationListList": { "type": "object", "properties": { "errors": { "description": "List of errors.", "type": "array", "items": { "type": "object" }, "default": [] }, "messages": { "description": "List of messages.", "type": "array", "items": { "type": "string" }, "default": [] }, "result": { "description": "List of items.", "type": "array", "items": { "$ref": "#/components/schemas/one_ApplicationList" } }, "result_info": { "description": "Pagination metadata.", "type": "object", "properties": { "count": { "description": "Number of items in current page.", "type": "integer" }, "next": { "description": "URL for next page.", "type": "string", "format": "uri", "nullable": true }, "page": { "description": "Current page number.", "type": "integer" }, "per_page": { "description": "Number of items per page.", "type": "integer" }, "previous": { "description": "URL for previous page.", "type": "string", "format": "uri", "nullable": true }, "total_count": { "description": "Total number of items.", "type": "integer" } } }, "success": { "description": "Whether the request succeeded.", "type": "boolean" } }, "required": [ "result", "success", "errors", "messages", "result_info" ] }, "one_PaginatedAuthMethodDetailList": { "type": "object", "properties": { "errors": { "description": "List of errors.", "type": "array", "items": { "type": "object" }, "default": [] }, "messages": { "description": "List of messages.", "type": "array", "items": { "type": "string" }, "default": [] }, "result": { "description": "List of items.", "type": "array", "items": { "$ref": "#/components/schemas/one_AuthMethodDetail" } }, "result_info": { "description": "Pagination metadata.", "type": "object", "properties": { "count": { "description": "Number of items in current page.", "type": "integer" }, "next": { "description": "URL for next page.", "type": "string", "format": "uri", "nullable": true }, "page": { "description": "Current page number.", "type": "integer" }, "per_page": { "description": "Number of items per page.", "type": "integer" }, "previous": { "description": "URL for previous page.", "type": "string", "format": "uri", "nullable": true }, "total_count": { "description": "Total number of items.", "type": "integer" } } }, "success": { "description": "Whether the request succeeded.", "type": "boolean" } }, "required": [ "result", "success", "errors", "messages", "result_info" ] }, "one_PaginatedIntegrationV2ListItemList": { "type": "object", "properties": { "errors": { "description": "List of errors.", "type": "array", "items": { "type": "object" }, "default": [] }, "messages": { "description": "List of messages.", "type": "array", "items": { "type": "string" }, "default": [] }, "result": { "description": "List of items.", "type": "array", "items": { "$ref": "#/components/schemas/one_IntegrationV2ListItem" } }, "result_info": { "description": "Pagination metadata.", "type": "object", "properties": { "count": { "description": "Number of items in current page.", "type": "integer" }, "next": { "description": "URL for next page.", "type": "string", "format": "uri", "nullable": true }, "page": { "description": "Current page number.", "type": "integer" }, "per_page": { "description": "Number of items per page.", "type": "integer" }, "previous": { "description": "URL for previous page.", "type": "string", "format": "uri", "nullable": true }, "total_count": { "description": "Total number of items.", "type": "integer" } } }, "success": { "description": "Whether the request succeeded.", "type": "boolean" } }, "required": [ "result", "success", "errors", "messages", "result_info" ] }, "one_PaginatedSetupFlowList": { "type": "object", "properties": { "errors": { "description": "List of errors.", "type": "array", "items": { "type": "object" }, "default": [] }, "messages": { "description": "List of messages.", "type": "array", "items": { "type": "string" }, "default": [] }, "result": { "description": "List of items.", "type": "array", "items": { "$ref": "#/components/schemas/one_SetupFlow" } }, "result_info": { "description": "Pagination metadata.", "type": "object", "properties": { "count": { "description": "Number of items in current page.", "type": "integer" }, "next": { "description": "URL for next page.", "type": "string", "format": "uri", "nullable": true }, "page": { "description": "Current page number.", "type": "integer" }, "per_page": { "description": "Number of items per page.", "type": "integer" }, "previous": { "description": "URL for previous page.", "type": "string", "format": "uri", "nullable": true }, "total_count": { "description": "Total number of items.", "type": "integer" } } }, "success": { "description": "Whether the request succeeded.", "type": "boolean" } }, "required": [ "result", "success", "errors", "messages", "result_info" ] }, "one_PatchedUpdateIntegrationV2Request": { "description": "Serializer for v2 integration PATCH requests.", "type": "object", "properties": { "credentials": { "description": "Partial credential fields to merge with existing.", "type": "object", "additionalProperties": true }, "dlp_profiles": { "description": "List of DLP profile IDs to associate with the integration.", "type": "array", "items": { "format": "uuid", "type": "string" }, "maxItems": 20 }, "name": { "description": "Name of the integration.", "type": "string", "maxLength": 256, "minLength": 1 }, "permissions": { "description": "List of permission scopes granted to the integration.", "type": "array", "items": { "minLength": 1, "type": "string" } }, "use_cases": { "description": "List of use case or feature slugs to enroll (e.g., ['casb', 'ces', 'auto_remediation']).", "type": "array", "items": { "description": "* `casb` - casb\n* `ces` - ces\n* `auto_remediation` - auto_remediation", "enum": [ "casb", "ces", "auto_remediation" ], "type": "string" } } } }, "one_Permission": { "description": "Permission/scope with severity for display.", "type": "object", "properties": { "display_name": { "description": "Human-readable permission name.", "type": "string" }, "scope": { "description": "Vendor-native scope identifier.", "type": "string" }, "severity": { "description": "Permission sensitivity level.\n\n* `low` - low\n* `medium` - medium\n* `high` - high\n* `critical` - critical", "type": "string", "enum": [ "low", "medium", "high", "critical" ] } }, "required": [ "display_name", "scope", "severity" ] }, "one_SetupFlow": { "description": "Setup flow for an application auth method.", "type": "object", "properties": { "auth_config": { "description": "OAuth configuration (present for OAuth-based flows).", "allOf": [ { "$ref": "#/components/schemas/one_AuthConfig" } ] }, "default": { "description": "Whether this is the default auth method.", "type": "boolean" }, "description": { "description": "Flow description.", "type": "string" }, "id": { "description": "Setup flow identifier.", "type": "string" }, "name": { "description": "Human-readable flow name.", "type": "string" }, "steps": { "description": "Ordered list of setup steps.", "type": "array", "items": { "$ref": "#/components/schemas/one_SetupFlowStep" } }, "supported_environments": { "description": "Environments this auth method supports (standard, fedramp).", "type": "array", "items": { "type": "string" } } }, "required": [ "default", "description", "id", "name", "steps", "supported_environments" ] }, "one_SetupFlowStep": { "description": "A single step in the setup flow. Polymorphic based on type.", "type": "object", "properties": { "component_id": { "description": "Component identifier (for component type).", "type": "string", "nullable": true }, "description": { "description": "Step description with markdown support.", "type": "string", "nullable": true }, "dynamic_content": { "description": "Dynamic content blocks (for instruction/form_input).", "type": "array", "items": { "$ref": "#/components/schemas/one_DynamicContent" }, "nullable": true }, "form_fields": { "description": "Form fields (for form_input).", "type": "array", "items": { "$ref": "#/components/schemas/one_FormField" } }, "is_required": { "description": "Whether step is required (for form_input).", "type": "boolean" }, "parameters": { "description": "Component parameters (for component type).", "additionalProperties": { "type": "string" }, "nullable": true, "type": "object" }, "title": { "description": "Step title (for instruction/form_input/oauth_redirect).", "type": "string" }, "type": { "description": "Step type.\n\n* `component` - component\n* `instruction` - instruction\n* `form_input` - form_input\n* `oauth_redirect` - oauth_redirect", "type": "string", "enum": [ "component", "instruction", "form_input", "oauth_redirect" ] } }, "required": [ "type" ] }, "one_UseCaseDetail": { "description": "Full use case with scopes and features for detail endpoint.", "type": "object", "properties": { "base_scopes": { "description": "Scopes always required for this use case.", "type": "array", "items": { "$ref": "#/components/schemas/one_Permission" } }, "description": { "description": "Use case description.", "type": "string" }, "display_name": { "description": "Human-readable use case name.", "type": "string" }, "features": { "description": "Optional features with extra scopes.", "type": "array", "items": { "$ref": "#/components/schemas/one_FeatureScope" } }, "id": { "description": "Use case identifier.", "type": "string" } }, "required": [ "base_scopes", "description", "display_name", "features", "id" ] }, "one_UseCaseSummary": { "description": "Lightweight use case for list endpoint.", "type": "object", "properties": { "display_name": { "description": "Human-readable use case name.", "type": "string" }, "id": { "description": "Use case identifier (e.g. casb, ces).", "type": "string" } }, "required": [ "display_name", "id" ] }, "organizations-api_Account": { "type": "object", "properties": { "created_on": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "settings": { "type": "object", "properties": { "abuse_contact_email": { "type": "string", "nullable": true }, "access_approval_expiry": { "type": "string", "format": "date-time", "nullable": true }, "api_access_enabled": { "type": "boolean", "nullable": true }, "default_nameservers": { "description": "Use [DNS Settings](https://developers.cloudflare.com/api/operations/dns-settings-for-an-account-list-dns-settings) instead. Deprecated.", "type": "string", "deprecated": true, "nullable": true }, "enforce_twofactor": { "type": "boolean", "nullable": true }, "use_account_custom_ns_by_default": { "description": "Use [DNS Settings](https://developers.cloudflare.com/api/operations/dns-settings-for-an-account-list-dns-settings) instead. Deprecated.", "type": "boolean", "deprecated": true, "nullable": true } }, "required": [ "enforce_twofactor", "api_access_enabled", "access_approval_expiry", "abuse_contact_email", "use_account_custom_ns_by_default", "default_nameservers" ] }, "tags": { "description": "Account tags, present only when `include_tags=true` is requested.", "type": "object", "additionalProperties": { "type": "string" } }, "type": { "type": "string", "enum": [ "standard", "enterprise" ] } }, "required": [ "id", "name", "type", "settings", "created_on" ] }, "organizations-api_BatchAccountMoveResponse": { "type": "object", "properties": { "statuses": { "type": "object", "properties": { "message": { "type": "string" }, "moved": { "type": "boolean" }, "tag": { "type": "string" } }, "required": [ "tag", "moved" ] } }, "required": [ "statuses" ] }, "organizations-api_BatchCreateMembersRequest": { "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_CreateSingleMember" }, "maxItems": 10 } }, "required": [ "members" ] }, "organizations-api_BoolAllocation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bool" ] }, "value": { "type": "boolean" } }, "required": [ "type", "value" ] }, "organizations-api_CreateMemberRequest": { "type": "object", "properties": { "member": { "$ref": "#/components/schemas/organizations-api_CreateSingleMember" } }, "required": [ "member" ] }, "organizations-api_CreateSingleMember": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "canceled" ] }, "user": { "type": "object", "properties": { "email": { "type": "string" } }, "required": [ "email" ] } }, "required": [ "user" ] }, "organizations-api_DeleteOrganizationResponse": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "organizations-api_Entitlement": { "type": "object", "properties": { "allocation": { "anyOf": [ { "$ref": "#/components/schemas/organizations-api_MaxCountAllocation" }, { "$ref": "#/components/schemas/organizations-api_BoolAllocation" }, { "$ref": "#/components/schemas/organizations-api_NullAllocation" } ] }, "feature": { "$ref": "#/components/schemas/organizations-api_Feature" } }, "required": [ "feature", "allocation" ] }, "organizations-api_Feature": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] }, "organizations-api_InnateEntitlements": { "type": "object", "properties": { "allow_add_subdomain": { "$ref": "#/components/schemas/organizations-api_BoolAllocation" }, "allow_auto_accept_invites": { "$ref": "#/components/schemas/organizations-api_BoolAllocation" }, "cname_setup_allowed": { "$ref": "#/components/schemas/organizations-api_BoolAllocation" }, "custom_entitlements": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_Entitlement" }, "nullable": true }, "mhs_certificate_count": { "$ref": "#/components/schemas/organizations-api_MaxCountAllocation" }, "partial_setup_allowed": { "$ref": "#/components/schemas/organizations-api_BoolAllocation" } }, "required": [ "allow_add_subdomain", "cname_setup_allowed", "partial_setup_allowed", "allow_auto_accept_invites", "mhs_certificate_count", "custom_entitlements" ] }, "organizations-api_MaxCountAllocation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "max_count" ] }, "value": { "type": "integer" } }, "required": [ "type", "value" ] }, "organizations-api_Member": { "type": "object", "properties": { "create_time": { "type": "string", "format": "date-time" }, "id": { "$ref": "#/components/schemas/organizations-api_MemberID" }, "meta": { "type": "object", "additionalProperties": { "type": "object" } }, "status": { "type": "string", "enum": [ "active", "pending", "rejected", "canceled" ] }, "update_time": { "type": "string", "format": "date-time" }, "user": { "$ref": "#/components/schemas/organizations-api_MemberSubjectUser" } }, "required": [ "id", "status", "user", "meta", "create_time", "update_time" ] }, "organizations-api_MemberID": { "description": "Organization Member ID", "type": "string", "example": "a7b9c3d2e8f4a1b5c6d0e9f2a3b7c4d8", "pattern": "^[a-f0-9]{32}$" }, "organizations-api_MemberSubjectUser": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "two_factor_authentication_enabled": { "type": "boolean" } }, "required": [ "id", "email", "name", "two_factor_authentication_enabled" ] }, "organizations-api_MoveAccountResponse": { "type": "object", "properties": { "account_id": { "type": "string" }, "destination_organization_id": { "type": "string" }, "source_organization_id": { "type": "string" } }, "required": [ "account_id", "source_organization_id", "destination_organization_id" ] }, "organizations-api_NullAllocation": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "" ] }, "value": { "type": "object" } }, "required": [ "type" ] }, "organizations-api_Organization": { "description": "References an Organization in the Cloudflare data model.", "type": "object", "properties": { "create_time": { "type": "string", "format": "date-time", "readOnly": true }, "id": { "allOf": [ { "$ref": "#/components/schemas/organizations-api_OrganizationID" } ], "readOnly": true }, "meta": { "type": "object", "additionalProperties": { "type": "object" }, "properties": { "hierarchy_tags": { "description": "Ordered chain of organization tags from the root organization down to\n(and including) this organization itself. Root organizations return a\nsingle-element array containing their own tag; sub-organizations return\n`[rootTag, ...intermediateTags, parentTag, selfTag]`. Useful for\nconstructing authorization scopes that need to cover every ancestor\nin the hierarchy.", "type": "array", "items": { "type": "string" } }, "managed_by": { "type": "string" }, "tenant_flags": { "allOf": [ { "$ref": "#/components/schemas/organizations-api_OrganizationFlags" } ] } }, "readOnly": true }, "name": { "type": "string" }, "parent": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/organizations-api_OrganizationID" }, "name": { "type": "string", "readOnly": true } }, "required": [ "id", "name" ] }, "profile": { "$ref": "#/components/schemas/organizations-api_Profile" } }, "required": [ "id", "name", "create_time", "meta" ] }, "organizations-api_OrganizationFlags": { "description": "Enable features for Organizations.", "type": "object", "properties": { "account_creation": { "type": "string" }, "account_creation_applies_tenant_defaults": { "type": "string" }, "account_deletion": { "type": "string" }, "account_migration": { "type": "string" }, "account_mobility": { "type": "string" }, "enterprise_capability": { "type": "string" }, "member_management": { "type": "string" }, "sub_org_creation": { "type": "string" } }, "required": [ "account_creation", "account_creation_applies_tenant_defaults", "account_deletion", "account_migration", "account_mobility", "enterprise_capability", "member_management", "sub_org_creation" ] }, "organizations-api_OrganizationID": { "type": "string", "example": "a7b9c3d2e8f4a1b5c6d0e9f2a3b7c4d8", "pattern": "^[a-f0-9]{32}$", "title": "Organization ID", "x-auditable": true }, "organizations-api_PageTokenResultInfo": { "type": "object", "properties": { "next_page_token": { "description": "Use this opaque token in the next request to retrieve the\nnext page.\n\nParameters used to filter the retrieved list must remain in subsequent\nrequests with a page token.", "type": "string" }, "total_size": { "description": "Counts the total amount of items in a list with the applied filters. The API omits next_page_token to indicate no more items in a particular list.", "type": "integer" } } }, "organizations-api_Profile": { "type": "object", "properties": { "business_address": { "type": "string" }, "business_email": { "type": "string" }, "business_name": { "type": "string" }, "business_phone": { "type": "string" }, "external_metadata": { "type": "string" } }, "required": [ "business_name", "business_email", "business_phone", "business_address", "external_metadata" ] }, "organizations-api_ProfileResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" }, "maxItems": 0 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "$ref": "#/components/schemas/organizations-api_Profile" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "organizations-api_Tenant": { "type": "object", "properties": { "cdate": { "type": "string", "format": "date-time" }, "customer_id": { "type": "string" }, "edate": { "type": "string", "format": "date-time" }, "tenant_contacts": { "type": "object", "properties": { "email": { "type": "string" }, "website": { "type": "string" } } }, "tenant_labels": { "type": "array", "items": { "type": "string" } }, "tenant_metadata": { "type": "object", "properties": { "dns": { "type": "object", "properties": { "ns_pool": { "type": "object", "properties": { "primary": { "type": "string" }, "secondary": { "type": "string" } } } }, "required": [ "ns_pool" ] } } }, "tenant_name": { "type": "string" }, "tenant_network": { "type": "object" }, "tenant_status": { "type": "string" }, "tenant_tag": { "type": "string" }, "tenant_type": { "type": "string" }, "tenant_units": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_TenantUnit" } } }, "required": [ "tenant_tag", "tenant_name", "tenant_labels", "tenant_type", "tenant_status", "tenant_metadata", "tenant_contacts", "cdate", "edate", "tenant_network", "tenant_units" ] }, "organizations-api_TenantMembership": { "type": "object", "properties": { "user_email": { "type": "string" }, "user_name": { "type": "string" }, "user_tag": { "type": "string" } }, "required": [ "user_tag", "user_email", "user_name" ] }, "organizations-api_TenantUnit": { "type": "object", "properties": { "unit_memberships": { "type": "array", "items": { "type": "object" } }, "unit_metadata": { "type": "object" }, "unit_name": { "type": "string" }, "unit_status": { "type": "string" }, "unit_tag": { "type": "string" } }, "required": [ "unit_tag", "unit_name", "unit_status", "unit_metadata", "unit_memberships" ] }, "organizations-api_V4ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/organizations-api_V4Message" } }, "result": { "type": "object" }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors", "messages" ] }, "organizations-api_V4Message": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "pages_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/pages_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "pages_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/pages_messages" }, "messages": { "$ref": "#/components/schemas/pages_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "pages_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/pages_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/pages_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "pages_build_config": { "description": "Configs for the project build process.", "type": "object", "properties": { "build_caching": { "description": "Enable build caching for the project.", "type": "boolean", "example": true, "nullable": true, "x-auditable": true }, "build_command": { "description": "Command used to build project.", "type": "string", "example": "npm run build", "nullable": true, "x-auditable": true }, "destination_dir": { "description": "Assets output directory of the build.", "type": "string", "example": "build", "nullable": true, "x-auditable": true }, "root_dir": { "description": "Directory to run the command.", "type": "string", "example": "/", "nullable": true, "x-auditable": true }, "web_analytics_tag": { "description": "The classifying tag for analytics.", "type": "string", "example": "cee1c73f6e4743d0b5e6bb1a0bcaabcc", "nullable": true, "x-auditable": true }, "web_analytics_token": { "description": "The auth token for analytics.", "type": "string", "example": "021e1057c18547eca7b79f2516f06o7x", "nullable": true, "x-sensitive": true } }, "required": [ "web_analytics_tag", "web_analytics_token" ] }, "pages_deployment": { "type": "object", "properties": { "aliases": { "description": "A list of alias URLs pointing to this deployment.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "https://branchname.projectname.pages.dev" ], "nullable": true, "readOnly": true }, "build_config": { "$ref": "#/components/schemas/pages_build_config" }, "created_on": { "description": "When the deployment was created.", "type": "string", "format": "date-time", "example": "2021-03-09T00:55:03.923456Z", "readOnly": true, "x-auditable": true }, "deployment_trigger": { "description": "Info about what caused the deployment.", "type": "object", "properties": { "metadata": { "description": "Additional info about the trigger.", "type": "object", "properties": { "branch": { "description": "Where the trigger happened.", "type": "string", "example": "main", "x-auditable": true }, "commit_dirty": { "description": "Whether the deployment trigger commit was dirty.", "type": "boolean", "example": false, "x-auditable": true }, "commit_hash": { "description": "Hash of the deployment trigger commit.", "type": "string", "example": "ad9ccd918a81025731e10e40267e11273a263421", "x-auditable": true }, "commit_message": { "description": "Message of the deployment trigger commit.", "type": "string", "example": "Update index.html", "x-auditable": true } }, "required": [ "branch", "commit_hash", "commit_message", "commit_dirty" ] }, "type": { "description": "What caused the deployment.", "type": "string", "example": "ad_hoc", "enum": [ "github:push", "ad_hoc", "deploy_hook" ], "x-auditable": true } }, "readOnly": true, "required": [ "type", "metadata" ] }, "env_vars": { "$ref": "#/components/schemas/pages_env_vars" }, "environment": { "description": "Type of deploy.", "type": "string", "example": "preview", "enum": [ "preview", "production" ], "readOnly": true, "x-auditable": true }, "id": { "description": "Id of the deployment.", "type": "string", "example": "f64788e9-fccd-4d4a-a28a-cb84f88f6", "readOnly": true, "x-auditable": true }, "is_skipped": { "description": "If the deployment has been skipped.", "type": "boolean", "example": true, "readOnly": true, "x-auditable": true }, "latest_stage": { "$ref": "#/components/schemas/pages_stage" }, "modified_on": { "description": "When the deployment was last modified.", "type": "string", "format": "date-time", "example": "2021-03-09T00:58:59.045655", "readOnly": true, "x-auditable": true }, "project_id": { "description": "Id of the project.", "type": "string", "example": "7b162ea7-7367-4d67-bcde-1160995d5", "readOnly": true, "x-auditable": true }, "project_name": { "$ref": "#/components/schemas/pages_project_name" }, "short_id": { "description": "Short Id (8 character) of the deployment.", "type": "string", "example": "f64788e9", "readOnly": true, "x-auditable": true }, "skip_reason": { "description": "Why the deployment was skipped.", "type": "string", "example": "commit_message", "enum": [ "commit_message", "preview_deployments_disabled", "production_deployments_disabled", "path_config", "branch_config", "pages_to_workers_conversion" ], "nullable": true, "readOnly": true, "x-auditable": true }, "source": { "$ref": "#/components/schemas/pages_source" }, "stages": { "description": "List of past stages.", "type": "array", "items": { "$ref": "#/components/schemas/pages_stage" }, "example": [ { "ended_on": "2021-06-03T15:39:03.134378Z", "name": "queued", "started_on": "2021-06-03T15:38:15.608194Z", "status": "active" }, { "ended_on": null, "name": "initialize", "started_on": null, "status": "idle" }, { "ended_on": null, "name": "clone_repo", "started_on": null, "status": "idle" }, { "ended_on": null, "name": "build", "started_on": null, "status": "idle" }, { "ended_on": null, "name": "deploy", "started_on": null, "status": "idle" } ], "readOnly": true }, "url": { "description": "The live URL to view this deployment.", "type": "string", "example": "https://f64788e9.ninjakittens.pages.dev", "readOnly": true, "x-auditable": true }, "uses_functions": { "description": "Whether the deployment uses functions.", "type": "boolean", "nullable": true, "readOnly": true, "x-auditable": true } }, "required": [ "aliases", "build_config", "created_on", "deployment_trigger", "environment", "env_vars", "id", "is_skipped", "latest_stage", "modified_on", "project_id", "project_name", "short_id", "source", "stages", "url" ] }, "pages_deployment_config_values": { "type": "object", "properties": { "ai_bindings": { "description": "Constellation bindings used for Pages Functions.", "type": "object", "example": { "AI_BINDING": { "project_id": "some-project-id" } }, "additionalProperties": { "description": "AI binding.", "properties": { "project_id": { "type": "string", "x-auditable": true } }, "required": [ "project_id" ], "type": "object" } }, "always_use_latest_compatibility_date": { "description": "Whether to always use the latest compatibility date for Pages Functions.", "type": "boolean", "example": false, "x-auditable": true }, "analytics_engine_datasets": { "description": "Analytics Engine bindings used for Pages Functions.", "type": "object", "example": { "ANALYTICS_ENGINE_BINDING": { "dataset": "api_analytics" } }, "additionalProperties": { "description": "Analytics Engine binding.", "properties": { "dataset": { "description": "Name of the dataset.", "type": "string", "example": "api_analytics", "x-auditable": true } }, "required": [ "dataset" ], "type": "object" } }, "browsers": { "description": "Browser bindings used for Pages Functions.", "type": "object", "example": { "BROWSER": {} }, "additionalProperties": { "description": "Browser binding.", "nullable": true, "type": "object", "x-stainless-empty-object": true } }, "build_image_major_version": { "description": "The major version of the build image to use for Pages Functions.", "type": "integer", "example": 3, "x-auditable": true }, "compatibility_date": { "description": "Compatibility date used for Pages Functions.", "type": "string", "example": "2025-01-01T00:00:00Z", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "compatibility_flags": { "description": "Compatibility flags used for Pages Functions.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "url_standard" ] }, "d1_databases": { "description": "D1 databases used for Pages Functions.", "type": "object", "example": { "D1_BINDING": { "id": "445e2955-951a-43f8-a35b-a4d0c8138f63" } }, "additionalProperties": { "description": "D1 binding.", "properties": { "id": { "description": "UUID of the D1 database.", "type": "string", "example": "445e2955-951a-43f8-a35b-a4d0c8138f63", "x-auditable": true } }, "required": [ "id" ], "type": "object" } }, "durable_object_namespaces": { "description": "Durable Object namespaces used for Pages Functions.", "type": "object", "example": { "DO_BINDING": { "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3" } }, "additionalProperties": { "description": "Durable Object binding.", "properties": { "namespace_id": { "description": "ID of the Durable Object namespace.", "type": "string", "example": "5eb63bbbe01eeed093cb22bb8f5acdc3", "x-auditable": true } }, "required": [ "namespace_id" ], "type": "object" } }, "env_vars": { "$ref": "#/components/schemas/pages_env_vars" }, "fail_open": { "description": "Whether to fail open when the deployment config cannot be applied.", "type": "boolean", "example": true, "x-auditable": true }, "hyperdrive_bindings": { "description": "Hyperdrive bindings used for Pages Functions.", "type": "object", "example": { "HYPERDRIVE": { "id": "a76a99bc342644deb02c38d66082262a" } }, "additionalProperties": { "description": "Hyperdrive binding.", "properties": { "id": { "type": "string", "example": "a76a99bc342644deb02c38d66082262a", "x-auditable": true } }, "required": [ "id" ], "type": "object" } }, "kv_namespaces": { "description": "KV namespaces used for Pages Functions.", "type": "object", "example": { "KV_BINDING": { "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3" } }, "additionalProperties": { "description": "KV namespace binding.", "properties": { "namespace_id": { "description": "ID of the KV namespace.", "type": "string", "example": "5eb63bbbe01eeed093cb22bb8f5acdc3", "x-auditable": true } }, "required": [ "namespace_id" ], "type": "object" } }, "limits": { "description": "Limits for Pages Functions.", "type": "object", "example": { "cpu_ms": 100 }, "properties": { "cpu_ms": { "description": "CPU time limit in milliseconds.", "type": "integer", "example": 100, "x-auditable": true } }, "required": [ "cpu_ms" ] }, "mtls_certificates": { "description": "mTLS bindings used for Pages Functions.", "type": "object", "example": { "MTLS": { "certificate_id": "d7cdd17c-916f-4cb7-aabe-585eb382ec4e" } }, "additionalProperties": { "description": "mTLS binding.", "properties": { "certificate_id": { "type": "string", "example": "d7cdd17c-916f-4cb7-aabe-585eb382ec4e", "x-auditable": true } }, "required": [ "certificate_id" ], "type": "object" } }, "placement": { "description": "Placement setting used for Pages Functions.", "type": "object", "example": { "mode": "smart" }, "properties": { "mode": { "description": "Placement mode.", "type": "string", "example": "smart", "x-auditable": true } }, "required": [ "mode" ] }, "queue_producers": { "description": "Queue Producer bindings used for Pages Functions.", "type": "object", "example": { "QUEUE_PRODUCER_BINDING": { "name": "some-queue" } }, "additionalProperties": { "description": "Queue Producer binding.", "properties": { "name": { "description": "Name of the Queue.", "type": "string", "example": "some-queue", "x-auditable": true } }, "required": [ "name" ], "type": "object" } }, "r2_buckets": { "description": "R2 buckets used for Pages Functions.", "type": "object", "example": { "R2_BINDING": { "name": "some-bucket" } }, "additionalProperties": { "description": "R2 binding.", "properties": { "jurisdiction": { "description": "Jurisdiction of the R2 bucket.", "type": "string", "example": "eu", "nullable": true, "x-auditable": true }, "name": { "description": "Name of the R2 bucket.", "type": "string", "example": "some-bucket", "x-auditable": true } }, "required": [ "name" ], "type": "object" } }, "services": { "description": "Services used for Pages Functions.", "type": "object", "example": { "SERVICE_BINDING": { "entrypoint": "MyHandler", "environment": "production", "service": "example-worker" } }, "additionalProperties": { "description": "Service binding.", "properties": { "entrypoint": { "description": "The entrypoint to bind to.", "type": "string", "nullable": true, "x-auditable": true }, "environment": { "description": "The Service environment.", "type": "string", "x-auditable": true }, "service": { "description": "The Service name.", "type": "string", "x-auditable": true } }, "required": [ "service", "environment" ], "type": "object" } }, "usage_model": { "description": "The usage model for Pages Functions.", "type": "string", "example": "standard", "enum": [ "standard", "bundled", "unbound" ], "deprecated": true, "x-auditable": true, "x-stainless-deprecation-message": "All new projects now use the Standard usage model." }, "vectorize_bindings": { "description": "Vectorize bindings used for Pages Functions.", "type": "object", "example": { "VECTORIZE": { "index_name": "my_index" } }, "additionalProperties": { "description": "Vectorize binding.", "properties": { "index_name": { "type": "string", "example": "my_index", "x-auditable": true } }, "required": [ "index_name" ], "type": "object" } }, "wrangler_config_hash": { "description": "Hash of the Wrangler configuration used for the deployment.", "type": "string", "example": "abc123def456", "x-auditable": true } }, "required": [ "env_vars", "fail_open", "always_use_latest_compatibility_date", "compatibility_date", "compatibility_flags", "build_image_major_version", "usage_model" ] }, "pages_deployment_config_values_request": { "type": "object", "properties": { "ai_bindings": { "description": "Constellation bindings used for Pages Functions.", "type": "object", "example": { "AI_BINDING": { "project_id": "some-project-id" } }, "additionalProperties": { "description": "AI binding.", "nullable": true, "properties": { "project_id": { "type": "string", "x-auditable": true } }, "required": [ "project_id" ], "type": "object" } }, "always_use_latest_compatibility_date": { "description": "Whether to always use the latest compatibility date for Pages Functions.", "type": "boolean", "example": false, "default": false, "x-auditable": true }, "analytics_engine_datasets": { "description": "Analytics Engine bindings used for Pages Functions.", "type": "object", "example": { "ANALYTICS_ENGINE_BINDING": { "dataset": "api_analytics" } }, "additionalProperties": { "description": "Analytics Engine binding.", "nullable": true, "properties": { "dataset": { "description": "Name of the dataset.", "type": "string", "example": "api_analytics", "x-auditable": true } }, "required": [ "dataset" ], "type": "object" } }, "browsers": { "description": "Browser bindings used for Pages Functions.", "type": "object", "example": { "BROWSER": {} }, "additionalProperties": { "description": "Browser binding.", "nullable": true, "type": "object", "x-stainless-empty-object": true } }, "build_image_major_version": { "description": "The major version of the build image to use for Pages Functions.", "type": "integer", "example": 3, "default": 3, "x-auditable": true }, "compatibility_date": { "description": "Compatibility date used for Pages Functions.", "type": "string", "example": "2025-01-01T00:00:00Z", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "compatibility_flags": { "description": "Compatibility flags used for Pages Functions.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "url_standard" ] }, "d1_databases": { "description": "D1 databases used for Pages Functions.", "type": "object", "example": { "D1_BINDING": { "id": "445e2955-951a-43f8-a35b-a4d0c8138f63" } }, "additionalProperties": { "description": "D1 binding.", "nullable": true, "properties": { "id": { "description": "UUID of the D1 database.", "type": "string", "example": "445e2955-951a-43f8-a35b-a4d0c8138f63", "x-auditable": true } }, "required": [ "id" ], "type": "object" } }, "durable_object_namespaces": { "description": "Durable Object namespaces used for Pages Functions.", "type": "object", "example": { "DO_BINDING": { "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3" } }, "additionalProperties": { "description": "Durable Object binding.", "nullable": true, "properties": { "namespace_id": { "description": "ID of the Durable Object namespace.", "type": "string", "example": "5eb63bbbe01eeed093cb22bb8f5acdc3", "x-auditable": true } }, "required": [ "namespace_id" ], "type": "object" } }, "env_vars": { "description": "Environment variables used for builds and Pages Functions.", "type": "object", "additionalProperties": { "discriminator": { "mapping": { "plain_text": "#/components/schemas/pages_plain_text_env_var", "secret_text": "#/components/schemas/pages_secret_text_env_var" }, "propertyName": "type" }, "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/pages_plain_text_env_var" }, { "$ref": "#/components/schemas/pages_secret_text_env_var" } ], "type": "object" } }, "fail_open": { "description": "Whether to fail open when the deployment config cannot be applied.", "type": "boolean", "example": true, "default": true, "x-auditable": true }, "hyperdrive_bindings": { "description": "Hyperdrive bindings used for Pages Functions.", "type": "object", "example": { "HYPERDRIVE": { "id": "a76a99bc342644deb02c38d66082262a" } }, "additionalProperties": { "description": "Hyperdrive binding.", "nullable": true, "properties": { "id": { "type": "string", "example": "a76a99bc342644deb02c38d66082262a", "x-auditable": true } }, "required": [ "id" ], "type": "object" } }, "kv_namespaces": { "description": "KV namespaces used for Pages Functions.", "type": "object", "example": { "KV_BINDING": { "namespace_id": "5eb63bbbe01eeed093cb22bb8f5acdc3" } }, "additionalProperties": { "description": "KV namespace binding.", "nullable": true, "properties": { "namespace_id": { "description": "ID of the KV namespace.", "type": "string", "example": "5eb63bbbe01eeed093cb22bb8f5acdc3", "x-auditable": true } }, "required": [ "namespace_id" ], "type": "object" } }, "limits": { "description": "Limits for Pages Functions.", "type": "object", "example": { "cpu_ms": 100 }, "properties": { "cpu_ms": { "description": "CPU time limit in milliseconds.", "type": "integer", "example": 100, "x-auditable": true } }, "required": [ "cpu_ms" ] }, "mtls_certificates": { "description": "mTLS bindings used for Pages Functions.", "type": "object", "example": { "MTLS": { "certificate_id": "d7cdd17c-916f-4cb7-aabe-585eb382ec4e" } }, "additionalProperties": { "description": "mTLS binding.", "nullable": true, "properties": { "certificate_id": { "type": "string", "example": "d7cdd17c-916f-4cb7-aabe-585eb382ec4e", "x-auditable": true } }, "required": [ "certificate_id" ], "type": "object" } }, "placement": { "description": "Placement setting used for Pages Functions.", "type": "object", "example": { "mode": "smart" }, "properties": { "mode": { "description": "Placement mode.", "type": "string", "example": "smart", "x-auditable": true } }, "required": [ "mode" ] }, "queue_producers": { "description": "Queue Producer bindings used for Pages Functions.", "type": "object", "example": { "QUEUE_PRODUCER_BINDING": { "name": "some-queue" } }, "additionalProperties": { "description": "Queue Producer binding.", "nullable": true, "properties": { "name": { "description": "Name of the Queue.", "type": "string", "example": "some-queue", "x-auditable": true } }, "required": [ "name" ], "type": "object" } }, "r2_buckets": { "description": "R2 buckets used for Pages Functions.", "type": "object", "example": { "R2_BINDING": { "name": "some-bucket" } }, "additionalProperties": { "description": "R2 binding.", "nullable": true, "properties": { "jurisdiction": { "description": "Jurisdiction of the R2 bucket.", "type": "string", "example": "eu", "nullable": true, "x-auditable": true }, "name": { "description": "Name of the R2 bucket.", "type": "string", "example": "some-bucket", "x-auditable": true } }, "required": [ "name" ], "type": "object" } }, "services": { "description": "Services used for Pages Functions.", "type": "object", "example": { "SERVICE_BINDING": { "entrypoint": "MyHandler", "environment": "production", "service": "example-worker" } }, "additionalProperties": { "description": "Service binding.", "nullable": true, "properties": { "entrypoint": { "description": "The entrypoint to bind to.", "type": "string", "nullable": true, "x-auditable": true }, "environment": { "description": "The Service environment.", "type": "string", "x-auditable": true }, "service": { "description": "The Service name.", "type": "string", "x-auditable": true } }, "required": [ "service" ], "type": "object" } }, "usage_model": { "description": "The usage model for Pages Functions.", "type": "string", "example": "standard", "default": "standard", "enum": [ "standard", "bundled", "unbound" ], "deprecated": true, "x-auditable": true, "x-stainless-deprecation-message": "All new projects now use the Standard usage model." }, "vectorize_bindings": { "description": "Vectorize bindings used for Pages Functions.", "type": "object", "example": { "VECTORIZE": { "index_name": "my_index" } }, "additionalProperties": { "description": "Vectorize binding.", "nullable": true, "properties": { "index_name": { "type": "string", "example": "my_index", "x-auditable": true } }, "required": [ "index_name" ], "type": "object" } }, "wrangler_config_hash": { "description": "Hash of the Wrangler configuration used for the deployment.", "type": "string", "example": "abc123def456", "x-auditable": true } } }, "pages_deployment_log": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "line": { "type": "string", "readOnly": true }, "ts": { "type": "string", "readOnly": true } }, "required": [ "ts", "line" ], "type": "object" } }, "includes_container_logs": { "type": "boolean", "readOnly": true }, "total": { "type": "integer", "readOnly": true } }, "example": { "data": [ { "line": "Cloning repository...", "ts": "2021-04-20T19:35:29.0749819Z" }, { "line": "From https://github.com/cloudflare/example", "ts": "2021-04-20T19:35:30.0749819Z" }, { "line": " * branch 209c5bb11d89533f426b2f8469bcae12fdccf71b -> FETCH_HEAD", "ts": "2021-04-20T19:35:30.0749819Z" }, { "line": "", "ts": "2021-04-20T19:35:30.0749819Z" }, { "line": "HEAD is now at 209c5bb Update index.html", "ts": "2021-04-20T19:35:30.0749819Z" }, { "line": "", "ts": "2021-04-20T19:35:30.0749819Z" }, { "line": "", "ts": "2021-04-20T19:35:30.0749819Z" }, { "line": "Success: Finished cloning repository files", "ts": "2021-04-20T19:35:30.0749819Z" }, { "line": "Installing dependencies", "ts": "2021-04-20T19:35:59.0749819Z" }, { "line": "Python version set to 2.7", "ts": "2021-04-20T19:35:59.0931208Z" }, { "line": "v12.18.0 is already installed.", "ts": "2021-04-20T19:36:02.2369501Z" }, { "line": "Now using node v12.18.0 (npm v6.14.4)", "ts": "2021-04-20T19:36:02.6028886Z" }, { "line": "Started restoring cached build plugins", "ts": "2021-04-20T19:36:02.624555Z" }, { "line": "Finished restoring cached build plugins", "ts": "2021-04-20T19:36:02.6340688Z" }, { "line": "Attempting ruby version 2.7.1, read from environment", "ts": "2021-04-20T19:36:02.963095Z" }, { "line": "Using ruby version 2.7.1", "ts": "2021-04-20T19:36:04.2236084Z" }, { "line": "Using PHP version 5.6", "ts": "2021-04-20T19:36:04.5450152Z" }, { "line": "5.2 is already installed.", "ts": "2021-04-20T19:36:04.5740509Z" }, { "line": "Using Swift version 5.2", "ts": "2021-04-20T19:36:04.577035Z" }, { "line": "Installing Hugo 0.54.0", "ts": "2021-04-20T19:36:04.5771615Z" }, { "line": "Hugo Static Site Generator v0.54.0-B1A82C61A/extended linux/amd64 BuildDate: 2019-02-01T10:04:38Z", "ts": "2021-04-20T19:36:05.4786868Z" }, { "line": "Started restoring cached go cache", "ts": "2021-04-20T19:36:05.4794366Z" }, { "line": "Finished restoring cached go cache", "ts": "2021-04-20T19:36:05.481977Z" }, { "line": "go version go1.14.4 linux/amd64", "ts": "2021-04-20T19:36:05.9049776Z" }, { "line": "go version go1.14.4 linux/amd64", "ts": "2021-04-20T19:36:05.9086053Z" }, { "line": "Installing missing commands", "ts": "2021-04-20T19:36:05.9163568Z" }, { "line": "Verify run directory", "ts": "2021-04-20T19:36:05.9163934Z" }, { "line": "Executing user command: echo \"skipping build step: no build command specified\"", "ts": "2021-04-20T19:36:05.9164636Z" }, { "line": "skipping build step: no build command specified", "ts": "2021-04-20T19:36:05.9165087Z" }, { "line": "Finished", "ts": "2021-04-20T19:36:05.917412Z" } ], "includes_container_logs": true, "total": 30 }, "required": [ "total", "includes_container_logs", "data" ] }, "pages_deployments": { "$ref": "#/components/schemas/pages_deployment" }, "pages_domain": { "type": "object", "properties": { "certificate_authority": { "type": "string", "example": "lets_encrypt", "enum": [ "google", "lets_encrypt" ], "readOnly": true, "x-auditable": true }, "created_on": { "type": "string", "readOnly": true, "x-auditable": true }, "domain_id": { "type": "string", "readOnly": true, "x-auditable": true }, "id": { "type": "string", "readOnly": true, "x-auditable": true }, "name": { "$ref": "#/components/schemas/pages_domain_name" }, "status": { "type": "string", "enum": [ "initializing", "pending", "active", "deactivated", "blocked", "error" ], "readOnly": true, "x-auditable": true }, "validation_data": { "type": "object", "properties": { "error_message": { "type": "string", "x-auditable": true }, "method": { "type": "string", "enum": [ "http", "txt" ], "x-auditable": true }, "status": { "type": "string", "enum": [ "initializing", "pending", "active", "deactivated", "error" ], "x-auditable": true }, "txt_name": { "type": "string", "x-auditable": true }, "txt_value": { "type": "string", "x-auditable": true } }, "readOnly": true, "required": [ "status", "method" ] }, "verification_data": { "type": "object", "properties": { "error_message": { "type": "string", "x-auditable": true }, "status": { "type": "string", "enum": [ "pending", "active", "deactivated", "blocked", "error" ] } }, "readOnly": true, "required": [ "status" ] }, "zone_tag": { "type": "string", "readOnly": true, "x-auditable": true } }, "required": [ "id", "domain_id", "name", "status", "created_on", "certificate_authority", "zone_tag", "validation_data", "verification_data" ] }, "pages_domain_name": { "description": "The domain name.", "type": "string", "example": "this-is-my-domain-01.com", "pattern": "^([a-zA-Z0-9][\\-a-zA-Z0-9]*\\.)+[\\-a-zA-Z0-9]{2,20}$", "x-auditable": true }, "pages_env_vars": { "description": "Environment variables used for builds and Pages Functions.", "type": "object", "additionalProperties": { "discriminator": { "mapping": { "plain_text": "#/components/schemas/pages_plain_text_env_var", "secret_text": "#/components/schemas/pages_secret_text_env_var" }, "propertyName": "type" }, "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/pages_plain_text_env_var" }, { "$ref": "#/components/schemas/pages_secret_text_env_var" } ], "type": "object" }, "nullable": true }, "pages_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "pages_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "pages_pages_assets_check_missing_request": { "type": "object", "properties": { "hashes": { "description": "List of file content hashes to check for existence in the asset store.", "type": "array", "items": { "type": "string" }, "example": [ "a948904f2f0f479b8f936b8a0c5d9882", "b026324c6904b2a9cb4b88d6d61c81d1" ] } }, "required": [ "hashes" ] }, "pages_pages_assets_check_missing_response": { "allOf": [ { "$ref": "#/components/schemas/pages_api-response-common" }, { "properties": { "result": { "description": "List of file content hashes that are missing from the asset store and need to be uploaded.", "type": "array", "items": { "type": "string" }, "example": [ "b026324c6904b2a9cb4b88d6d61c81d1" ] } }, "required": [ "result" ], "type": "object" } ] }, "pages_pages_assets_upload_request": { "type": "array", "items": { "properties": { "base64": { "description": "Whether value is base64 encoded.", "type": "boolean", "example": true }, "key": { "description": "File content hash used as the object key in the Pages asset store.", "type": "string", "example": "b026324c6904b2a9cb4b88d6d61c81d1" }, "metadata": { "type": "object", "properties": { "contentType": { "description": "MIME type for the uploaded file.", "type": "string", "example": "text/plain" } }, "required": [ "contentType" ] }, "value": { "description": "File content. When base64 is true, this value is base64 encoded.", "type": "string", "example": "SGVsbG8sIFdvcmxkIQ==" } }, "required": [ "key", "value", "metadata", "base64" ], "type": "object" } }, "pages_pages_assets_upsert_hashes_request": { "type": "object", "properties": { "hashes": { "description": "List of file content hashes to register in the asset store.", "type": "array", "items": { "type": "string" }, "example": [ "a948904f2f0f479b8f936b8a0c5d9882", "b026324c6904b2a9cb4b88d6d61c81d1" ] } }, "required": [ "hashes" ] }, "pages_pages_upload_token_response": { "type": "object", "properties": { "jwt": { "description": "Short-lived JWT used to authenticate Pages Direct Upload asset operations.", "type": "string", "x-sensitive": true } }, "required": [ "jwt" ] }, "pages_plain_text_env_var": { "description": "A plaintext environment variable.", "type": "object", "properties": { "type": { "type": "string", "enum": [ "plain_text" ], "x-auditable": true }, "value": { "description": "Environment variable value.", "type": "string" } }, "example": { "type": "plain_text", "value": "hello world" }, "nullable": true, "required": [ "type", "value" ] }, "pages_project": { "type": "object", "properties": { "build_config": { "$ref": "#/components/schemas/pages_build_config" }, "canonical_deployment": { "allOf": [ { "$ref": "#/components/schemas/pages_deployment" }, { "description": "Most recent production deployment of the project.", "nullable": true, "readOnly": true, "type": "object" } ] }, "created_on": { "description": "When the project was created.", "type": "string", "format": "date-time", "example": "2017-01-01T00:00:00Z", "readOnly": true, "x-auditable": true }, "deployment_configs": { "description": "Configs for deployments in a project.", "type": "object", "properties": { "preview": { "description": "Configs for preview deploys.", "allOf": [ { "$ref": "#/components/schemas/pages_deployment_config_values" } ] }, "production": { "description": "Configs for production deploys.", "allOf": [ { "$ref": "#/components/schemas/pages_deployment_config_values" } ] } }, "required": [ "production", "preview" ] }, "domains": { "description": "A list of associated custom domains for the project.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "customdomain.com", "customdomain.org" ], "readOnly": true }, "framework": { "description": "Framework the project is using.", "type": "string", "readOnly": true, "x-auditable": true }, "framework_version": { "description": "Version of the framework the project is using.", "type": "string", "readOnly": true, "x-auditable": true }, "id": { "description": "ID of the project.", "type": "string", "example": "7b162ea7-7367-4d67-bcde-1160995d5", "readOnly": true, "x-auditable": true }, "latest_deployment": { "allOf": [ { "$ref": "#/components/schemas/pages_deployment" }, { "description": "Most recent deployment of the project.", "nullable": true, "readOnly": true, "type": "object" } ] }, "name": { "$ref": "#/components/schemas/pages_project_name" }, "preview_script_name": { "description": "Name of the preview script.", "type": "string", "example": "pages-worker--1234567-preview", "readOnly": true, "x-auditable": true }, "production_branch": { "description": "Production branch of the project. Used to identify production deployments.", "type": "string", "example": "main", "x-auditable": true }, "production_script_name": { "description": "Name of the production script.", "type": "string", "example": "pages-worker--1234567-production", "readOnly": true, "x-auditable": true }, "source": { "$ref": "#/components/schemas/pages_source" }, "subdomain": { "description": "The Cloudflare subdomain associated with the project.", "type": "string", "example": "helloworld.pages.dev", "readOnly": true, "x-auditable": true }, "uses_functions": { "description": "Whether the project uses functions.", "type": "boolean", "nullable": true, "readOnly": true, "x-auditable": true } }, "required": [ "id", "name", "deployment_configs", "latest_deployment", "canonical_deployment", "created_on", "production_branch", "production_script_name", "preview_script_name", "uses_functions", "framework", "framework_version" ] }, "pages_project-object": { "$ref": "#/components/schemas/pages_project" }, "pages_project_name": { "description": "Name of the project.", "type": "string", "example": "this-is-my-project-01", "pattern": "^[a-z0-9][a-z0-9-]*$", "x-auditable": true }, "pages_secret_text_env_var": { "description": "An encrypted environment variable.", "type": "object", "properties": { "type": { "type": "string", "enum": [ "secret_text" ], "x-auditable": true }, "value": { "description": "Secret value.", "type": "string", "x-sensitive": true } }, "example": { "type": "secret_text", "value": "" }, "nullable": true, "required": [ "type", "value" ] }, "pages_source": { "description": "Configs for the project source control.", "type": "object", "properties": { "config": { "type": "object", "properties": { "deployments_enabled": { "description": "Whether to enable automatic deployments when pushing to the source repository.\nWhen disabled, no deployments (production or preview) will be triggered automatically.\n", "type": "boolean", "deprecated": true, "x-auditable": true, "x-stainless-deprecation-message": "Use `production_deployments_enabled` and `preview_deployment_setting` for more granular control." }, "owner": { "description": "The owner of the repository.", "type": "string", "example": "my-org", "x-auditable": true }, "owner_id": { "description": "The owner ID of the repository.", "type": "string", "example": "12345678", "x-auditable": true }, "path_excludes": { "description": "A list of paths that should be excluded from triggering a preview deployment. Wildcard syntax (`*`) is supported.", "type": "array", "items": { "type": "string", "x-auditable": true } }, "path_includes": { "description": "A list of paths that should be watched to trigger a preview deployment. Wildcard syntax (`*`) is supported.", "type": "array", "items": { "type": "string", "x-auditable": true } }, "pr_comments_enabled": { "description": "Whether to enable PR comments.", "type": "boolean", "x-auditable": true }, "preview_branch_excludes": { "description": "A list of branches that should not trigger a preview deployment. Wildcard syntax (`*`) is supported. Must be used with `preview_deployment_setting` set to `custom`.", "type": "array", "items": { "type": "string", "x-auditable": true } }, "preview_branch_includes": { "description": "A list of branches that should trigger a preview deployment. Wildcard syntax (`*`) is supported. Must be used with `preview_deployment_setting` set to `custom`.", "type": "array", "items": { "type": "string", "x-auditable": true } }, "preview_deployment_setting": { "description": "Controls whether commits to preview branches trigger a preview deployment.", "type": "string", "enum": [ "all", "none", "custom" ], "x-auditable": true }, "production_branch": { "description": "The production branch of the repository.", "type": "string", "example": "main", "x-auditable": true }, "production_deployments_enabled": { "description": "Whether to trigger a production deployment on commits to the production branch.", "type": "boolean", "x-auditable": true }, "repo_id": { "description": "The ID of the repository.", "type": "string", "example": "12345678", "x-auditable": true }, "repo_name": { "description": "The name of the repository.", "type": "string", "example": "my-repo", "x-auditable": true } }, "required": [ "deployments_enabled", "owner", "owner_id", "path_excludes", "path_includes", "pr_comments_enabled", "preview_branch_excludes", "preview_branch_includes", "preview_deployment_setting", "production_branch", "production_deployments_enabled", "repo_id", "repo_name" ] }, "type": { "description": "The source control management provider.", "type": "string", "example": "github", "enum": [ "github", "gitlab" ], "x-auditable": true } }, "required": [ "type", "config" ] }, "pages_stage": { "description": "The status of the deployment.", "type": "object", "properties": { "ended_on": { "description": "When the stage ended.", "type": "string", "format": "date-time", "example": "2021-03-09T00:58:59.045655", "nullable": true, "readOnly": true, "x-auditable": true }, "name": { "description": "The current build stage.", "type": "string", "example": "deploy", "enum": [ "queued", "initialize", "clone_repo", "build", "deploy" ], "x-auditable": true }, "started_on": { "description": "When the stage started.", "type": "string", "format": "date-time", "example": "2021-03-09T00:55:03.923456Z", "nullable": true, "readOnly": true, "x-auditable": true }, "status": { "description": "State of the current stage.", "type": "string", "example": "success", "enum": [ "success", "idle", "active", "failure", "canceled" ], "readOnly": true, "x-auditable": true } }, "readOnly": true, "required": [ "name", "started_on", "ended_on", "status" ] }, "pages_tail": { "description": "A tail session for streaming logs from a Pages deployment.", "type": "object", "properties": { "id": { "description": "Identifier of the tail session.", "type": "string", "example": "49a4dcf81a3940fab8453b2be3fb86ef", "readOnly": true }, "url": { "description": "Optional WebSocket URL to connect to for receiving tail events, when returned by the tail service.", "type": "string", "example": "wss://tail.developers.workers.dev/49a4dcf81a3940fab8453b2be3fb86ef", "readOnly": true } }, "required": [ "id" ] }, "pay-per-crawl_BotAccessMode": { "type": "string", "enum": [ "charge", "bypass" ] }, "pay-per-crawl_CrawlerEntry": { "type": "object", "properties": { "bot_management": { "type": "boolean" }, "category": { "type": "string" }, "category_id": { "type": "integer" }, "heuristic_id": { "type": "integer", "format": "int64", "nullable": true }, "info_url": { "type": "string", "format": "uri", "nullable": true }, "managed": { "type": "boolean" }, "name": { "type": "string" }, "onboarded": { "type": "boolean" }, "operator": { "type": "string" }, "slug": { "type": "string" }, "testing_id": { "type": "string", "nullable": true }, "user_agent": { "type": "string", "nullable": true }, "verified_id": { "type": "integer", "format": "int64", "nullable": true }, "visible": { "type": "boolean" }, "wba_id": { "type": "string", "nullable": true } } }, "pay-per-crawl_DaricConfig": { "type": "object", "properties": { "bot_overrides": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/pay-per-crawl_BotAccessMode" } }, "enabled": { "type": "boolean" }, "price_usd_microcents": { "description": "Price in microcents 1 USD = 100,000,000 microcents. Must be 0 or a multiple of 100,000 $0.001. Range: $0.001–$9,999.999.", "type": "integer", "maximum": 999999900000, "minimum": 0 } } }, "pay-per-crawl_DaricZoneCanBeEnabled": { "type": "object", "properties": { "can_be_enabled": { "type": "boolean" }, "enabled": { "type": "boolean" }, "id": { "type": "string" } } }, "pay-per-crawl_ErrorSource": { "type": "object", "properties": { "pointer": { "type": "string" } } }, "pay-per-crawl_IronCladContract": { "type": "object", "properties": { "body": { "type": "string" }, "id": { "type": "string" } } }, "pay-per-crawl_Msg": { "type": "object", "properties": { "code": { "type": "integer" }, "documentation_url": { "type": "string" }, "error_chain": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "message": { "type": "string" }, "meta": { "description": "Meta object containing non-standard meta-information about the error.\nThis field must be an object or null!" }, "source": { "$ref": "#/components/schemas/pay-per-crawl_Source" } } }, "pay-per-crawl_RESTError": { "type": "object", "properties": { "code": { "type": "integer" }, "documentation_url": { "type": "string" }, "error": { "type": "string" }, "source": { "$ref": "#/components/schemas/pay-per-crawl_ErrorSource" } } }, "pay-per-crawl_ResultInfo": { "type": "object", "properties": { "count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_count": { "type": "integer" }, "total_pages": { "description": "TotalPages is a pointer so that if TotalPages == 0 we return that there\nare indeed 0 pages. omitempty would have removed the field otherwise.\nThis is important as a customer may be relying on always reading this\nproperty and it should not be absent just because it is 0, only absent\nif a value is never provided.", "type": "integer" } } }, "pay-per-crawl_SignatureLinkResponse": { "type": "object", "properties": { "link": { "type": "string", "format": "uri" } } }, "pay-per-crawl_Source": { "type": "object", "properties": { "parameter": { "description": "Parameter is a string indicating which URI query parameter caused the error.", "type": "string" }, "parameter_value_index": { "description": "ParameterPosition indicates position of parameter value which caused the error,\nfor cases when there are multiple values for the same parameter.", "type": "integer" }, "pointer": { "description": "Pointer is a JSON Pointer [RFC6901] to the associated entity in the request document\ne.g. \"/data\" for a primary data object, or \"/data/attributes/title\" for a specific attribute.", "type": "array", "items": { "type": "string" } } } }, "pay-per-crawl_StripeConnectResp": { "type": "object", "properties": { "url": { "type": "string" } } }, "pay-per-crawl_StripeConnection": { "type": "object", "properties": { "connect_status": { "type": "string" }, "stripe_account_id": { "type": "string" } } }, "pay-per-crawl_ZonesCanBeEnabledPayload": { "type": "object", "properties": { "zones": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_DaricZoneCanBeEnabled" } } } }, "pay-per-crawl_ZonesCanBeEnabledQueryPayload": { "type": "object", "properties": { "zones": { "type": "array", "items": { "type": "string" } } } }, "pay-per-crawl_apiErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_RESTError" } }, "result": {}, "success": { "type": "boolean" } } }, "pay-per-crawl_apiNoResultResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "result_info": { "$ref": "#/components/schemas/pay-per-crawl_ResultInfo" }, "success": { "type": "boolean" } } }, "pay-per-crawl_createStripeConfigResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "result": { "$ref": "#/components/schemas/pay-per-crawl_StripeConnectResp" }, "result_info": { "$ref": "#/components/schemas/pay-per-crawl_ResultInfo" }, "success": { "type": "boolean" } } }, "pay-per-crawl_getConfigResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "result": { "$ref": "#/components/schemas/pay-per-crawl_DaricConfig" }, "result_info": { "$ref": "#/components/schemas/pay-per-crawl_ResultInfo" }, "success": { "type": "boolean" } } }, "pay-per-crawl_getStripeConfigResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "result": { "$ref": "#/components/schemas/pay-per-crawl_StripeConnection" }, "result_info": { "$ref": "#/components/schemas/pay-per-crawl_ResultInfo" }, "success": { "type": "boolean" } } }, "pay-per-crawl_getTermsResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "result": { "$ref": "#/components/schemas/pay-per-crawl_IronCladContract" }, "result_info": { "$ref": "#/components/schemas/pay-per-crawl_ResultInfo" }, "success": { "type": "boolean" } } }, "pay-per-crawl_getTermsSignatureLinkResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "result": { "$ref": "#/components/schemas/pay-per-crawl_SignatureLinkResponse" }, "result_info": { "$ref": "#/components/schemas/pay-per-crawl_ResultInfo" }, "success": { "type": "boolean" } } }, "pay-per-crawl_getTermsSignatureResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "result": { "type": "string", "nullable": true }, "result_info": { "$ref": "#/components/schemas/pay-per-crawl_ResultInfo" }, "success": { "type": "boolean" } } }, "pay-per-crawl_getZoneCanBeEnabledResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "result": { "$ref": "#/components/schemas/pay-per-crawl_DaricZoneCanBeEnabled" }, "result_info": { "$ref": "#/components/schemas/pay-per-crawl_ResultInfo" }, "success": { "type": "boolean" } } }, "pay-per-crawl_listCrawlersResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "result": { "type": "object", "properties": { "crawlers": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_CrawlerEntry" } } } }, "result_info": { "$ref": "#/components/schemas/pay-per-crawl_ResultInfo" }, "success": { "type": "boolean" } } }, "pay-per-crawl_queryZonesCanBeEnabledResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/pay-per-crawl_Msg" } }, "result": { "$ref": "#/components/schemas/pay-per-crawl_ZonesCanBeEnabledPayload" }, "result_info": { "$ref": "#/components/schemas/pay-per-crawl_ResultInfo" }, "success": { "type": "boolean" } } }, "posture-api_Asset": { "description": "Asset information including metadata and categorization.", "type": "object", "properties": { "category": { "$ref": "#/components/schemas/posture-api_AssetCategory" }, "external_id": { "description": "External identifier from the source system.", "type": "string", "example": "external-file-id-123", "maxLength": 512 }, "fields": { "description": "The fields associated with the asset.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_AssetField" }, "readOnly": true }, "id": { "description": "Unique identifier for the asset.", "type": "string", "format": "uuid", "example": "8a043daf-def4-403e-9d28-da2e93d9b824" }, "link": { "description": "Direct link to the asset.", "type": "string", "format": "uri", "example": "https://slack-files.com/TYJH37DCK-E0238GG6B8-92fd5y5674", "maxLength": 2048, "nullable": true }, "name": { "description": "Human-readable name of the asset.", "type": "string", "example": "Public.svg" } }, "example": { "external_id": "external-file-id-123", "id": "8a043daf-def4-403e-9d28-da2e93d9b824", "link": "https://slack-files.com/TYJH37DCK-E0238GG6B8-92fd5y5674", "name": "Public.svg" }, "required": [ "category", "external_id", "fields", "name" ] }, "posture-api_AssetCategory": { "description": "Category information for an asset.", "type": "object", "properties": { "id": { "description": "Unique identifier for the asset category.", "type": "string", "format": "uuid", "example": "1a78cbf3-b98f-4289-b1f2-22db64130f4f" }, "service": { "description": "The specific service within the vendor the asset is part of (often none). Example - AWS is the vendor, S3 is the service.", "type": "string", "example": "OneDrive", "nullable": true }, "type": { "description": "The type of asset.", "type": "string", "example": "file" }, "vendor": { "description": "The vendor the asset is part of.", "type": "string", "example": "Slack", "readOnly": true } }, "example": { "id": "1a78cbf3-b98f-4289-b1f2-22db64130f4f", "service": null, "type": "file", "vendor": "Slack" }, "required": [ "service", "type", "vendor" ] }, "posture-api_AssetField": { "description": "Additional field information for an asset.", "type": "object", "properties": { "link": { "description": "Optional link associated with the field.", "type": "string", "format": "uri", "example": "https://example.com", "nullable": true }, "name": { "description": "The name of the field.", "type": "string", "example": "File Name" }, "value": { "description": "The value of the field.", "type": "string", "example": "sensitive-document.xlsx" } }, "example": { "link": "https://example.com", "name": "Credential name", "value": "Test asset 2" }, "required": [ "name", "value" ] }, "posture-api_BaseFindingType": { "description": "Basic finding type information.", "type": "object", "properties": { "category": { "$ref": "#/components/schemas/posture-api_FindingCategory" }, "description": { "description": "Detailed description of the finding.", "type": "string", "example": "This finding indicates that a file in your Slack workspace is publicly accessible.", "nullable": true }, "id": { "description": "The unique identifier of the finding.", "type": "string", "format": "uuid", "example": "a20895dd-9c3b-43bd-a608-71c98c6c2d94" }, "name": { "description": "The name of the finding.", "type": "string", "example": "Slack File Publicly Accessible" }, "severity": { "$ref": "#/components/schemas/posture-api_SeverityEnum" }, "vendor": { "description": "The SaaS/Cloud vendor of the platform with which the finding is associated.", "type": "string", "example": "Google Workspace" } }, "required": [ "id", "name", "category", "vendor", "severity" ] }, "posture-api_ContentAsset": { "description": "Content asset with DLP information.", "type": "object", "properties": { "asset_id": { "description": "Unique identifier for the asset.", "type": "string", "format": "uuid", "example": "e6910838-4b91-45e9-b2b4-91bb23cb9762" }, "asset_name": { "description": "Name of the asset.", "type": "string", "example": "Test Asset Name" }, "dlp_contexts": { "description": "DLP context information for this asset.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_DlpContext" } }, "dlp_profile_count": { "description": "Number of DLP profiles that flagged this asset.", "type": "integer", "example": 2 }, "dlp_profile_ids": { "description": "IDs of DLP profiles that flagged this asset.", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "c12f2059-8df4-43f8-9eb9-d27112d92b63", "822c051b-0bb4-4747-8929-471a1d506eef" ] }, "integration": { "$ref": "#/components/schemas/posture-api_IntegrationSummary" }, "latest_affliction_date": { "description": "Most recent date this asset was flagged.", "type": "string", "format": "date-time", "example": "2024-10-18T19:53:57.626659Z" } }, "required": [ "asset_id", "asset_name", "latest_affliction_date", "dlp_profile_ids", "dlp_profile_count", "dlp_contexts", "integration" ] }, "posture-api_ContentExportRequest": { "description": "Request body for creating content exports.", "type": "object", "properties": { "dlp_profile_id": { "description": "Filter by DLP profile IDs.", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "e91a2360-da51-4fdf-9711-bcdecd462614" ] }, "dlp_profile_information": { "description": "DLP profile metadata for the export.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_DLPProfile" } }, "integration_id": { "description": "Filter by integration IDs.", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "c416bc38-75dc-425f-ae25-c37b5df5c37f" ] }, "max_affliction_date": { "description": "Filter to view content flagged on or before this date.", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "min_affliction_date": { "description": "Filter to view content flagged on or after this date.", "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" }, "orders": { "description": "Ordering specifications for the export.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_ContentOrder" } }, "search": { "description": "Search term to filter content.", "type": "string", "example": "sensitive" }, "vendors": { "description": "Filter by vendor types.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_VendorsEnum" }, "example": [ "GOOGLE_WORKSPACE" ] } }, "required": [ "dlp_profile_information" ] }, "posture-api_ContentOrder": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/posture-api_Order" }, { "properties": { "name": { "description": "Content-specific field names for ordering.", "type": "string", "example": "asset_name", "enum": [ "asset_name", "dlp_profile_count", "integration_name", "latest_affliction_date" ] } }, "required": [ "name" ], "type": "object" } ] }, "posture-api_CreatePolicyRequest": { "description": "Request body for creating a new policy configuration.", "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/posture-api_PolicyActionsInput" }, "applies_to_all_integrations": { "description": "When true, the policy applies to all integrations for the account. When false, integration_ids must be provided.", "type": "boolean", "example": false }, "description": { "description": "Optional description of what this policy does.", "type": "string", "example": "Automatically remove public access from files when detected", "maxLength": 1000, "x-stainless-terraform-configurability": "computed_optional" }, "display_name": { "description": "Display name for the policy configuration.", "type": "string", "example": "Auto-remediate public files", "maxLength": 255 }, "enabled": { "description": "Boolean specifying if the policy is enabled or disabled.", "type": "boolean", "example": true }, "finding_type_id": { "description": "The finding type this policy is associated with. All remediation actions must match this finding type.", "type": "string", "format": "uuid", "example": "5a7d9e2f-1b3c-4d5e-8f6a-7b8c9d0e1f2a" }, "integration_ids": { "description": "The integrations this policy applies to. Required when applies_to_all_integrations is false.", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "display_name", "enabled", "applies_to_all_integrations", "finding_type_id", "actions" ] }, "posture-api_CreateRemediationJobResponse": { "description": "Response for remediation job creation requests.", "type": "object", "properties": { "errors": { "description": "Array of error messages.", "type": "array", "items": { "type": "object" }, "example": [] }, "messages": { "description": "Array of informational messages.", "type": "array", "items": { "type": "object" }, "example": [] }, "result": { "type": "object", "properties": { "created": { "description": "Successfully created remediation jobs.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_RemediationJob" } }, "failed": { "description": "Failed remediation job creation attempts.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_RemediationJobFailure" } } }, "required": [ "created", "failed" ] }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages", "result" ] }, "posture-api_CreateWebhookJobsRequest": { "description": "Request body for creating up to 100 webhook jobs. The number of jobs is the product of webhook_ids and finding_instance_ids.", "type": "object", "properties": { "finding_instance_ids": { "description": "Array of finding instance IDs to send to the webhooks.", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "770e8400-e29b-41d4-a716-446655440002", "660e8400-e29b-41d4-a716-446655440001" ] }, "webhook_ids": { "description": "Array of webhook IDs to trigger jobs for.", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "550e8400-e29b-41d4-a716-446655440000", "660e8400-e29b-41d4-a716-446655440001" ], "minItems": 1 } }, "required": [ "webhook_ids", "finding_instance_ids" ] }, "posture-api_CreateWebhookJobsResponse": { "description": "Response for webhook job creation requests.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/posture-api_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "created": { "description": "Successfully created webhook jobs.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_WebhookJob" } }, "failed": { "description": "Failed webhook job creation attempts.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_WebhookJobFailure" } } }, "required": [ "created", "failed" ] } }, "required": [ "result" ], "type": "object" } ] }, "posture-api_CreateWebhookRequest": { "description": "Request body for creating a new webhook configuration.", "type": "object", "properties": { "authentication_type": { "description": "Type of authentication used for the webhook.", "type": "string", "example": "Bearer Auth", "enum": [ "Basic Auth", "None", "Bearer Auth", "Static Headers", "HMAC-Signing" ] }, "destination_url": { "description": "Target URL for the webhook configuration. Where resulting data will be sent.", "type": "string", "format": "uri", "example": "https://example.com/webhook" }, "headers": { "description": "List of custom headers to include in webhook requests.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_WebhookHeaderInput" }, "example": [ { "key": "Authorization", "value": "Bearer token123" }, { "key": "X-Custom-Header", "value": "value" } ] }, "label": { "description": "Account-specified display label for the webhook configuration.", "type": "string", "example": "Send to Slack" }, "signing_secret": { "description": "Secret key used for HMAC signing when authentication_type is \"HMAC-Signing\".", "type": "string", "example": "my-secret-key" } }, "required": [ "label", "destination_url", "authentication_type" ] }, "posture-api_CredentialHealthStatusEnum": { "description": "Health status of integration credentials.", "type": "string", "example": "Healthy", "enum": [ "Initializing", "Healthy", "Unhealthy" ] }, "posture-api_DLPProfile": { "description": "DLP profile configuration.", "type": "object", "properties": { "entries": { "description": "Entries contained within this DLP profile.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_DLPProfileEntry" } }, "id": { "description": "Unique identifier for the DLP profile.", "type": "string", "format": "uuid", "example": "e91a2360-da51-4fdf-9711-bcdecd462614" }, "name": { "description": "Name of the DLP profile.", "type": "string", "example": "Financial Information" } }, "required": [ "id", "name", "entries" ] }, "posture-api_DLPProfileEntry": { "description": "Entry within a DLP profile.", "type": "object", "properties": { "id": { "description": "Unique identifier for the DLP profile entry.", "type": "string", "format": "uuid", "example": "55ba2c6c-8ef4-4b2e-9148-e75e8b6ccac1" }, "name": { "description": "Name of the DLP profile entry.", "type": "string", "example": "Credit Card Numbers" }, "profile_id": { "description": "ID of the parent DLP profile.", "type": "string", "format": "uuid", "example": "e91a2360-da51-4fdf-9711-bcdecd462614" } }, "required": [ "id", "name", "profile_id" ] }, "posture-api_DeletePolicyResponse": { "description": "Response from DeletePolicy operation.", "type": "object", "properties": { "id": { "description": "ID of the policy deleted.", "type": "string", "format": "uuid", "example": "3f7b8c9d-6e5a-4f3b-9c2d-1e0a8b7c6d5e" } }, "required": [ "id" ] }, "posture-api_DirectionEnum": { "description": "Sort direction.", "type": "string", "example": "asc", "enum": [ "asc", "desc" ] }, "posture-api_DlpContext": { "description": "DLP context information for a finding.", "type": "object", "properties": { "created": { "description": "When the DLP context was created.", "type": "string", "format": "date-time", "example": "2025-03-18T17:25:38.695977Z", "readOnly": true }, "deleted": { "description": "When the DLP context was deleted.", "type": "string", "format": "date-time", "example": "2025-03-18T17:25:38.695977Z", "nullable": true }, "entry_ids": { "description": "DLP Entry IDs.", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "21befc68-a297-4090-ac10-17a051b901cd", "d6dd1e16-f78c-401a-b564-45c4e44aa467" ] }, "id": { "description": "Unique identifier for the DLP context.", "type": "string", "format": "uuid", "example": "7653ff3a-d25e-4c10-8034-3460937c045b" }, "match_context_max_extent": { "description": "DLP Right Boundary of match context.", "type": "integer", "example": 512, "maximum": 2147483647, "minimum": 0, "nullable": true }, "match_context_min_extent": { "description": "DLP Left Boundary of match context.", "type": "integer", "example": 1, "maximum": 2147483647, "minimum": 0, "nullable": true }, "match_context_payload": { "description": "DLP Match context payload that matched the profile in question.", "type": "object", "example": {}, "additionalProperties": true, "nullable": true }, "profile_id": { "description": "DLP Profile ID.", "type": "string", "format": "uuid", "example": "ab20a60b-21f2-4b13-ac98-24dcee27ac0e" }, "updated": { "description": "When the DLP context was last updated.", "type": "string", "format": "date-time", "example": "2025-03-18T17:25:38.695977Z", "readOnly": true } }, "required": [ "created", "entry_ids", "profile_id", "updated" ] }, "posture-api_EvaluateNewWebhookRequest": { "description": "Request body for testing a webhook configuration before creating it.", "type": "object", "properties": { "authentication_type": { "description": "Type of authentication to use for the test webhook request.", "type": "string", "example": "Bearer Auth", "enum": [ "Basic Auth", "None", "Bearer Auth", "Static Headers", "HMAC-Signing" ] }, "destination_url": { "description": "Target URL to send the test webhook event to.", "type": "string", "format": "uri", "example": "https://example.com/webhook" }, "headers": { "description": "List of custom headers to include in the test webhook request.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_WebhookHeaderInput" }, "example": [ { "key": "Authorization", "value": "Bearer token123" }, { "key": "X-Custom-Header", "value": "value" } ] }, "signing_secret": { "description": "Secret key used for HMAC signing when authentication_type is \"HMAC-Signing\".", "type": "string", "example": "my-secret-key" } }, "required": [ "destination_url", "authentication_type" ] }, "posture-api_EvaluateNewWebhookResponse": { "description": "Response body for webhook evaluation test results.", "type": "object", "properties": { "message": { "description": "Human-readable message describing the test result.", "type": "string", "example": "Webhook test successful" }, "status_code": { "description": "HTTP status code returned by the webhook endpoint. 0 if connection failed.", "type": "integer", "example": 200 }, "success": { "description": "Whether the webhook test was successful (received 2xx response).", "type": "boolean", "example": true } }, "required": [ "success", "status_code", "message" ] }, "posture-api_ExportJob": { "description": "Information about an export job.", "type": "object", "properties": { "download_url": { "description": "The URL by which the successfully created export can be downloaded by the end users.", "type": "string", "format": "uri", "example": "https://example.com/45ce02c2-e797-4a71-98cb-937244352fd4", "maxLength": 1024, "nullable": true }, "errors": { "description": "Contains information on errors which may have occurred during export creation.", "type": "string", "nullable": true }, "file_name": { "description": "The base name of the file that is/was generated by the export job.", "type": "string", "example": "Finding_Instances_2024-02-27T04:05:26Z", "maxLength": 256, "nullable": true }, "file_path": { "description": "The full path of the file that is stored within external storage (currently R2).", "type": "string", "example": "/exports/finding-instances/2024/02/27/Finding_Instances_2024-02-27T04:05:26Z.csv", "maxLength": 512, "nullable": true }, "id": { "description": "Unique identifier for the export job.", "type": "string", "format": "uuid", "example": "45ce02c2-e797-4a71-98cb-937244352fd4" }, "status": { "$ref": "#/components/schemas/posture-api_StatusEnum" }, "type": { "$ref": "#/components/schemas/posture-api_ExportJobTypeEnum" }, "user_id": { "description": "ID of the export-requesting user.", "type": "string", "example": "e7712d506b1ee4c5ede0802815f55a75", "maxLength": 128 } }, "example": { "download_url": "https://example.com/45ce02c2-e797-4a71-98cb-937244352fd4", "errors": null, "file_name": "findings_export_2024-02-27.csv", "id": "45ce02c2-e797-4a71-98cb-937244352fd4", "status": "Success", "type": "finding", "user_id": "e7712d506b1ee4c5ede0802815f55a75" }, "required": [ "id", "status", "type", "user_id" ] }, "posture-api_ExportJobTypeEnum": { "description": "Type of export job.", "type": "string", "example": "finding", "enum": [ "finding", "findingInstance", "content", "remediationJob" ] }, "posture-api_Finding": { "description": "Aggregated finding information with counts and metadata. This is optimized for list API queries and represents a finding along with its instance statistics.", "type": "object", "properties": { "active_count": { "description": "Number of active problematic instances identified in the security finding.", "type": "integer", "example": 5, "readOnly": true }, "archived_count": { "description": "Number of archived instances identified in the security finding.", "type": "integer", "example": 2, "readOnly": true }, "finding": { "$ref": "#/components/schemas/posture-api_FindingType" }, "id": { "description": "Base64 encoded identifier of the security finding.", "type": "string", "format": "byte", "example": "MDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAxOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMgo=", "readOnly": true }, "ignored": { "description": "Determines if finding is currently ignored.", "type": "boolean", "example": false, "readOnly": true }, "instance_count": { "description": "Number of total (Active or archived) problematic instances identified in the security finding.", "type": "integer", "example": 7, "readOnly": true }, "integration": { "$ref": "#/components/schemas/posture-api_IntegrationSummary" }, "latest_affliction_date": { "description": "Timestamp of the latest affliction date of an active finding.", "type": "string", "format": "date-time", "example": "2025-03-18T17:25:38.700131Z", "readOnly": true }, "severity_override": { "$ref": "#/components/schemas/posture-api_FindingSeverityOverride" } }, "required": [ "active_count", "archived_count", "finding", "id", "ignored", "instance_count", "integration", "latest_affliction_date" ] }, "posture-api_FindingBulkActionRequest": { "description": "Request body for bulk actions on findings.", "type": "object", "properties": { "checks": { "description": "A list of finding IDs to pass along.", "type": "array", "items": { "maxLength": 512, "minLength": 1, "type": "string" }, "example": [ "MDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAxOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMgo=" ], "maxItems": 500, "minItems": 1 } }, "required": [ "checks" ] }, "posture-api_FindingCategory": { "description": "Category information for a finding.", "type": "object", "properties": { "observation": { "$ref": "#/components/schemas/posture-api_ObservationEnum" }, "product": { "$ref": "#/components/schemas/posture-api_ProductEnum" }, "type": { "$ref": "#/components/schemas/posture-api_FindingCategoryTypeEnum" } }, "example": { "observation": "Issue", "product": "SaaS", "type": "Posture" }, "required": [ "observation", "product", "type" ] }, "posture-api_FindingCategoryTypeEnum": { "description": "The type of the finding category.", "type": "string", "example": "Content", "enum": [ "Content", "Posture" ] }, "posture-api_FindingExportFilterRequest": { "description": "Filter specification for findings export jobs.", "type": "object", "properties": { "ignored": { "description": "Filter for only the ignored findings. Set to false to only see active items.", "type": "boolean", "example": true }, "integration_id": { "description": "Filter by multiple integration IDs.", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "55d7337e-1d0a-49fc-9826-925ba40df035" ] }, "max_affliction_date": { "description": "Filter to view findings that occurred on or before the affliction date. Can be a date-time in ISO 8601 format or an epoch timestamp.", "type": "string", "format": "date-time", "example": "2019-08-24T14:15:22Z" }, "min_affliction_date": { "description": "Filter to view findings that occurred on or after the affliction date. Can be a date-time in ISO 8601 format or an epoch timestamp.", "type": "string", "format": "date-time", "example": "2018-08-24T14:15:22Z" }, "orders": { "description": "Which fields to use when ordering the findings.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_FindingExportOrderFilterRequest" } }, "product": { "description": "Filter by finding's category product.", "type": "string", "example": "SaaS", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/posture-api_ProductEnum" }, { "$ref": "#/components/schemas/posture-api_NullEnum" } ] }, "search": { "description": "A search term.", "type": "string", "example": "public access" }, "severities": { "description": "Filter by severity levels.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_SeveritiesEnum" }, "example": [ "CRITICAL" ] }, "vendors": { "description": "Filter by vendor types.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_VendorsEnum" }, "example": [ "AWS" ] } } }, "posture-api_FindingExportOrderFilterRequest": { "description": "Order specification for finding exports.", "type": "object", "properties": { "direction": { "$ref": "#/components/schemas/posture-api_DirectionEnum" }, "name": { "description": "Which field to use when ordering the findings.", "type": "string", "example": "instance_count", "enum": [ "instance_count", "finding.name", "integration.name", "latest_affliction_date", "severity" ] } }, "required": [ "direction", "name" ] }, "posture-api_FindingInstance": { "description": "A specific instance of a security finding. In the API interface, we refer to the 'finding' table in our DB as finding instances, optimized for the p99 use case.", "type": "object", "properties": { "affliction_date": { "description": "When this specific instance was identified.", "type": "string", "format": "date-time", "example": "2025-03-18T17:25:38.700541Z" }, "asset": { "$ref": "#/components/schemas/posture-api_Asset" }, "dlp_contexts": { "description": "DLP context information if this is a content finding.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_DlpContext" }, "readOnly": true }, "id": { "description": "Unique identifier for the finding instance.", "type": "string", "format": "uuid", "example": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, "is_archived": { "description": "Whether this finding instance has been archived.", "type": "boolean", "example": false, "default": false }, "remediations": { "description": "A list of the 10 most recent remediation jobs for this finding instance, ordered by creation time (most recent first). The 'stale' field indicates whether the remediation job was created before the finding instance's affliction_date (true) or after it (false). If there has never been a remediation job for this finding instance, this field will be an empty array.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_RemediationJobSummary" } }, "webhooks": { "description": "The most recent webhook job invocation for each webhook configuration associated with this finding instance. Each entry represents the latest job (any status) per webhook config. The 'stale' field indicates whether the job was invoked before the finding instance's current affliction_date. If no webhook jobs have been created, this field will be an empty array.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_WebhookInvocationSummary" } } }, "required": [ "affliction_date", "asset", "dlp_contexts", "remediations", "webhooks" ] }, "posture-api_FindingInstanceBulkActionRequest": { "description": "Request body for bulk actions on finding instances.", "type": "object", "properties": { "check_instances": { "description": "A list of finding instance IDs to pass along.", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ] } }, "required": [ "check_instances" ] }, "posture-api_FindingInstanceExportFilterRequest": { "description": "Filter specification for finding instance exports.", "type": "object", "properties": { "archived": { "description": "Filter for archived status.", "type": "boolean", "example": false }, "max_affliction_date": { "description": "Filter to view findings that occurred on or before the affliction date. Can be a date-time in ISO 8601 format or an epoch timestamp.", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "min_affliction_date": { "description": "Filter to view findings that occurred on or after the affliction date. Can be a date-time in ISO 8601 format or an epoch timestamp.", "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" }, "orders": { "description": "Ordering specifications for the export.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_FindingInstanceExportOrderFilterRequest" }, "default": [] }, "search": { "description": "A search term.", "type": "string", "example": "sensitive data" } } }, "posture-api_FindingInstanceExportOrderFilterRequest": { "description": "Order specification for finding instance exports.", "type": "object", "properties": { "direction": { "$ref": "#/components/schemas/posture-api_DirectionEnum" }, "name": { "description": "Which field to use when ordering the finding instances.", "type": "string", "example": "asset.name", "enum": [ "asset.name", "affliction_date" ] } }, "required": [ "direction", "name" ] }, "posture-api_FindingRemediation": { "description": "Remediation guide information for a finding.", "type": "object", "properties": { "frameworks": { "description": "Relevant Compliance Frameworks.", "type": "array", "items": { "type": "string" }, "example": [ "SOC2", "ISO27001" ], "readOnly": true }, "guide": { "description": "Remediation guide text.", "type": "string", "example": "To fix this issue, update the file permissions to remove public access." }, "id": { "description": "Remediation Id.", "type": "string", "format": "uuid", "example": "a20895dd-9c3b-43bd-a608-71c98c6c2d94", "readOnly": true }, "impact": { "description": "Description of the potential impact.", "type": "string", "example": "Publicly accessible files may expose sensitive information." }, "locale": { "description": "I18N Locale.", "type": "string", "example": "en-US", "readOnly": true }, "threat": { "description": "Description of the threat.", "type": "string", "example": "Data exposure and potential compliance violations." } }, "nullable": true, "required": [ "frameworks", "guide", "id", "impact", "locale", "threat" ] }, "posture-api_FindingSeverityOverride": { "description": "Override information for finding severity.", "type": "object", "properties": { "created_by": { "description": "User ID who created the override.", "type": "string", "example": "1234" }, "severity": { "$ref": "#/components/schemas/posture-api_SeverityEnum" } }, "example": { "created_by": "1234", "severity": "Critical" }, "required": [ "created_by", "severity" ] }, "posture-api_FindingType": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/posture-api_BaseFindingType" }, { "properties": { "remediation": { "$ref": "#/components/schemas/posture-api_FindingRemediation" } }, "type": "object" } ], "required": [ "category", "id", "name", "remediation", "severity", "vendor" ] }, "posture-api_IntegrationPolicy": { "description": "Policy configuration for an integration.", "type": "object", "properties": { "client_id": { "description": "OAuth client ID for the policy.", "type": "string", "nullable": true }, "compliance_level": { "description": "Compliance level for the policy.", "type": "string", "example": "standard" }, "dlp_enabled": { "description": "Whether DLP is enabled for this policy.", "type": "boolean", "example": true }, "id": { "description": "Policy identifier.", "type": "string", "format": "uuid", "example": "d647642e-09ac-4b34-8acc-ac30f57adc2c" }, "link": { "description": "Link to policy documentation.", "type": "string", "format": "uri", "nullable": true }, "name": { "description": "Policy name.", "type": "string", "example": "Google Workspace Standard Policy" }, "permissions": { "description": "List of permissions included in the policy.", "type": "array", "items": { "type": "string" }, "example": [ "https://www.googleapis.com/auth/admin.directory.domain.readonly", "https://www.googleapis.com/auth/admin.directory.user.readonly" ] } }, "example": { "compliance_level": "standard", "dlp_enabled": true, "id": "d647642e-09ac-4b34-8acc-ac30f57adc2c", "name": "Google Workspace Standard Policy" } }, "posture-api_IntegrationSummary": { "description": "Summary information about an integration.", "type": "object", "properties": { "created": { "description": "When entity was created.", "type": "string", "format": "date-time", "example": "2021-08-10T20:16:11.851451Z", "readOnly": true }, "credential_health_status": { "$ref": "#/components/schemas/posture-api_CredentialHealthStatusEnum" }, "credentials_expiry": { "description": "The date and time when the integration credentials will expire.", "type": "string", "format": "date-time", "example": "2025-03-18T17:25:38.697902Z", "nullable": true }, "id": { "description": "Integration ID.", "type": "string", "format": "uuid", "example": "c416bc38-75dc-425f-ae25-c37b5df5c37f" }, "is_paused": { "description": "Whether the given integration is paused by the user.", "type": "boolean", "example": false, "default": false }, "last_hydrated": { "description": "When were the integration credentials last updated.", "type": "string", "format": "date-time", "example": "2025-03-18T17:25:38.697894Z", "readOnly": true }, "name": { "description": "Name of the integration.", "type": "string", "example": "Example integration", "maxLength": 256 }, "permissions": { "description": "The vendor-specific permissions associated with the integration.", "type": "array", "items": { "type": "string" }, "example": [ "GroupMember.Read.All", "Group.Read.All" ], "readOnly": true }, "policy": { "$ref": "#/components/schemas/posture-api_IntegrationPolicy" }, "status": { "description": "Current status of the integration.", "type": "string", "example": "Healthy", "readOnly": true }, "updated": { "description": "Last entity was updated.", "type": "string", "format": "date-time", "example": "2021-08-10T20:16:11.851451Z", "readOnly": true }, "upgradable": { "description": "Whether the integrations permissions can be updated.", "type": "boolean", "example": false, "readOnly": true }, "upgrade_dismissed": { "description": "UI State as to whether a potential permissions upgrade has been dismissed.", "type": "boolean", "example": false, "default": false }, "vendor": { "$ref": "#/components/schemas/posture-api_Vendor" }, "zt_enrollments": { "description": "Zero Trust products associated with this integration.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_ZeroTrustProduct" }, "readOnly": true } }, "required": [ "created", "last_hydrated", "name", "permissions", "policy", "status", "updated", "upgradable", "vendor", "zt_enrollments" ] }, "posture-api_NullEnum": { "type": "string", "enum": [ null ], "nullable": true }, "posture-api_ObservationEnum": { "description": "The type of the observation.", "type": "string", "example": "Issue", "enum": [ "Issue", "Insight", "Activity" ] }, "posture-api_Order": { "description": "Generic ordering specification.", "type": "object", "properties": { "direction": { "$ref": "#/components/schemas/posture-api_DirectionEnum" }, "name": { "description": "Field name to order by.", "type": "string", "example": "instance_count" } }, "required": [ "direction", "name" ] }, "posture-api_PaginatedContentAssetList": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/posture-api_api-response-collection" }, { "properties": { "result": { "description": "Array of content asset objects.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_ContentAsset" } } }, "type": "object" } ] }, "posture-api_PaginatedExportJobList": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/posture-api_api-response-collection" }, { "properties": { "result": { "description": "Array of export job objects.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_ExportJob" } } }, "type": "object" } ] }, "posture-api_PaginatedRemediationJobList": { "description": "Paginated list of remediation jobs.", "type": "object", "properties": { "errors": { "description": "Array of error messages.", "type": "array", "items": { "type": "object" }, "example": [] }, "messages": { "description": "Array of informational messages.", "type": "array", "items": { "type": "object" }, "example": [] }, "result": { "description": "Array of remediation job objects.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_RemediationJob" } }, "result_info": { "type": "object", "properties": { "count": { "description": "Number of results on current page.", "type": "integer", "example": 2 }, "cursor": { "description": "Cursor for pagination.", "type": "string", "example": "next_cursor_value", "nullable": true }, "page": { "description": "Current page number.", "type": "integer", "example": 1 }, "per_page": { "description": "Number of results per page.", "type": "integer", "example": 10 }, "total_count": { "description": "Total number of results.", "type": "integer", "example": 2 } } }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages", "result_info", "result" ] }, "posture-api_PaginatedRemediationTypeList": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/posture-api_api-response-collection" }, { "properties": { "result": { "description": "Array of remediation type objects.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_RemediationType" } } }, "type": "object" } ] }, "posture-api_PolicyActionsInput": { "description": "Actions to execute when this policy is triggered, grouped by action type.\nA policy must contain at least one action across all groups and may include\nat most one remediation.", "type": "object", "properties": { "remediation_types": { "description": "Remediation actions to execute (at most one).", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_PolicyRemediationActionInput" }, "maxItems": 1 }, "webhook_configs": { "description": "Webhook actions to execute.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_PolicyWebhookActionInput" } } }, "minProperties": 1 }, "posture-api_PolicyActionsResponse": { "description": "The actions configured for this policy.", "type": "object", "properties": { "remediation_types": { "description": "List of remediation types that will be executed.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_PolicyRemediationTypeResponse" } }, "webhook_configs": { "description": "List of webhook configurations that will be triggered.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_PolicyWebhookConfigResponse" } } }, "required": [ "remediation_types", "webhook_configs" ] }, "posture-api_PolicyLogActionsResponse": { "description": "Actions dispatched by the policy consumer for this invocation. Both arrays are always present and may be empty.", "type": "object", "properties": { "remediations": { "description": "Remediation jobs spawned by this policy invocation.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_PolicyLogRemediationResponse" } }, "webhooks": { "description": "Webhook jobs dispatched by this policy invocation.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_PolicyLogWebhookResponse" } } }, "required": [ "remediations", "webhooks" ] }, "posture-api_PolicyLogPolicyResponse": { "description": "The policy configuration that fired.", "type": "object", "properties": { "name": { "description": "Display name of the policy at the time it ran.", "type": "string", "example": "Auto-remediate publicly shared files" }, "url": { "description": "URL to the policy configuration in the dashboard. Currently always an empty string; populated in a future revision once the upstream view exposes the policy configuration ID.", "type": "string", "example": "" } }, "required": [ "name", "url" ] }, "posture-api_PolicyLogRemediationResponse": { "description": "A remediation job dispatched during a policy invocation.", "type": "object", "properties": { "id": { "description": "Identifier of the remediation job, suitable for cross-referencing with the remediations API.", "type": "string", "example": "rj_001" }, "type": { "description": "Display name of the remediation type that ran.", "type": "string", "example": "Revoke External Sharing" }, "url": { "description": "Path to the remediation job in the dashboard.", "type": "string", "example": "/one/casb/remediations/rj_001" } }, "required": [ "type", "id", "url" ] }, "posture-api_PolicyLogResponse": { "description": "A single policy invocation log entry. Each entry represents one execution of a policy against a finding instance.", "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/posture-api_PolicyLogActionsResponse" }, "policy": { "$ref": "#/components/schemas/posture-api_PolicyLogPolicyResponse" }, "timestamp": { "description": "When the policy invocation was recorded by ClickHouse, in ClickHouse DateTime format (UTC).", "type": "string", "example": "2026-04-07T13:00:00Z" }, "trigger": { "$ref": "#/components/schemas/posture-api_PolicyLogTriggerResponse" } }, "required": [ "timestamp", "policy", "trigger", "actions" ] }, "posture-api_PolicyLogTriggerResponse": { "description": "The finding instance that caused the policy to fire.", "type": "object", "properties": { "date_detected": { "description": "When the finding was first detected, in ISO 8601 / RFC3339 format.", "type": "string", "example": "2026-04-07T13:00:00Z" }, "fields_of_interest": { "description": "Free-form JSON object containing finding-type-specific context fields (e.g. file owner, sharing scope). Schema varies per finding type; consumers should treat unknown keys defensively. Null when the upstream row had no fields_of_interest.", "type": "object", "example": { "owner": "alice@company.com", "sharing": "public" }, "additionalProperties": true, "nullable": true }, "finding_type_name": { "description": "Display name of the finding type that triggered the policy.", "type": "string", "example": "GW: File publicly accessible" }, "instance_asset": { "description": "Name of the specific resource (file, drive item, etc.) the finding was raised against.", "type": "string", "example": "Q4_Financials.pdf" }, "integration_name": { "description": "Display name of the CASB integration that produced the finding.", "type": "string", "example": "Finance GW" }, "integration_url": { "description": "Path to the integration in the dashboard.", "type": "string", "example": "/one/casb/integrations/int_001" } }, "required": [ "finding_type_name", "instance_asset", "date_detected", "integration_name", "integration_url", "fields_of_interest" ] }, "posture-api_PolicyLogWebhookResponse": { "description": "A webhook job dispatched during a policy invocation.", "type": "object", "properties": { "nickname": { "description": "User-set nickname of the webhook configuration that fired.", "type": "string", "example": "SOC alerting" }, "url": { "description": "Path to the webhook configuration in the dashboard.", "type": "string", "example": "/one/casb/webhooks/wh_001" } }, "required": [ "nickname", "url" ] }, "posture-api_PolicyRemediationActionInput": { "description": "A remediation action to be executed.", "type": "object", "properties": { "remediation_type_id": { "description": "The ID of the remediation type to execute.", "type": "string", "format": "uuid", "example": "5a7d9e2f-1b3c-4d5e-8f6a-7b8c9d0e1f2a" } }, "required": [ "remediation_type_id" ] }, "posture-api_PolicyRemediationTypeResponse": { "description": "A remediation type configured for the policy.", "type": "object", "properties": { "display_name": { "description": "Display name/label of the remediation type.", "type": "string", "example": "Remove Public Access", "readOnly": true }, "remediation_type": { "description": "The system name of the remediation type.", "type": "string", "example": "remove_public_access", "readOnly": true }, "remediation_type_id": { "description": "Unique identifier for the remediation type.", "type": "string", "format": "uuid", "example": "5a7d9e2f-1b3c-4d5e-8f6a-7b8c9d0e1f2a" } }, "required": [ "remediation_type_id", "remediation_type", "display_name" ] }, "posture-api_PolicyResponse": { "description": "Response body for a policy configuration.", "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/posture-api_PolicyActionsResponse" }, "applies_to_all_integrations": { "description": "When true, the policy applies to all integrations for the account. When false, it applies only to the specified integration_ids.", "type": "boolean", "example": false }, "created_at": { "description": "Timestamp when the policy was created.", "type": "string", "format": "date-time", "example": "2025-03-18T17:25:38.700541Z", "readOnly": true }, "description": { "description": "User-set description of what this policy does. Limited to 1000 characters.", "type": "string", "example": "Automatically remove public access from files when detected" }, "disabled_at": { "description": "Timestamp when the policy was disabled. Omitted from the response when the policy\nis enabled.", "type": "string", "format": "date-time", "example": "2025-03-18T17:25:38.700541Z", "readOnly": true }, "display_name": { "description": "Display name for the policy configuration. Limited to 255 characters.", "type": "string", "example": "Auto-remediate public files" }, "enabled": { "description": "Whether the policy is enabled. Derived from disabled_at (enabled when disabled_at is unset).", "type": "boolean", "example": true }, "finding_type_id": { "description": "The finding type this policy is associated with. Immutable after creation; changing it replaces the policy.", "type": "string", "format": "uuid", "example": "5a7d9e2f-1b3c-4d5e-8f6a-7b8c9d0e1f2a" }, "id": { "description": "Unique identifier for the policy configuration.", "type": "string", "format": "uuid", "example": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "readOnly": true }, "integration_ids": { "description": "The integrations this policy applies to.", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ] }, "last_triggered_at": { "description": "Timestamp of the most recent successful policy invocation. Omitted\nfrom the response when the policy has never been successfully\ntriggered. Only populated on GET responses; absent on responses from\ncreate/update endpoints.", "type": "string", "format": "date-time", "example": "2025-03-18T17:25:38.700541Z", "readOnly": true }, "updated_at": { "description": "Timestamp when the policy was last updated.", "type": "string", "format": "date-time", "example": "2025-03-18T17:25:38.700541Z", "readOnly": true } }, "required": [ "id", "created_at", "updated_at", "integration_ids", "applies_to_all_integrations", "finding_type_id", "display_name", "description", "enabled", "actions" ] }, "posture-api_PolicyWebhookActionInput": { "description": "A webhook action to be executed.", "type": "object", "properties": { "webhook_config_id": { "description": "The ID of the webhook configuration to use.", "type": "string", "format": "uuid", "example": "3f7b8c9d-6e5a-4f3b-9c2d-1e0a8b7c6d5e" } }, "required": [ "webhook_config_id" ] }, "posture-api_PolicyWebhookConfigResponse": { "description": "A webhook configuration associated with the policy.", "type": "object", "properties": { "display_name": { "description": "Display name/label of the webhook configuration.", "type": "string", "example": "Send to Slack", "readOnly": true }, "webhook_config_id": { "description": "Unique identifier for the webhook configuration.", "type": "string", "format": "uuid", "example": "3f7b8c9d-6e5a-4f3b-9c2d-1e0a8b7c6d5e" } }, "required": [ "webhook_config_id", "display_name" ] }, "posture-api_ProductEnum": { "description": "The product category.", "type": "string", "example": "SaaS", "enum": [ "SaaS", "Cloud" ] }, "posture-api_RemediationJob": { "description": "Information about a remediation job.", "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/posture-api_RemediationJobAsset" }, "created_at": { "description": "When the remediation job was created.", "type": "string", "format": "date-time", "example": "2025-07-07T18:39:13.123456Z" }, "finding_id": { "description": "Encoded finding ID.", "type": "string", "example": "MDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAxOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMgo=" }, "finding_instance_id": { "description": "ID of the finding instance being remediated.", "type": "string", "format": "uuid", "example": "3f7b8c9d-6e5a-4f3b-9c2d-1e0a8b7c6d5e" }, "finding_type_id": { "description": "ID of the finding type.", "type": "string", "format": "uuid", "example": "775c5f38-efcf-4b2b-93db-8428979eb6a2" }, "finding_type_name": { "description": "Name of the finding type.", "type": "string", "example": "Microsoft: File publicly accessible with edit access" }, "id": { "description": "Unique identifier for the remediation job.", "type": "string", "format": "uuid", "example": "c416bc38-75db-425f-ae25-c37b5df5c37f" }, "integration_name": { "description": "Name of the integration.", "type": "string", "example": "Microsoft" }, "last_updated": { "description": "When the remediation job was last updated.", "type": "string", "format": "date-time", "example": "2025-07-07T18:39:13.123456Z" }, "remediation_type": { "description": "Type of remediation being performed.", "type": "string", "example": "Remove publicly accessible edit url" }, "status": { "$ref": "#/components/schemas/posture-api_RemediationJobStatusEnum" }, "triggered_by_actor": { "description": "Type of actor that triggered the remediation job. Null on legacy rows created before this column was populated.", "type": "string", "example": "user", "enum": [ "user", "account_token", null ], "nullable": true }, "triggered_by_id": { "description": "ID of the actor that triggered the job. Meaning depends on triggered_by_actor. Null on legacy rows.", "type": "string", "example": "0123456789abcdef0123456789abcdef", "nullable": true }, "triggered_by_user": { "description": "Email of the user who triggered the remediation. For account-token actors this is the literal \"Account API Token\"; for policy actors this is empty.", "type": "string", "example": "user@example.com" } }, "required": [ "id", "status", "finding_instance_id", "finding_type_id", "finding_id", "finding_type_name", "remediation_type", "integration_name", "triggered_by_user", "created_at", "last_updated", "asset" ] }, "posture-api_RemediationJobActorTypeEnum": { "description": "Type of actor that triggered the remediation job.", "type": "string", "example": "user", "enum": [ "user", "account_token" ] }, "posture-api_RemediationJobAsset": { "description": "Asset information for a remediation job.", "type": "object", "properties": { "category": { "$ref": "#/components/schemas/posture-api_RemediationJobAssetCategory" }, "external_id": { "description": "External identifier from the source system.", "type": "string", "example": "c416bc38-75db-425f-ae25-c37b5df5c37f" }, "fields": { "description": "Additional fields associated with the asset.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_RemediationJobAssetField" } }, "id": { "description": "Unique identifier for the asset.", "type": "string", "format": "uuid", "example": "a1b2c3d4-5678-9abc-def0-123456789abc" }, "link": { "description": "Direct link to the asset.", "type": "string", "format": "uri", "example": "https://dashboard.microsoft.com/files/details", "nullable": true }, "name": { "description": "Human-readable name of the asset.", "type": "string", "example": "Microsoft File Publicly Accessible" } }, "required": [ "id", "external_id", "name", "fields", "category" ] }, "posture-api_RemediationJobAssetCategory": { "description": "Category information for a remediation job asset.", "type": "object", "properties": { "service": { "description": "Specific service within the vendor.", "type": "string", "example": "OneDrive" }, "type": { "description": "Asset type.", "type": "string", "example": "SaaS" }, "vendor": { "$ref": "#/components/schemas/posture-api_VendorsDisplayNameEnum" } }, "required": [ "type", "vendor", "service" ] }, "posture-api_RemediationJobAssetField": { "description": "Additional field information for a remediation job asset.", "type": "object", "properties": { "link": { "description": "Optional link associated with the field.", "type": "string", "format": "uri", "example": "https://dashboard.microsoft.com/files/details", "nullable": true }, "name": { "description": "Field name.", "type": "string", "example": "File Name" }, "value": { "description": "Field value (can be string, number, or boolean).", "type": "string", "example": "sensitive-document.xlsx", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "name", "value" ] }, "posture-api_RemediationJobFailure": { "description": "Information about a failed remediation job creation.", "type": "object", "properties": { "error": { "description": "Error message describing the failure.", "type": "string", "example": "Failed to create remediation job" }, "finding_instance_id": { "description": "ID of the finding instance that failed to create a remediation job.", "type": "string", "format": "uuid", "example": "2e6b4c8a-9d1f-4e3b-8c7a-5f9e2d1a6b4c" } }, "required": [ "finding_instance_id", "error" ] }, "posture-api_RemediationJobStatusEnum": { "description": "Status of a remediation job.", "type": "string", "example": "pending", "enum": [ "pending", "processing", "completed", "failed", "validating" ] }, "posture-api_RemediationJobSummary": { "description": "Summary information about a remediation job.", "type": "object", "properties": { "created_at": { "description": "When the remediation job was created.", "type": "string", "format": "date-time", "example": "2025-03-18T18:30:15.123456Z" }, "id": { "description": "Unique identifier for the remediation job.", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "stale": { "description": "Whether this remediation job is stale (created before the finding instance's affliction_date).", "type": "boolean", "example": false }, "status": { "$ref": "#/components/schemas/posture-api_RemediationJobStatusEnum" } }, "example": { "created_at": "2025-03-18T18:30:15.123456Z", "id": "123e4567-e89b-12d3-a456-426614174000", "stale": false, "status": "pending" }, "required": [ "id", "status", "created_at", "stale" ] }, "posture-api_RemediationJobsCreateRequest": { "description": "Request body for creating remediation jobs.", "type": "object", "properties": { "finding_instance_ids": { "description": "UUIDs identifying Finding Instances.", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "3f7b8c9d-6e5a-4f3b-9c2d-1e0a8b7c6d5e", "ab7b8c9d-6e5a-4f3b-9c2d-1e0a8b7c6d7g" ] }, "remediation_type_id": { "description": "A UUID identifying this Remediation Type.", "type": "string", "format": "uuid", "example": "5a7d9e2f-1b3c-4d5e-8f6a-7b8c9d0e1f2a" } }, "required": [ "finding_instance_ids", "remediation_type_id" ] }, "posture-api_RemediationJobsExportFilterRequest": { "description": "Filter specification for remediation jobs export.", "type": "object", "properties": { "integration_id": { "description": "Filter by multiple integration IDs.", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "55d7337e-1d0a-49fc-9826-925ba40df035" ] }, "max_updated_at": { "description": "Filter to view remediation jobs updated on or before this datetime. Can be a date-time in ISO 8601 format or an epoch timestamp.", "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z" }, "min_updated_at": { "description": "Filter to view remediation jobs updated on or after this datetime. Can be a date-time in ISO 8601 format or an epoch timestamp.", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "orders": { "description": "Ordering specifications for the export.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_RemediationJobsExportOrderFilterRequest" }, "default": [] }, "search": { "description": "A search term.", "type": "string", "example": "public access" }, "status": { "description": "Filter by remediation job status.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_RemediationJobStatusEnum" }, "example": [ "pending", "completed" ] } } }, "posture-api_RemediationJobsExportOrderFilterRequest": { "description": "Order specification for remediation jobs exports.", "type": "object", "properties": { "direction": { "$ref": "#/components/schemas/posture-api_DirectionEnum" }, "name": { "description": "Which field to use when ordering the remediation jobs.", "type": "string", "example": "last_updated_at", "enum": [ "asset_name", "finding_type_name", "integration_name", "status", "last_updated_at", "affliction_date" ] } }, "required": [ "direction", "name" ] }, "posture-api_RemediationType": { "description": "Information about a remediation type.", "type": "object", "properties": { "description": { "description": "A description of the action(s) taken by the remediation type.", "type": "string", "example": "Remove publicly accessible URL granting edit access" }, "display_name": { "description": "The name of the remediation type as displayed in the cloudflare dashboard.", "type": "string", "example": "Remove Publicly Accessible URL - Edit Access" }, "finding_type_id": { "description": "The identifier of the finding_type which this remediation type should remediate.", "type": "string", "format": "uuid", "example": "6a790513-bbb5-4933-8971-76a744ec5448" }, "id": { "description": "The identifier for the remediation type.", "type": "string", "format": "uuid", "example": "7d736ac5-ed3b-46d5-9375-7025175ba1d9" }, "remediation_type": { "description": "The name of the remediation type.", "type": "string", "example": "Microsoft: Remove Publicly Accessible URL - Edit Access" } }, "required": [ "id", "finding_type_id", "remediation_type", "display_name", "description" ] }, "posture-api_SeveritiesEnum": { "description": "The severity level for export filters.", "type": "string", "example": "HIGH", "enum": [ "CRITICAL", "HIGH", "MEDIUM", "LOW" ] }, "posture-api_SeverityEnum": { "description": "The severity level of a finding.", "type": "string", "example": "High", "enum": [ "Critical", "High", "Medium", "Low" ] }, "posture-api_StatusEnum": { "description": "Status of an export job.", "type": "string", "example": "Success", "enum": [ "Pending", "Success", "Failure", "Rescheduled", "In-Progress" ] }, "posture-api_TuneFindingSeverityRequest": { "description": "Request body for updating a finding's severity.", "type": "object", "properties": { "new_severity": { "description": "The numeric severity value to apply to the finding.", "type": "integer", "enum": [ 1, 2, 3, 4 ] } }, "required": [ "new_severity" ] }, "posture-api_UpdatePolicyRequest": { "description": "Request body for updating an existing policy configuration.", "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/posture-api_PolicyActionsInput" }, "applies_to_all_integrations": { "description": "When true, the policy applies to all integrations for the account. When false, integration_ids must be provided.", "type": "boolean", "example": false }, "description": { "description": "Optional description of what this policy does.", "type": "string", "example": "Automatically remove public access from files when detected", "maxLength": 1000, "x-stainless-terraform-configurability": "computed_optional" }, "display_name": { "description": "Display name for the policy configuration.", "type": "string", "example": "Auto-remediate public files", "maxLength": 255 }, "enabled": { "description": "Boolean specifying if the policy is enabled or disabled.", "type": "boolean", "example": true }, "integration_ids": { "description": "The integrations this policy applies to. Required when applies_to_all_integrations is false.", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "display_name", "enabled", "applies_to_all_integrations", "actions" ] }, "posture-api_UpdateWebhookRequest": { "description": "Request body for updating an existing webhook configuration.", "type": "object", "properties": { "authentication_type": { "description": "Type of authentication used for the webhook.", "type": "string", "example": "Bearer Auth", "enum": [ "Basic Auth", "None", "Bearer Auth", "Static Headers", "HMAC-Signing" ] }, "destination_url": { "description": "Target URL for the webhook configuration. Where resulting data will be sent.", "type": "string", "format": "uri", "example": "https://example.com/webhook" }, "headers": { "description": "List of custom headers to include in webhook requests.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_WebhookHeaderInput" }, "example": [ { "key": "Authorization", "value": "Bearer token123" }, { "key": "X-Custom-Header", "value": "value" } ] }, "label": { "description": "Account-specified display label for the webhook configuration.", "type": "string", "example": "Send to Slack" }, "signing_secret": { "description": "Secret key used for HMAC signing when authentication_type is \"HMAC-Signing\".", "type": "string", "example": "my-secret-key" }, "status": { "description": "Status of the webhook configuration.", "type": "string", "example": "enabled", "enum": [ "enabled", "disabled" ] } }, "required": [ "label", "destination_url", "authentication_type", "status" ] }, "posture-api_Vendor": { "description": "Information about a vendor/service provider.", "type": "object", "properties": { "description": { "description": "Detailed information about what kinds of issues are detected for this vendor.", "type": "string", "example": "Identify important security issues across your Google Workspace account ranging from shadow IT, misconfigurations, user access, and more.", "nullable": true }, "display_name": { "description": "The display name of the vendor.", "type": "string", "example": "Google Workspace" }, "id": { "description": "The id of the vendor.", "type": "string", "example": "R09PR0xFX1dPUktTUEFDRQ==" }, "logo": { "description": "Logo URL for the vendor.", "type": "string", "format": "uri", "example": "https://cdn.vectrix-infra.com/DetectionPack_Logos/GoogleWorkspace/g.png" }, "name": { "description": "The name of the vendor.", "type": "string", "example": "GOOGLE_WORKSPACE" }, "policies": { "description": "The policies related to the vendor.", "type": "array", "items": { "additionalProperties": true, "type": "object" }, "example": [] }, "static_logo": { "description": "Static logo URL for the vendor.", "type": "string", "format": "uri", "example": "https://onprem.cloudflare.come/DetectionPack_Logos/GoogleWorkspace/g.png" }, "zt_enrollments": { "description": "The vendor's compatible Zero Trust products.", "type": "array", "items": { "type": "string" }, "example": [ "casb" ] } }, "required": [ "description", "display_name", "id", "logo", "name", "static_logo", "zt_enrollments" ] }, "posture-api_VendorsDisplayNameEnum": { "description": "Display names for vendor types.", "type": "string", "example": "Google Workspace", "enum": [ "AWS", "Anthropic", "Bitbucket", "Box", "Confluence", "Dropbox", "GitHub", "Google Cloud Platform", "Google Workspace", "Jira", "Microsoft", "Microsoft Internal", "Okta", "OpenAI", "Slack", "Salesforce", "ServiceNow", "Workday", "Zoom" ] }, "posture-api_VendorsEnum": { "description": "Supported vendor types for integrations.", "type": "string", "example": "GOOGLE_WORKSPACE", "enum": [ "ANTHROPIC", "AWS", "BITBUCKET", "BOX", "CONFLUENCE", "DROPBOX", "GITHUB", "GOOGLE_CLOUD_PLATFORM", "GOOGLE_WORKSPACE", "JIRA", "MICROSOFT", "MICROSOFT_INTERNAL", "OPENAI", "SALESFORCE", "SERVICENOW", "SLACK" ] }, "posture-api_Webhook": { "description": "Webhook configuration for sending finding notifications.", "type": "object", "properties": { "authentication_type": { "description": "Type of authentication used for the webhook.", "type": "string", "example": "Bearer Auth", "enum": [ "Basic Auth", "None", "Bearer Auth", "Static Headers", "HMAC-Signing" ] }, "created_at": { "description": "Timestamp when the webhook configuration was created.", "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" }, "destination_url": { "description": "Target URL for the webhook configuration. Where resulting data will be sent.", "type": "string", "format": "uri", "example": "https://example.com/webhook" }, "headers": { "description": "List of header keys configured for this webhook. Values are not included for security reasons.", "type": "array", "items": { "properties": { "key": { "description": "Header key name (lowercase).", "type": "string", "example": "authorization" }, "value": { "description": "Header value. This field is never returned in API responses for security reasons.", "type": "string", "example": "my-authorization-value", "writeOnly": true } }, "type": "object" } }, "id": { "description": "Unique identifier for the specific webhook configuration.", "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "label": { "description": "Account-specified display label for the webhook configuration.", "type": "string", "example": "Send to Gmail" }, "status": { "description": "Current status of the webhook configuration. If disabled, data cannot be sent through this configuration.", "type": "string", "example": "enabled", "enum": [ "enabled", "disabled" ] }, "updated_at": { "description": "Timestamp when the webhook configuration was last updated.", "type": "string", "format": "date-time", "example": "2024-01-20T14:45:00Z" }, "version": { "description": "Version number of the configuration.", "type": "integer", "format": "uint32", "example": 1 } }, "required": [ "id", "label", "destination_url", "status", "authentication_type", "created_at", "updated_at", "version" ] }, "posture-api_WebhookHeaderInput": { "description": "A header to include in webhook requests. On Create/Evaluate, both key and value are required. On Update, omitting value means \"keep existing value\".", "type": "object", "properties": { "key": { "description": "Header key name.", "type": "string", "example": "Authorization", "maxLength": 255 }, "value": { "description": "Header value. Required on Create and Evaluate. On Update, omit or set to null to keep existing value.", "type": "string", "example": "Bearer token123", "maxLength": 4096, "nullable": true } }, "required": [ "key" ] }, "posture-api_WebhookInvocationSummary": { "description": "Summary of the most recent webhook job invocation for a specific webhook configuration.", "type": "object", "properties": { "latest_job": { "description": "The most recent webhook job for this webhook configuration.", "type": "object", "properties": { "created_at": { "description": "When the webhook job was created.", "type": "string", "format": "date-time", "example": "2025-03-18T18:30:15.123456Z" }, "id": { "description": "Unique identifier for the webhook job.", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "stale": { "description": "Whether this webhook job is stale (created before the finding instance's current affliction_date).", "type": "boolean", "example": false }, "status": { "description": "Current status of the webhook job.", "type": "string", "example": "pending", "enum": [ "pending", "processing", "completed" ] } }, "required": [ "id", "status", "created_at", "stale" ] }, "webhook_id": { "description": "Unique identifier for the webhook configuration.", "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "webhook_label": { "description": "Account-specified display label for the webhook configuration.", "type": "string", "example": "Send to Gmail" } }, "required": [ "webhook_id", "webhook_label", "latest_job" ] }, "posture-api_WebhookJob": { "description": "Information about a webhook job.", "type": "object", "properties": { "asset_data": { "description": "Asset data associated with this webhook job.", "type": "object", "additionalProperties": true }, "created_at": { "description": "When the webhook job was created.", "type": "string", "format": "date-time", "example": "2025-07-07T18:39:13.123456Z" }, "failure_details": { "description": "Additional details about the failure.", "type": "object", "additionalProperties": true }, "failure_reason": { "$ref": "#/components/schemas/posture-api_WebhookJobFailureReasonEnum" }, "id": { "description": "Unique identifier for the webhook job.", "type": "string", "format": "uuid", "example": "c416bc38-75db-425f-ae25-c37b5df5c37f" }, "integration_id": { "description": "ID of the integration.", "type": "string", "format": "uuid", "example": "9f8e7d6c-5b4a-3210-fedc-ba0987654321" }, "last_updated_at": { "description": "When the webhook job was last updated.", "type": "string", "format": "date-time", "example": "2025-07-07T18:39:13.123456Z" }, "parameters": { "$ref": "#/components/schemas/posture-api_WebhookJobParameters" }, "status": { "$ref": "#/components/schemas/posture-api_WebhookJobStatusEnum" }, "triggered_by_actor": { "$ref": "#/components/schemas/posture-api_WebhookJobActorTypeEnum" }, "triggered_by_id": { "description": "ID of the actor that triggered the job.", "type": "string", "example": "user@example.com" }, "webhook_id": { "description": "ID of the webhook configuration.", "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "required": [ "id", "webhook_id", "integration_id", "asset_data", "parameters", "status", "triggered_by_actor", "triggered_by_id", "created_at", "last_updated_at" ] }, "posture-api_WebhookJobActorTypeEnum": { "description": "Type of actor that triggered the webhook job.", "type": "string", "enum": [ "user", "account_token" ] }, "posture-api_WebhookJobFailure": { "description": "Information about a failed webhook job creation.", "type": "object", "properties": { "error": { "description": "Error message describing the failure.", "type": "string", "example": "Failed to create webhook job" }, "finding_instance_id": { "description": "ID of the finding instance that failed to create a webhook job.", "type": "string", "format": "uuid", "example": "2e6b4c8a-9d1f-4e3b-8c7a-5f9e2d1a6b4c" }, "webhook_id": { "description": "ID of the webhook configuration.", "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } }, "required": [ "webhook_id", "finding_instance_id", "error" ] }, "posture-api_WebhookJobFailureReasonEnum": { "description": "Reason for webhook job failure.", "type": "string", "enum": [ "Permission Denied", "Integration Unavailable", "Service Temporarily Unavailable", "System Error" ] }, "posture-api_WebhookJobParameters": { "description": "Parameters for a webhook job.", "type": "object", "properties": { "finding_instance_id": { "description": "ID of the finding instance.", "type": "string", "format": "uuid", "example": "3f7b8c9d-6e5a-4f3b-9c2d-1e0a8b7c6d5e" } }, "required": [ "finding_instance_id" ] }, "posture-api_WebhookJobStatusEnum": { "description": "Status of a webhook job.", "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "posture-api_ZeroTrustProduct": { "description": "Information about a Zero Trust product integration.", "type": "object", "properties": { "description": { "description": "Brief description of the Zero Trust Product.", "type": "string", "example": "example" }, "display_name": { "description": "The verbose name of the Zero Trust Product.", "type": "string", "example": "Cloud Access Security Broker" }, "enabled": { "description": "Flag to enable/disable access to the listed integration from the corresponding Cloudflare product.", "type": "boolean", "example": true, "default": false }, "id": { "description": "The internal identifier of the Zero Trust Product.", "type": "string", "example": "casb" } }, "example": { "description": "example", "display_name": "Cloud Access Security Broker", "enabled": true, "id": "casb" } }, "posture-api_api-response-collection": { "description": "Response structure for paginated collections.", "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/posture-api_messages" }, "messages": { "$ref": "#/components/schemas/posture-api_messages" }, "result_info": { "$ref": "#/components/schemas/posture-api_result-info" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages", "result_info" ] }, "posture-api_api-response-common": { "description": "Common response structure for all API endpoints.", "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/posture-api_messages" }, "messages": { "$ref": "#/components/schemas/posture-api_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages" ] }, "posture-api_error-response": { "description": "Standard error response structure.", "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/posture-api_messages" }, "messages": { "$ref": "#/components/schemas/posture-api_messages" }, "success": { "description": "Indicates the request failed.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages" ] }, "posture-api_export-job-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/posture-api_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/posture-api_ExportJob" } }, "type": "object" } ] }, "posture-api_finding-instance-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/posture-api_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/posture-api_FindingInstance" } }, "type": "object" } ] }, "posture-api_finding-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/posture-api_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/posture-api_Finding" } }, "type": "object" } ] }, "posture-api_finding-type-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/posture-api_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/posture-api_BaseFindingType" } }, "type": "object" } ] }, "posture-api_messages": { "type": "array", "items": { "properties": { "code": { "description": "Error or message code.", "type": "integer", "example": 1000, "minimum": 1000 }, "documentation_url": { "description": "Link to relevant documentation.", "type": "string", "format": "uri", "example": "https://developers.cloudflare.com/api/operations/list-findings" }, "message": { "description": "Human-readable message.", "type": "string", "example": "Request processed successfully" }, "source": { "type": "object", "properties": { "pointer": { "description": "JSON pointer to the source of the error.", "type": "string", "example": "/data/attributes/name" } } } }, "required": [ "code", "message" ], "type": "object" }, "example": [], "uniqueItems": true }, "posture-api_paginated-finding-instance-list": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/posture-api_api-response-collection" }, { "properties": { "result": { "description": "Array of finding instance objects.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_FindingInstance" } } }, "type": "object" } ] }, "posture-api_paginated-finding-list": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/posture-api_api-response-collection" }, { "properties": { "result": { "description": "Array of finding objects.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_Finding" } } }, "type": "object" } ] }, "posture-api_paginated-finding-type-list": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/posture-api_api-response-collection" }, { "properties": { "result": { "description": "Array of finding type objects.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_BaseFindingType" } } }, "type": "object" } ] }, "posture-api_result-info": { "description": "Pagination and result information.", "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "integer", "example": 1 }, "cursor": { "description": "Cursor for cursor-based pagination.", "type": "string", "example": "eyJpZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsImFmZmxpY3Rpb25fZGF0ZSI6IjE5NzAtMDEtMDFUMDA6MDA6MDAuMDAwMDAwWiJ9", "nullable": true }, "next": { "description": "URL to the next page of results.", "type": "string", "format": "uri", "nullable": true }, "page": { "description": "Current page within paginated list of results.", "type": "integer", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "integer", "example": 20 }, "previous": { "description": "URL to the previous page of results.", "type": "string", "format": "uri", "nullable": true }, "total_count": { "description": "Total results available without any search parameters.", "type": "integer", "example": 2000 } } }, "posture-api_webhook-list-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/posture-api_api-response-common" }, { "properties": { "result": { "description": "List of webhook configurations.", "type": "array", "items": { "$ref": "#/components/schemas/posture-api_Webhook" } } }, "type": "object" } ] }, "posture-api_webhook-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/posture-api_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/posture-api_Webhook" } }, "type": "object" } ] }, "precursor_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/precursor_messages" }, "messages": { "$ref": "#/components/schemas/precursor_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "precursor_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/precursor_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/precursor_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "precursor_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/precursor_api-response-common" } ] }, "precursor_default_mode": { "description": "The zone-level Precursor enforcement mode applied to requests that do\nnot match a more specific enforcement rule.\n", "type": "string", "example": "off", "default": "off", "deprecated": true, "enum": [ "off", "min-friction", "max-security" ], "x-auditable": true }, "precursor_enforcement_rule": { "type": "object", "properties": { "description": { "description": "An informative description of the rule.", "type": "string", "example": "Ease friction on the login path", "default": "", "x-auditable": true }, "enabled": { "description": "Whether the rule is active.", "type": "boolean", "example": true, "default": true, "x-auditable": true }, "expression": { "description": "The filter expression that determines which requests the rule matches.", "type": "string", "example": "http.request.uri.path eq \"/login\"", "maxLength": 4000, "x-auditable": true }, "id": { "description": "The read-only identifier that Cloudflare assigns to the rule.", "type": "string", "example": "3a03d665bac043e3a684e0d385a4b1e2", "readOnly": true, "x-auditable": true }, "mode": { "$ref": "#/components/schemas/precursor_enforcement_rule_mode" } }, "required": [ "expression", "mode" ], "title": "Enforcement Rule" }, "precursor_enforcement_rule_mode": { "description": "The override mode Precursor applies to requests matching an enforcement\nrule. Unlike `default_mode`, this cannot be `off`.\n", "type": "string", "example": "max-security", "enum": [ "min-friction", "max-security" ], "x-auditable": true }, "precursor_enforcement_rules": { "description": "The ordered list of enforcement rules for the zone.", "type": "array", "items": { "$ref": "#/components/schemas/precursor_enforcement_rule" }, "deprecated": true }, "precursor_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "precursor_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "precursor_precursor_config": { "type": "object", "properties": { "default_mode": { "$ref": "#/components/schemas/precursor_default_mode" }, "enforcement_rules": { "$ref": "#/components/schemas/precursor_enforcement_rules" } }, "example": { "default_mode": "min-friction", "enforcement_rules": [ { "description": "Enforce max-security on the shop page", "enabled": true, "expression": "http.request.uri.path eq \"/shop\"", "mode": "max-security" } ] }, "minProperties": 1, "title": "Precursor Config" }, "precursor_precursor_config_response_body": { "allOf": [ { "$ref": "#/components/schemas/precursor_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/precursor_precursor_config" } }, "type": "object" } ] }, "public-ip_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/public-ip_messages" }, "messages": { "$ref": "#/components/schemas/public-ip_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "public-ip_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/public-ip_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/public-ip_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "public-ip_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/public-ip_api-response-common" } ] }, "public-ip_etag": { "description": "A digest of the IP data. Useful for determining if the data has changed.", "type": "string", "example": "a8e453d9d129a3769407127936edfdb0" }, "public-ip_ips": { "type": "object", "properties": { "etag": { "$ref": "#/components/schemas/public-ip_etag" }, "ipv4_cidrs": { "$ref": "#/components/schemas/public-ip_ipv4_cidrs" }, "ipv6_cidrs": { "$ref": "#/components/schemas/public-ip_ipv6_cidrs" } } }, "public-ip_ips_jdcloud": { "type": "object", "properties": { "etag": { "$ref": "#/components/schemas/public-ip_etag" }, "ipv4_cidrs": { "$ref": "#/components/schemas/public-ip_ipv4_cidrs" }, "ipv6_cidrs": { "$ref": "#/components/schemas/public-ip_ipv6_cidrs" }, "jdcloud_cidrs": { "$ref": "#/components/schemas/public-ip_jdcloud_cidrs" } } }, "public-ip_ipv4_cidrs": { "description": "List of Cloudflare IPv4 CIDR addresses.", "type": "array", "items": { "description": "IPv4 CIDR.", "example": "199.27.128.0/21", "type": "string" } }, "public-ip_ipv6_cidrs": { "description": "List of Cloudflare IPv6 CIDR addresses.", "type": "array", "items": { "description": "IPv6 CIDR.", "example": "2400:cb00::/32", "type": "string" } }, "public-ip_jdcloud_cidrs": { "description": "List IPv4 and IPv6 CIDRs, only populated if `?networks=jdcloud` is used.", "type": "array", "items": { "description": "IPv4 or IPv6 CIDR.", "example": "199.27.128.0/21", "type": "string" } }, "public-ip_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "r2-data-catalog_account-id": { "description": "Use this to identify the account.", "type": "string", "example": "0123456789abcdef0123456789abcdef", "pattern": "^[a-fA-F0-9]{32}$" }, "r2-data-catalog_api-response-common-failure": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "type": "object" }, "minItems": 1 }, "messages": { "type": "array", "items": { "type": "object" } }, "success": { "type": "boolean", "enum": [ false ] } } }, "r2-data-catalog_api-response-errors": { "description": "Contains errors if the API call was unsuccessful.", "type": "array", "items": { "properties": { "code": { "description": "Specifies the error code.", "type": "integer" }, "message": { "description": "Describes the error.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "r2-data-catalog_api-response-messages": { "description": "Contains informational messages.", "type": "array", "items": { "properties": { "code": { "description": "Specifies the message code.", "type": "integer" }, "message": { "description": "Contains the message text.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "r2-data-catalog_api-response-single": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/r2-data-catalog_api-response-errors" }, "messages": { "$ref": "#/components/schemas/r2-data-catalog_api-response-messages" }, "success": { "$ref": "#/components/schemas/r2-data-catalog_api-response-success" } }, "required": [ "success", "errors", "messages" ] }, "r2-data-catalog_api-response-success": { "description": "Indicates whether the API call was successful.", "type": "boolean", "example": true }, "r2-data-catalog_bucket-name": { "description": "Specifies the R2 bucket name.", "type": "string", "example": "my-data-bucket", "maxLength": 63, "minLength": 3, "pattern": "^[a-z0-9]([a-z0-9\\-]*[a-z0-9])?$" }, "r2-data-catalog_catalog": { "description": "Contains R2 Data Catalog information.", "type": "object", "properties": { "bucket": { "description": "Specifies the associated R2 bucket name.", "type": "string", "example": "my-data-bucket" }, "credential_status": { "description": "Shows the credential configuration status.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_credential-status" } ], "nullable": true }, "id": { "description": "Use this to uniquely identify the catalog.", "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "maintenance_config": { "description": "Configures maintenance for the catalog.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_catalog-maintenance-config" } ], "nullable": true }, "name": { "description": "Specifies the catalog name (generated from account and bucket name).", "type": "string", "example": "account123_my-bucket" }, "status": { "$ref": "#/components/schemas/r2-data-catalog_catalog-status" } }, "required": [ "id", "name", "bucket", "status" ] }, "r2-data-catalog_catalog-activation-response": { "description": "Contains response from activating an R2 bucket as a catalog.", "type": "object", "properties": { "id": { "description": "Use this to uniquely identify the activated catalog.", "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "description": "Specifies the name of the activated catalog.", "type": "string", "example": "account123_my-bucket" } }, "required": [ "id", "name" ] }, "r2-data-catalog_catalog-compaction-config": { "description": "Configures compaction for catalog maintenance.", "type": "object", "properties": { "state": { "$ref": "#/components/schemas/r2-data-catalog_catalog-maintenance-state" }, "target_size_mb": { "$ref": "#/components/schemas/r2-data-catalog_catalog-target-file-size" } }, "required": [ "state", "target_size_mb" ] }, "r2-data-catalog_catalog-credential-request": { "description": "Contains request to store catalog credentials.", "type": "object", "properties": { "token": { "description": "Provides the Cloudflare API token for accessing R2.", "type": "string", "example": "your-cloudflare-api-token-here" } }, "required": [ "token" ] }, "r2-data-catalog_catalog-list": { "description": "Contains the list of catalogs.", "type": "object", "properties": { "warehouses": { "description": "Lists catalogs in the account.", "type": "array", "items": { "$ref": "#/components/schemas/r2-data-catalog_catalog" } } }, "required": [ "warehouses" ] }, "r2-data-catalog_catalog-maintenance-config": { "description": "Configures maintenance for the catalog.", "type": "object", "properties": { "compaction": { "$ref": "#/components/schemas/r2-data-catalog_catalog-compaction-config" }, "interval": { "$ref": "#/components/schemas/r2-data-catalog_maintenance-interval" }, "snapshot_expiration": { "$ref": "#/components/schemas/r2-data-catalog_snapshot-expiration-config" } } }, "r2-data-catalog_catalog-maintenance-config-response": { "description": "Contains maintenance configuration and credential status.", "type": "object", "properties": { "credential_status": { "$ref": "#/components/schemas/r2-data-catalog_credential-status" }, "maintenance_config": { "$ref": "#/components/schemas/r2-data-catalog_catalog-maintenance-config" } }, "required": [ "maintenance_config", "credential_status" ] }, "r2-data-catalog_catalog-maintenance-state": { "description": "Specifies the state of maintenance operations.", "type": "string", "example": "enabled", "enum": [ "enabled", "disabled" ] }, "r2-data-catalog_catalog-maintenance-update-request": { "description": "Contains request to update catalog maintenance configuration.", "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_maintenance-update-params" } ] }, "r2-data-catalog_catalog-status": { "description": "Indicates the status of the catalog.", "type": "string", "example": "active", "enum": [ "active", "inactive" ] }, "r2-data-catalog_catalog-target-file-size": { "description": "Sets the target file size for compaction in megabytes. Defaults to \"128\".", "type": "string", "example": "128", "enum": [ "64", "128", "256", "512" ] }, "r2-data-catalog_compaction-update-params": { "description": "Updates compaction configuration (all fields optional).", "type": "object", "properties": { "state": { "description": "Updates the state optionally.", "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_catalog-maintenance-state" } ] }, "target_size_mb": { "description": "Updates the target file size optionally.", "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_catalog-target-file-size" } ] } } }, "r2-data-catalog_credential-status": { "description": "Shows the credential configuration status.", "type": "string", "example": "present", "enum": [ "present", "absent" ] }, "r2-data-catalog_get-table-response": { "description": "Single-table detail response wrapping standard Iceberg `TableMetadata`\nwith snapshot-pruning counters.\n", "type": "object", "properties": { "identifier": { "$ref": "#/components/schemas/r2-data-catalog_table-identifier" }, "metadata": { "$ref": "#/components/schemas/r2-data-catalog_table-metadata" }, "metadata_location": { "description": "Specifies the S3-compatible URI to the current Iceberg metadata file\nin R2. Omitted for staged tables that have not yet been committed.\n", "type": "string", "example": "s3://my-bucket/__r2_data_catalog/wh-id/table-id/metadata/00001-abc.metadata.json" }, "returned_snapshots": { "description": "Describes the number of snapshots that appear in `metadata.snapshots`. Caps the\nlist at 10 (the most recent by `timestamp-ms`), but if the current\nsnapshot falls outside the recent window, the result includes it in the\nset, leading to a possible total of 11.\n", "type": "integer", "example": 10, "minimum": 0 }, "table_uuid": { "description": "Contains the Iceberg table UUID, stable across renames.", "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "total_snapshots": { "description": "Indicates the total number of snapshots stored for the table, before pruning.", "type": "integer", "example": 122113, "minimum": 0 } }, "required": [ "identifier", "table_uuid", "total_snapshots", "returned_snapshots", "metadata" ] }, "r2-data-catalog_maintenance-interval": { "description": "Scheduling interval between normal table maintenance runs.", "type": "string", "example": "1h", "pattern": "^\\d+(d|h|m|s)$" }, "r2-data-catalog_maintenance-run-operation": { "type": "object", "properties": { "duration_ms": { "type": "integer", "format": "int64" }, "error_code": { "type": "integer", "format": "int32", "nullable": true }, "metrics": { "type": "object", "additionalProperties": true, "nullable": true }, "operation": { "type": "string", "enum": [ "rewrite_manifests", "compaction", "snapshot_expiration" ] }, "status": { "type": "string", "enum": [ "succeeded", "failed", "skipped", "not_run" ] } }, "required": [ "operation", "status", "duration_ms" ] }, "r2-data-catalog_maintenance-run-record": { "type": "object", "properties": { "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "configuration_type": { "type": "string", "enum": [ "compaction", "snapshot_expiration" ] }, "customer_message": { "type": "string", "nullable": true }, "duration_ms": { "type": "integer", "format": "int64", "nullable": true }, "operation_results": { "type": "array", "items": { "$ref": "#/components/schemas/r2-data-catalog_maintenance-run-operation" } }, "outcome": { "type": "string", "nullable": true }, "primary_error_code": { "type": "integer", "format": "int32", "nullable": true }, "run_id": { "type": "integer", "format": "int64" }, "started_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "running", "succeeded", "failed", "interrupted", "timed_out", "cancelled" ] } }, "required": [ "run_id", "configuration_type", "status", "started_at", "operation_results" ] }, "r2-data-catalog_maintenance-runs-response": { "type": "object", "properties": { "next_page_token": { "type": "string", "nullable": true }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/r2-data-catalog_maintenance-run-record" } } }, "required": [ "runs", "next_page_token" ] }, "r2-data-catalog_maintenance-update-params": { "description": "Contains maintenance update parameters.", "type": "object", "properties": { "compaction": { "$ref": "#/components/schemas/r2-data-catalog_compaction-update-params" }, "snapshot_expiration": { "$ref": "#/components/schemas/r2-data-catalog_snapshot-expiration-update-params" } } }, "r2-data-catalog_namespace-details": { "description": "Contains namespace with metadata details.", "type": "object", "properties": { "created_at": { "description": "Indicates the creation timestamp in ISO 8601 format.", "type": "string", "format": "date-time", "nullable": true }, "namespace": { "$ref": "#/components/schemas/r2-data-catalog_namespace-identifier" }, "namespace_uuid": { "description": "Contains the UUID that persists across renames.", "type": "string", "format": "uuid" }, "updated_at": { "description": "Shows the last update timestamp in ISO 8601 format. Null if never updated.", "type": "string", "format": "date-time", "nullable": true } }, "required": [ "namespace", "namespace_uuid" ] }, "r2-data-catalog_namespace-identifier": { "description": "Specifies the hierarchical namespace parts as an array of strings.\nFor example, [\"bronze\", \"analytics\"] represents the namespace \"bronze.analytics\".\n", "type": "array", "items": { "type": "string" }, "example": [ "bronze", "analytics" ], "maxItems": 16, "minItems": 1 }, "r2-data-catalog_namespace-list-response": { "description": "Contains the list of namespaces with optional pagination.", "type": "object", "properties": { "details": { "description": "Contains detailed metadata for each namespace when return_details is true.\nEach object includes the namespace, UUID, and timestamps.\n", "type": "array", "items": { "$ref": "#/components/schemas/r2-data-catalog_namespace-details" }, "nullable": true }, "namespace_uuids": { "description": "Contains UUIDs for each namespace when return_uuids is true.\nThe order corresponds to the namespaces array.\n", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "0199b999-6869-7383-bb1f-d30e059d5326", "0199b99b-2c88-73b3-8dbb-421e0e8f2757" ], "nullable": true }, "namespaces": { "description": "Lists namespaces in the catalog.", "type": "array", "items": { "$ref": "#/components/schemas/r2-data-catalog_namespace-identifier" } }, "next_page_token": { "description": "Use this opaque token to fetch the next page of results.\nA null or absent value indicates the last page.\n", "type": "string", "example": "MSYxNzU5NzU1NTc4NTA0MTk0JjAxOTliOTliLTJjODgtNzNiMy04ZGJiLTQyMWUwZThmMjc1Nw", "nullable": true } }, "required": [ "namespaces" ] }, "r2-data-catalog_queue-maintenance-request": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "nullable": true } } }, "r2-data-catalog_queue-maintenance-response": { "type": "object", "properties": { "message": { "type": "string" }, "queued": { "type": "boolean" }, "request_id": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "queued", "message" ] }, "r2-data-catalog_snapshot-expiration-config": { "description": "Configures snapshot expiration settings.", "type": "object", "properties": { "max_snapshot_age": { "description": "Specifies the maximum age for snapshots. The system deletes snapshots older than this age.\nFormat: where unit is d (days), h (hours), m (minutes), or s (seconds).\nExamples: \"7d\" (7 days), \"48h\" (48 hours), \"2880m\" (2,880 minutes).\nDefaults to \"7d\".\n", "type": "string", "example": "7d", "pattern": "^\\d+(d|h|m|s)$" }, "min_snapshots_to_keep": { "description": "Specifies the minimum number of snapshots to retain. Defaults to 100.", "type": "integer", "format": "int64", "example": 100, "minimum": 1 }, "state": { "$ref": "#/components/schemas/r2-data-catalog_catalog-maintenance-state" } }, "required": [ "state", "min_snapshots_to_keep", "max_snapshot_age" ] }, "r2-data-catalog_snapshot-expiration-update-params": { "description": "Updates snapshot expiration configuration (all fields optional).", "type": "object", "properties": { "max_snapshot_age": { "description": "Updates the maximum age for snapshots optionally.", "type": "string", "pattern": "^\\d+(d|h|m|s)$" }, "min_snapshots_to_keep": { "description": "Updates the minimum number of snapshots to retain optionally.", "type": "integer", "format": "int64", "minimum": 1 }, "state": { "description": "Updates the state optionally.", "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_catalog-maintenance-state" } ] } } }, "r2-data-catalog_table-compaction-config": { "description": "Configures compaction settings for table optimization.", "type": "object", "properties": { "next_eligible_at": { "description": "Earliest time when the scheduler can claim this operation. Null when disabled.", "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "state": { "$ref": "#/components/schemas/r2-data-catalog_catalog-maintenance-state" }, "target_size_mb": { "$ref": "#/components/schemas/r2-data-catalog_catalog-target-file-size" } }, "required": [ "state", "target_size_mb" ] }, "r2-data-catalog_table-compaction-update-params": { "description": "Updates table compaction configuration; all fields are optional.", "type": "object", "properties": { "state": { "$ref": "#/components/schemas/r2-data-catalog_catalog-maintenance-state" }, "target_size_mb": { "$ref": "#/components/schemas/r2-data-catalog_catalog-target-file-size" } } }, "r2-data-catalog_table-details": { "description": "Contains table with metadata.", "type": "object", "properties": { "created_at": { "description": "Indicates the creation timestamp in ISO 8601 format.", "type": "string", "format": "date-time", "nullable": true }, "identifier": { "$ref": "#/components/schemas/r2-data-catalog_table-identifier" }, "location": { "description": "Specifies the base S3 URI for table storage location.", "type": "string", "nullable": true }, "metadata_location": { "description": "Contains the S3 URI to table metadata file. Null for staged tables.", "type": "string", "nullable": true }, "table_uuid": { "description": "Contains the UUID that persists across renames.", "type": "string", "format": "uuid" }, "updated_at": { "description": "Shows the last update timestamp in ISO 8601 format. Null if never updated.", "type": "string", "format": "date-time", "nullable": true } }, "required": [ "identifier", "table_uuid" ] }, "r2-data-catalog_table-identifier": { "description": "Specifies a unique table identifier within a catalog.", "type": "object", "properties": { "name": { "description": "Specifies the table name.", "type": "string", "example": "events" }, "namespace": { "$ref": "#/components/schemas/r2-data-catalog_namespace-identifier" } }, "required": [ "namespace", "name" ] }, "r2-data-catalog_table-list-response": { "description": "Contains the list of tables with optional pagination.", "type": "object", "properties": { "details": { "description": "Contains detailed metadata for each table when return_details is true.\nEach object includes identifier, UUID, timestamps, and locations.\n", "type": "array", "items": { "$ref": "#/components/schemas/r2-data-catalog_table-details" }, "nullable": true }, "identifiers": { "description": "Lists tables in the namespace.", "type": "array", "items": { "$ref": "#/components/schemas/r2-data-catalog_table-identifier" } }, "next_page_token": { "description": "Use this opaque token to fetch the next page of results.\nA null or absent value indicates the last page.\n", "type": "string", "example": "MSYxNzU5NzU2MTI4NTU2Njk2JjAxOTliOWEzLTkxMmUtN2ZhMS05YzllLTg5MTAxMGQzYTg0MQ", "nullable": true }, "table_uuids": { "description": "Contains UUIDs for each table when return_uuids is true.\nThe order corresponds to the identifiers array.\n", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "0199b9a1-28a0-71e0-a73e-b0fc32c8468e", "0199b9a1-3c74-7731-bf53-d8c67ead079d" ], "nullable": true } }, "required": [ "identifiers" ] }, "r2-data-catalog_table-maintenance-config": { "description": "Configures maintenance for the table.", "type": "object", "properties": { "compaction": { "$ref": "#/components/schemas/r2-data-catalog_table-compaction-config" }, "interval": { "allOf": [ { "$ref": "#/components/schemas/r2-data-catalog_maintenance-interval" } ], "readOnly": true }, "snapshot_expiration": { "$ref": "#/components/schemas/r2-data-catalog_table-snapshot-expiration-config" } } }, "r2-data-catalog_table-maintenance-config-response": { "description": "Contains table maintenance configuration.", "type": "object", "properties": { "maintenance_config": { "$ref": "#/components/schemas/r2-data-catalog_table-maintenance-config" } }, "required": [ "maintenance_config" ] }, "r2-data-catalog_table-maintenance-update-request": { "description": "Contains request to update table maintenance configuration.", "type": "object", "properties": { "compaction": { "$ref": "#/components/schemas/r2-data-catalog_table-compaction-update-params" }, "snapshot_expiration": { "$ref": "#/components/schemas/r2-data-catalog_snapshot-expiration-update-params" } } }, "r2-data-catalog_table-metadata": { "description": "Contains standard Apache Iceberg table metadata (format version 1 or 2).\nSee https://iceberg.apache.org/spec/#table-metadata-fields for the full\nfield reference. Uses the `s3://` URI scheme for S3 compatibility,\nregardless of the underlying R2 backend.\n\nLimits the `snapshots`, `snapshot-log`, and `metadata-log` arrays to the\nmost recent 10 entries (by `timestamp-ms`). Always keeps the current\nsnapshot (via `current-snapshot-id`) even when it falls outside that\nwindow.\n", "type": "object", "example": { "current-schema-id": 1, "current-snapshot-id": 3055729675574597000, "default-sort-order-id": 0, "default-spec-id": 0, "format-version": 2, "last-column-id": 3, "last-sequence-number": 34, "last-updated-ms": 1602638573590, "location": "s3://my-bucket/__r2_data_catalog/wh-id/table-id", "metadata-log": [], "partition-specs": [ { "fields": [ { "field-id": 1000, "name": "user_id_bucket", "source-id": 1, "transform": "bucket[16]" } ], "spec-id": 0 } ], "properties": { "write.parquet.compression-codec": "zstd" }, "refs": { "main": { "snapshot-id": 3055729675574597000, "type": "branch" } }, "schemas": [ { "fields": [ { "id": 1, "name": "user_id", "required": true, "type": "long" }, { "id": 2, "name": "email", "required": true, "type": "string" } ], "identifier-field-ids": [ 1 ], "schema-id": 1, "type": "struct" } ], "snapshot-log": [ { "snapshot-id": 3055729675574597000, "timestamp-ms": 1555100955770 } ], "snapshots": [ { "manifest-list": "s3://my-bucket/__r2_data_catalog/wh-id/table-id/metadata/snap-3055729675574597004.avro", "schema-id": 1, "sequence-number": 1, "snapshot-id": 3055729675574597000, "summary": { "operation": "append" }, "timestamp-ms": 1555100955770 } ], "sort-orders": [ { "fields": [], "order-id": 0 } ], "table-uuid": "550e8400-e29b-41d4-a716-446655440000" }, "additionalProperties": true }, "r2-data-catalog_table-snapshot-expiration-config": { "type": "object", "properties": { "max_snapshot_age": { "description": "Specifies the maximum age for snapshots.", "type": "string", "example": "7d", "pattern": "^\\d+(d|h|m|s)$" }, "min_snapshots_to_keep": { "description": "Specifies the minimum number of snapshots to retain. Defaults to 100.", "type": "integer", "format": "int64", "example": 100, "minimum": 1 }, "next_eligible_at": { "description": "Earliest time when the scheduler can claim this operation. Null when disabled.", "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "state": { "$ref": "#/components/schemas/r2-data-catalog_catalog-maintenance-state" } }, "required": [ "state", "min_snapshots_to_keep", "max_snapshot_age" ] }, "r2-slurper_ConnectivityResponse": { "type": "object", "properties": { "connectivityStatus": { "type": "string", "enum": [ "success", "error" ] } } }, "r2-slurper_CreateJobRequest": { "type": "object", "properties": { "overwrite": { "type": "boolean", "default": true }, "source": { "$ref": "#/components/schemas/r2-slurper_SourceJobSchema" }, "target": { "$ref": "#/components/schemas/r2-slurper_R2TargetSchema" } } }, "r2-slurper_GCSLikeCredsSchema": { "type": "object", "properties": { "clientEmail": { "type": "string" }, "privateKey": { "type": "string", "x-sensitive": true } }, "required": [ "clientEmail", "privateKey" ] }, "r2-slurper_GCSSourceSchema": { "type": "object", "properties": { "bucket": { "type": "string" }, "keys": { "type": "array", "items": { "type": "string" }, "maxItems": 10000, "nullable": true }, "pathPrefix": { "type": "string", "nullable": true }, "secret": { "$ref": "#/components/schemas/r2-slurper_GCSLikeCredsSchema" }, "vendor": { "type": "string", "enum": [ "gcs" ] } }, "required": [ "vendor", "bucket", "secret" ] }, "r2-slurper_JobLogResponse": { "type": "object", "properties": { "createdAt": { "type": "string" }, "job": { "type": "string" }, "logType": { "type": "string", "enum": [ "migrationStart", "migrationComplete", "migrationAbort", "migrationError", "migrationPause", "migrationResume", "migrationErrorFailedContinuation", "importErrorRetryExhaustion", "importSkippedStorageClass", "importSkippedOversized", "importSkippedEmptyObject", "importSkippedUnsupportedContentType", "importSkippedExcludedContentType", "importSkippedInvalidMedia", "importSkippedRequiresRetrieval" ] }, "message": { "type": "string", "nullable": true }, "objectKey": { "type": "string", "nullable": true } } }, "r2-slurper_JobProgressResponse": { "type": "object", "properties": { "createdAt": { "type": "string" }, "failedObjects": { "type": "integer" }, "id": { "type": "string" }, "objects": { "type": "integer" }, "skippedObjects": { "type": "integer" }, "status": { "$ref": "#/components/schemas/r2-slurper_JobStatus" }, "transferredObjects": { "type": "integer" } } }, "r2-slurper_JobResponse": { "type": "object", "properties": { "createdAt": { "type": "string" }, "finishedAt": { "type": "string", "nullable": true }, "id": { "type": "string" }, "overwrite": { "type": "boolean" }, "source": { "oneOf": [ { "properties": { "bucket": { "type": "string" }, "endpoint": { "type": "string", "format": "uri", "nullable": true }, "keys": { "type": "array", "items": { "type": "string" }, "nullable": true }, "pathPrefix": { "type": "string", "nullable": true }, "vendor": { "type": "string", "enum": [ "s3" ] } }, "title": "S3SourceResponseSchema", "type": "object" }, { "properties": { "bucket": { "type": "string" }, "keys": { "type": "array", "items": { "type": "string" }, "nullable": true }, "pathPrefix": { "type": "string", "nullable": true }, "vendor": { "type": "string", "enum": [ "gcs" ] } }, "title": "GCSSourceResponseSchema", "type": "object" }, { "properties": { "bucket": { "type": "string" }, "jurisdiction": { "$ref": "#/components/schemas/r2-slurper_Jurisdiction" }, "keys": { "type": "array", "items": { "type": "string" }, "nullable": true }, "pathPrefix": { "type": "string", "nullable": true }, "vendor": { "type": "string", "enum": [ "r2" ] } }, "title": "R2SourceResponseSchema", "type": "object" } ] }, "status": { "$ref": "#/components/schemas/r2-slurper_JobStatus" }, "target": { "type": "object", "properties": { "bucket": { "type": "string" }, "jurisdiction": { "$ref": "#/components/schemas/r2-slurper_Jurisdiction" }, "vendor": { "type": "string", "enum": [ "r2" ] } }, "title": "R2TargetResponseSchema" } } }, "r2-slurper_JobStatus": { "type": "string", "enum": [ "running", "paused", "aborted", "completed" ] }, "r2-slurper_Jurisdiction": { "type": "string", "enum": [ "default", "eu", "us", "fedramp" ] }, "r2-slurper_R2SourceSchema": { "type": "object", "properties": { "bucket": { "type": "string" }, "jurisdiction": { "$ref": "#/components/schemas/r2-slurper_Jurisdiction" }, "keys": { "type": "array", "items": { "type": "string" }, "maxItems": 10000, "nullable": true }, "pathPrefix": { "type": "string", "nullable": true }, "secret": { "$ref": "#/components/schemas/r2-slurper_S3LikeCredsSchema" }, "vendor": { "type": "string", "enum": [ "r2" ] } }, "required": [ "vendor", "bucket", "secret" ] }, "r2-slurper_R2TargetSchema": { "type": "object", "properties": { "bucket": { "type": "string" }, "jurisdiction": { "$ref": "#/components/schemas/r2-slurper_Jurisdiction" }, "secret": { "$ref": "#/components/schemas/r2-slurper_S3LikeCredsSchema" }, "vendor": { "type": "string", "enum": [ "r2" ] } }, "required": [ "vendor", "bucket", "secret" ] }, "r2-slurper_S3LikeCredsSchema": { "type": "object", "properties": { "accessKeyId": { "type": "string" }, "secretAccessKey": { "type": "string", "x-sensitive": true } }, "required": [ "accessKeyId", "secretAccessKey" ] }, "r2-slurper_S3SourceSchema": { "type": "object", "properties": { "bucket": { "type": "string" }, "endpoint": { "description": "Custom S3-compatible endpoint that must use https://.", "type": "string", "format": "uri", "nullable": true }, "keys": { "type": "array", "items": { "type": "string" }, "maxItems": 10000, "nullable": true }, "pathPrefix": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "secret": { "$ref": "#/components/schemas/r2-slurper_S3LikeCredsSchema" }, "vendor": { "type": "string", "enum": [ "s3" ] } }, "required": [ "vendor", "bucket", "secret" ] }, "r2-slurper_SourceJobSchema": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/r2-slurper_S3SourceSchema" }, { "$ref": "#/components/schemas/r2-slurper_GCSSourceSchema" }, { "$ref": "#/components/schemas/r2-slurper_R2SourceSchema" } ] }, "r2-slurper_api-v4-error": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000, "x-auditable": true }, "message": { "type": "string", "x-auditable": true } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [ { "code": 7003, "message": "No route for the URI" } ], "minLength": 1 }, "r2-slurper_api-v4-failure": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/r2-slurper_api-v4-error" }, "messages": { "$ref": "#/components/schemas/r2-slurper_api-v4-message" }, "success": { "description": "Indicates if the API call was successful or not.", "type": "boolean", "example": false, "enum": [ false ], "x-auditable": true } } }, "r2-slurper_api-v4-message": { "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [] }, "r2-slurper_api-v4-success": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/r2-slurper_api-v4-error" }, "messages": { "$ref": "#/components/schemas/r2-slurper_api-v4-message" }, "success": { "description": "Indicates if the API call was successful or not.", "type": "boolean", "enum": [ true ], "x-auditable": true } } }, "r2_account_identifier": { "description": "Account ID.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 }, "r2_account_level_metrics": { "description": "Metrics based on the class they belong to.", "type": "object", "properties": { "infrequentAccess": { "$ref": "#/components/schemas/r2_class_based_metrics" }, "standard": { "$ref": "#/components/schemas/r2_class_based_metrics" } } }, "r2_add_custom_domain_request": { "type": "object", "properties": { "ciphers": { "description": "An allowlist of ciphers for TLS termination. These ciphers must be in the BoringSSL format.", "type": "array", "items": { "type": "string" }, "x-auditable": true }, "domain": { "description": "Name of the custom domain to be added.", "type": "string", "x-auditable": true }, "enabled": { "description": "Whether to enable public bucket access at the custom domain. If undefined, the domain will be enabled.", "type": "boolean", "x-auditable": true }, "minTLS": { "description": "Minimum TLS Version the custom domain will accept for incoming connections. If not set, defaults to 1.0.", "type": "string", "enum": [ "1.0", "1.1", "1.2", "1.3" ], "x-auditable": true }, "zoneId": { "description": "Zone ID of the custom domain.", "type": "string", "x-auditable": true } }, "example": { "domain": "prefix.example-domain.com", "enabled": true, "zoneId": "36ca64a6d92827b8a6b90be344bb1bfd" }, "required": [ "domain", "zoneId", "enabled" ] }, "r2_add_custom_domain_response": { "type": "object", "properties": { "ciphers": { "description": "An allowlist of ciphers for TLS termination. These ciphers must be in the BoringSSL format.", "type": "array", "items": { "type": "string" }, "x-auditable": true }, "domain": { "description": "Domain name of the affected custom domain.", "type": "string", "x-auditable": true }, "enabled": { "description": "Whether this bucket is publicly accessible at the specified custom domain.", "type": "boolean" }, "minTLS": { "description": "Minimum TLS Version the custom domain will accept for incoming connections. If not set, defaults to 1.0.", "type": "string", "enum": [ "1.0", "1.1", "1.2", "1.3" ], "x-auditable": true }, "zoneId": { "description": "Zone ID of the custom domain.", "type": "string", "x-auditable": true } }, "example": { "domain": "example-domain.com", "enabled": true, "zoneId": "36ca64a6d92827b8a6b90be344bb1bfd" }, "required": [ "domain", "enabled", "zoneId" ] }, "r2_bucket": { "description": "A single R2 bucket.", "type": "object", "properties": { "creation_date": { "description": "Creation timestamp.", "type": "string" }, "jurisdiction": { "$ref": "#/components/schemas/r2_jurisdiction" }, "location": { "$ref": "#/components/schemas/r2_bucket_location" }, "name": { "$ref": "#/components/schemas/r2_bucket_name" }, "storage_class": { "$ref": "#/components/schemas/r2_storage_class" } } }, "r2_bucket-config": { "type": "object", "properties": { "bucketName": { "description": "Name of the bucket.", "type": "string", "x-auditable": true }, "queues": { "description": "List of queues associated with the bucket.", "type": "array", "items": { "$ref": "#/components/schemas/r2_queues-config" } } } }, "r2_bucket-lock-rule": { "type": "object", "properties": { "condition": { "oneOf": [ { "$ref": "#/components/schemas/r2_lock-rule-age-condition" }, { "$ref": "#/components/schemas/r2_lock-rule-date-condition" }, { "$ref": "#/components/schemas/r2_lock-rule-indefinite-condition" } ] }, "enabled": { "description": "Whether or not this rule is in effect.", "type": "boolean", "x-auditable": true }, "id": { "description": "Unique identifier for this rule.", "type": "string", "example": "Lock all objects for 24 hours", "x-auditable": true }, "prefix": { "description": "Rule will only apply to objects/uploads in the bucket that start with the given prefix, an empty prefix can be provided to scope rule to all objects/uploads.", "type": "string", "x-auditable": true } }, "required": [ "id", "condition", "enabled" ] }, "r2_bucket-lock-rule-config": { "type": "object", "properties": { "rules": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/r2_bucket-lock-rule" } ] } } } }, "r2_bucket_location": { "description": "Location of the bucket.", "type": "string", "enum": [ "apac", "eeur", "enam", "weur", "wnam", "oc" ], "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "r2_bucket_name": { "description": "Name of the bucket.", "type": "string", "example": "example-bucket", "maxLength": 64, "minLength": 3, "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]", "x-auditable": true }, "r2_class_based_metrics": { "description": "Metrics based on what state they are in(uploaded or published).", "type": "object", "properties": { "published": { "$ref": "#/components/schemas/r2_object_size_metrics" }, "uploaded": { "$ref": "#/components/schemas/r2_object_size_metrics" } } }, "r2_cors-rule": { "type": "object", "properties": { "allowed": { "description": "Object specifying allowed origins, methods and headers for this CORS rule.", "type": "object", "properties": { "headers": { "description": "Specifies the value for the Access-Control-Allow-Headers header R2 sets when requesting objects in this bucket from a browser. Cross-origin requests that include custom headers (e.g. x-user-id) should specify these headers as AllowedHeaders.", "type": "array", "items": { "example": "x-requested-by", "type": "string", "x-auditable": true } }, "methods": { "description": "Specifies the value for the Access-Control-Allow-Methods header R2 sets when requesting objects in a bucket from a browser.", "type": "array", "items": { "enum": [ "GET", "PUT", "POST", "DELETE", "HEAD" ], "type": "string", "x-auditable": true } }, "origins": { "description": "Specifies the value for the Access-Control-Allow-Origin header R2 sets when requesting objects in a bucket from a browser.", "type": "array", "items": { "example": "http://localhost:3000", "type": "string", "x-auditable": true } } }, "required": [ "methods", "origins" ] }, "exposeHeaders": { "description": "Specifies the headers that can be exposed back, and accessed by, the JavaScript making the cross-origin request. If you need to access headers beyond the safelisted response headers, such as Content-Encoding or cf-cache-status, you must specify it here.", "type": "array", "items": { "example": "Content-Encoding", "type": "string", "x-auditable": true } }, "id": { "description": "Identifier for this rule.", "type": "string", "example": "Allow Local Development", "x-auditable": true }, "maxAgeSeconds": { "description": "Specifies the amount of time (in seconds) browsers are allowed to cache CORS preflight responses. Browsers may limit this to 2 hours or less, even if the maximum value (86400) is specified.", "type": "number", "example": 3600, "x-auditable": true } }, "required": [ "allowed" ] }, "r2_domain_name": { "description": "Name of the custom domain.", "type": "string", "example": "example-domain/custom-domain.com", "x-auditable": true }, "r2_edit_custom_domain_request": { "type": "object", "properties": { "ciphers": { "description": "An allowlist of ciphers for TLS termination. These ciphers must be in the BoringSSL format.", "type": "array", "items": { "type": "string" }, "x-auditable": true }, "enabled": { "description": "Whether to enable public bucket access at the specified custom domain.", "type": "boolean", "x-auditable": true }, "minTLS": { "description": "Minimum TLS Version the custom domain will accept for incoming connections. If not set, defaults to previous value.", "type": "string", "enum": [ "1.0", "1.1", "1.2", "1.3" ], "x-auditable": true } }, "example": { "enabled": true, "minTLS": "1.2" } }, "r2_edit_custom_domain_response": { "type": "object", "properties": { "ciphers": { "description": "An allowlist of ciphers for TLS termination. These ciphers must be in the BoringSSL format.", "type": "array", "items": { "type": "string" }, "x-auditable": true }, "domain": { "description": "Domain name of the affected custom domain.", "type": "string", "x-auditable": true }, "enabled": { "description": "Whether this bucket is publicly accessible at the specified custom domain.", "type": "boolean", "x-auditable": true }, "minTLS": { "description": "Minimum TLS Version the custom domain will accept for incoming connections. If not set, defaults to 1.0.", "type": "string", "enum": [ "1.0", "1.1", "1.2", "1.3" ], "x-auditable": true } }, "example": { "domain": "example-domain.com", "enabled": true }, "required": [ "domain" ] }, "r2_edit_managed_domain_request": { "type": "object", "properties": { "enabled": { "description": "Whether to enable public bucket access at the r2.dev domain.", "type": "boolean", "x-auditable": true } }, "example": { "enabled": true }, "required": [ "enabled" ] }, "r2_enable_sippy_aws": { "properties": { "destination": { "description": "R2 bucket to copy objects to.", "type": "object", "properties": { "accessKeyId": { "description": "ID of a Cloudflare API token.\nThis is the value labelled \"Access Key ID\" when creating an API.\ntoken from the [R2 dashboard](https://dash.cloudflare.com/?to=/:account/r2/api-tokens).\n\nSippy will use this token when writing objects to R2, so it is\nbest to scope this token to the bucket you're enabling Sippy for.\n", "type": "string" }, "provider": { "type": "string", "enum": [ "r2" ], "x-auditable": true }, "secretAccessKey": { "description": "Value of a Cloudflare API token.\nThis is the value labelled \"Secret Access Key\" when creating an API.\ntoken from the [R2 dashboard](https://dash.cloudflare.com/?to=/:account/r2/api-tokens).\n\nSippy will use this token when writing objects to R2, so it is\nbest to scope this token to the bucket you're enabling Sippy for.\n", "type": "string", "x-sensitive": true } } }, "source": { "description": "AWS S3 bucket to copy objects from.", "type": "object", "properties": { "accessKeyId": { "description": "Access Key ID of an IAM credential (ideally scoped to a single S3 bucket).", "type": "string" }, "bucket": { "description": "Name of the AWS S3 bucket.", "type": "string", "x-auditable": true }, "provider": { "type": "string", "enum": [ "aws" ], "x-auditable": true }, "region": { "description": "Name of the AWS availability zone.", "type": "string", "x-auditable": true }, "secretAccessKey": { "description": "Secret Access Key of an IAM credential (ideally scoped to a single S3 bucket).", "type": "string", "x-sensitive": true } } } } }, "r2_enable_sippy_azure": { "properties": { "destination": { "description": "R2 bucket to copy objects to.", "type": "object", "properties": { "accessKeyId": { "description": "ID of a Cloudflare API token.\nThis is the value labelled \"Access Key ID\" when creating an API.\ntoken from the [R2 dashboard](https://dash.cloudflare.com/?to=/:account/r2/api-tokens).\n\nSippy will use this token when writing objects to R2, so it is\nbest to scope this token to the bucket you're enabling Sippy for.\n", "type": "string" }, "provider": { "type": "string", "enum": [ "r2" ], "x-auditable": true }, "secretAccessKey": { "description": "Value of a Cloudflare API token.\nThis is the value labelled \"Secret Access Key\" when creating an API.\ntoken from the [R2 dashboard](https://dash.cloudflare.com/?to=/:account/r2/api-tokens).\n\nSippy will use this token when writing objects to R2, so it is\nbest to scope this token to the bucket you're enabling Sippy for.\n", "type": "string", "x-sensitive": true } } }, "source": { "description": "Azure Blob Storage container to copy objects from.", "type": "object", "properties": { "accountKey": { "description": "Access key for the Azure Storage account. Mutually exclusive with sasToken.", "type": "string", "x-sensitive": true }, "accountName": { "description": "Name of the Azure Storage account.", "type": "string", "x-auditable": true }, "container": { "description": "Name of the Azure Blob Storage container.", "type": "string", "x-auditable": true }, "provider": { "type": "string", "enum": [ "azure" ], "x-auditable": true }, "sasToken": { "description": "Shared Access Signature token for the Azure Storage account. Mutually exclusive with accountKey.", "type": "string", "x-sensitive": true } } } } }, "r2_enable_sippy_gcs": { "properties": { "destination": { "description": "R2 bucket to copy objects to.", "type": "object", "properties": { "accessKeyId": { "description": "ID of a Cloudflare API token.\nThis is the value labelled \"Access Key ID\" when creating an API.\ntoken from the [R2 dashboard](https://dash.cloudflare.com/?to=/:account/r2/api-tokens).\n\nSippy will use this token when writing objects to R2, so it is\nbest to scope this token to the bucket you're enabling Sippy for.\n", "type": "string" }, "provider": { "type": "string", "enum": [ "r2" ] }, "secretAccessKey": { "description": "Value of a Cloudflare API token.\nThis is the value labelled \"Secret Access Key\" when creating an API.\ntoken from the [R2 dashboard](https://dash.cloudflare.com/?to=/:account/r2/api-tokens).\n\nSippy will use this token when writing objects to R2, so it is\nbest to scope this token to the bucket you're enabling Sippy for.\n", "type": "string", "x-sensitive": true } } }, "source": { "description": "GCS bucket to copy objects from.", "type": "object", "properties": { "bucket": { "description": "Name of the GCS bucket.", "type": "string", "x-auditable": true }, "clientEmail": { "description": "Client email of an IAM credential (ideally scoped to a single GCS bucket).", "type": "string" }, "privateKey": { "description": "Private Key of an IAM credential (ideally scoped to a single GCS bucket).", "type": "string", "x-sensitive": true }, "provider": { "type": "string", "enum": [ "gcs" ] } } } } }, "r2_enable_sippy_s3": { "properties": { "destination": { "description": "R2 bucket to copy objects to.", "type": "object", "properties": { "accessKeyId": { "description": "ID of a Cloudflare API token.\nThis is the value labelled \"Access Key ID\" when creating an API.\ntoken from the [R2 dashboard](https://dash.cloudflare.com/?to=/:account/r2/api-tokens).\n\nSippy will use this token when writing objects to R2, so it is\nbest to scope this token to the bucket you're enabling Sippy for.\n", "type": "string" }, "provider": { "type": "string", "enum": [ "r2" ], "x-auditable": true }, "secretAccessKey": { "description": "Value of a Cloudflare API token.\nThis is the value labelled \"Secret Access Key\" when creating an API.\ntoken from the [R2 dashboard](https://dash.cloudflare.com/?to=/:account/r2/api-tokens).\n\nSippy will use this token when writing objects to R2, so it is\nbest to scope this token to the bucket you're enabling Sippy for.\n", "type": "string", "x-sensitive": true } } }, "source": { "description": "General S3-compatible provider to copy objects from.", "type": "object", "properties": { "accessKeyId": { "description": "Access Key ID of an IAM credential (ideally scoped to a single S3 bucket).", "type": "string" }, "bucketUrl": { "description": "URL to the S3-compatible API of the bucket.", "type": "string", "x-auditable": true }, "provider": { "type": "string", "enum": [ "s3" ], "x-auditable": true }, "secretAccessKey": { "description": "Secret Access Key of an IAM credential (ideally scoped to a single S3 bucket).", "type": "string", "x-sensitive": true } } } } }, "r2_errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true } }, "r2_get_custom_domain_response": { "type": "object", "properties": { "ciphers": { "description": "An allowlist of ciphers for TLS termination. These ciphers must be in the BoringSSL format.", "type": "array", "items": { "type": "string" }, "x-auditable": true }, "domain": { "description": "Domain name of the custom domain to be added.", "type": "string", "x-auditable": true }, "enabled": { "description": "Whether this bucket is publicly accessible at the specified custom domain.", "type": "boolean", "x-auditable": true }, "minTLS": { "description": "Minimum TLS Version the custom domain will accept for incoming connections. If not set, defaults to 1.0.", "type": "string", "enum": [ "1.0", "1.1", "1.2", "1.3" ], "x-auditable": true }, "status": { "type": "object", "properties": { "ownership": { "description": "Ownership status of the domain.", "type": "string", "enum": [ "pending", "active", "deactivated", "blocked", "error", "unknown" ], "x-auditable": true }, "ssl": { "description": "SSL certificate status.", "type": "string", "enum": [ "initializing", "pending", "active", "deactivated", "error", "unknown" ], "x-auditable": true } }, "required": [ "ssl", "ownership" ] }, "zoneId": { "description": "Zone ID of the custom domain resides in.", "type": "string", "x-auditable": true }, "zoneName": { "description": "Zone that the custom domain resides in.", "type": "string", "x-auditable": true } }, "example": { "domain": "prefix.example-domain.one.com", "enabled": false, "status": { "ownership": "deactivated", "ssl": "pending" }, "zoneId": "36ca64a6d92827b8a6b90be344bb1bfd", "zoneName": "example-domain.one.com" }, "required": [ "domain", "status", "enabled" ] }, "r2_jurisdiction": { "description": "Jurisdiction where objects in this bucket are guaranteed to be stored.", "type": "string", "default": "default", "enum": [ "default", "eu", "us", "fedramp", "fedramp-high" ], "x-auditable": true, "x-stainless-param": "jurisdiction" }, "r2_lifecycle-age-condition": { "description": "Condition for lifecycle transitions to apply after an object reaches an age in seconds.", "type": "object", "properties": { "maxAge": { "type": "integer", "x-auditable": true }, "type": { "type": "string", "enum": [ "Age" ], "x-auditable": true } }, "required": [ "type", "maxAge" ] }, "r2_lifecycle-config": { "type": "object", "properties": { "rules": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/r2_lifecycle-rule" } ] } } } }, "r2_lifecycle-date-condition": { "description": "Condition for lifecycle transitions to apply on a specific date.", "type": "object", "properties": { "date": { "type": "string", "format": "date-time", "x-auditable": true }, "type": { "type": "string", "enum": [ "Date" ], "x-auditable": true } }, "required": [ "type", "date" ] }, "r2_lifecycle-rule": { "type": "object", "properties": { "abortMultipartUploadsTransition": { "description": "Transition to abort ongoing multipart uploads.", "type": "object", "properties": { "condition": { "allOf": [ { "$ref": "#/components/schemas/r2_lifecycle-age-condition" } ] } } }, "conditions": { "description": "Conditions that apply to all transitions of this rule.", "type": "object", "properties": { "prefix": { "description": "Transitions will only apply to objects/uploads in the bucket that start with the given prefix, an empty prefix can be provided to scope rule to all objects/uploads.", "type": "string", "x-auditable": true } }, "required": [ "prefix" ] }, "deleteObjectsTransition": { "description": "Transition to delete objects.", "type": "object", "properties": { "condition": { "oneOf": [ { "$ref": "#/components/schemas/r2_lifecycle-age-condition" }, { "$ref": "#/components/schemas/r2_lifecycle-date-condition" } ] } } }, "enabled": { "description": "Whether or not this rule is in effect.", "type": "boolean", "x-auditable": true }, "id": { "description": "Unique identifier for this rule.", "type": "string", "example": "Expire all objects older than 24 hours", "x-auditable": true }, "storageClassTransitions": { "description": "Transitions to change the storage class of objects.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/r2_lifecycle-storage-transition" } ] } } }, "required": [ "id", "conditions", "enabled" ] }, "r2_lifecycle-storage-transition": { "type": "object", "properties": { "condition": { "oneOf": [ { "$ref": "#/components/schemas/r2_lifecycle-age-condition" }, { "$ref": "#/components/schemas/r2_lifecycle-date-condition" } ] }, "storageClass": { "type": "string", "enum": [ "InfrequentAccess" ], "x-auditable": true } }, "required": [ "condition", "storageClass" ] }, "r2_list_custom_domains_response": { "type": "object", "properties": { "domains": { "type": "array", "items": { "properties": { "ciphers": { "description": "An allowlist of ciphers for TLS termination. These ciphers must be in the BoringSSL format.", "type": "array", "items": { "type": "string" }, "x-auditable": true }, "domain": { "description": "Domain name of the custom domain to be added.", "type": "string", "x-auditable": true }, "enabled": { "description": "Whether this bucket is publicly accessible at the specified custom domain.", "type": "boolean", "x-auditable": true }, "minTLS": { "description": "Minimum TLS Version the custom domain will accept for incoming connections. If not set, defaults to 1.0.", "type": "string", "enum": [ "1.0", "1.1", "1.2", "1.3" ], "x-auditable": true }, "status": { "type": "object", "properties": { "ownership": { "description": "Ownership status of the domain.", "type": "string", "enum": [ "pending", "active", "deactivated", "blocked", "error", "unknown" ], "x-auditable": true }, "ssl": { "description": "SSL certificate status.", "type": "string", "enum": [ "initializing", "pending", "active", "deactivated", "error", "unknown" ], "x-auditable": true } }, "required": [ "ssl", "ownership" ] }, "zoneId": { "description": "Zone ID of the custom domain resides in.", "type": "string", "x-auditable": true }, "zoneName": { "description": "Zone that the custom domain resides in.", "type": "string", "x-auditable": true } }, "required": [ "domain", "status", "enabled" ], "type": "object" } } }, "example": { "domains": [ { "domain": "prefix.example-domain.one.com", "enabled": false, "status": { "ownership": "deactivated", "ssl": "pending" }, "zoneId": "36ca64a6d92827b8a6b90be344bb1bfd", "zoneName": "example-domain.one.com" }, { "domain": "prefix.example-domain.two.com", "enabled": true, "status": { "ownership": "active", "ssl": "active" }, "zoneId": "d9d28585d5f8f5b0f857b055bf574f19" } ] }, "required": [ "domains" ] }, "r2_local_uploads_configuration": { "description": "Configuration for local uploads on a bucket.", "type": "object", "properties": { "enabled": { "description": "Whether local uploads is enabled for this bucket. When enabled, object's data is written to the nearest region first, then asynchronously replicated to the bucket's primary region.", "type": "boolean", "x-auditable": true } } }, "r2_lock-rule-age-condition": { "description": "Condition to apply a lock rule to an object for how long in seconds.", "type": "object", "properties": { "maxAgeSeconds": { "type": "integer", "example": 100, "x-auditable": true }, "type": { "type": "string", "enum": [ "Age" ], "x-auditable": true } }, "required": [ "type", "maxAgeSeconds" ] }, "r2_lock-rule-date-condition": { "description": "Condition to apply a lock rule to an object until a specific date.", "type": "object", "properties": { "date": { "type": "string", "format": "date-time", "x-auditable": true }, "type": { "type": "string", "enum": [ "Date" ], "x-auditable": true } }, "required": [ "type", "date" ] }, "r2_lock-rule-indefinite-condition": { "description": "Condition to apply a lock rule indefinitely.", "type": "object", "properties": { "type": { "type": "string", "enum": [ "Indefinite" ], "x-auditable": true } }, "required": [ "type" ] }, "r2_managed_domain_response": { "type": "object", "properties": { "bucketId": { "description": "Bucket ID.", "type": "string", "maxLength": 32, "x-auditable": true }, "domain": { "description": "Domain name of the bucket's r2.dev domain.", "type": "string", "x-auditable": true }, "enabled": { "description": "Whether this bucket is publicly accessible at the r2.dev domain.", "type": "boolean", "x-auditable": true } }, "example": { "bucketId": "0113a9e4549cf9b1ff1bf56e04da0cef", "domain": "pub-0113a9e4549cf9b1ff1bf56e04da0cef.r2.dev", "enabled": true }, "required": [ "bucketId", "domain", "enabled" ] }, "r2_messages": { "type": "array", "items": { "type": "string" } }, "r2_object_size_metrics": { "description": "Metrics on number of objects/amount of storage used.", "type": "object", "properties": { "metadataSize": { "description": "Amount of.", "type": "number" }, "objects": { "description": "Number of objects stored.", "type": "number" }, "payloadSize": { "description": "Amount of storage used by object data.", "type": "number" } } }, "r2_queue_identifier": { "description": "Queue ID.", "type": "string", "example": "11111aa1-11aa-111a-a1a1-a1a111a11a11", "maxLength": 32, "x-auditable": true }, "r2_queues-config": { "type": "object", "properties": { "queueId": { "description": "Queue ID.", "type": "string", "example": "11111aa1-11aa-111a-a1a1-a1a111a11a11", "x-auditable": true }, "queueName": { "description": "Name of the queue.", "type": "string", "example": "first-queue", "x-auditable": true }, "rules": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/r2_rule" }, { "properties": { "createdAt": { "description": "Timestamp when the rule was created.", "type": "string", "example": "2024-09-19T21:54:48.405Z", "x-auditable": true }, "description": { "description": "A description that can be used to identify the event notification rule after creation.", "type": "string", "example": "Notifications from source bucket to queue", "x-auditable": true }, "ruleId": { "description": "Rule ID.", "type": "string", "example": "11111aa1-11aa-111a-a1a1-a1a111a11a11", "x-auditable": true } }, "type": "object" } ] } } } }, "r2_r2-action": { "type": "string", "enum": [ "PutObject", "CopyObject", "DeleteObject", "CompleteMultipartUpload", "LifecycleDeletion" ], "x-auditable": true }, "r2_r2_bucket_job": { "description": "Descriptor of a bucket background job. Returned when the delete-objects endpoint is\ninvoked with a `prefix` query parameter, and by the Get Bucket Job and List Bucket Jobs\nendpoints. An empty prefix indicates an Empty Bucket job. A small operation can already\nbe `COMPLETED` when it is returned.\n", "type": "object", "properties": { "endTime": { "description": "When the job finished. Absent while the job is still `ENQUEUED` or `RUNNING`.\n", "type": "string", "format": "date-time" }, "id": { "description": "Unique identifier used to poll the job.", "type": "string" }, "jobType": { "description": "The job kind. Always `prefixDelete` for this endpoint.", "type": "string", "enum": [ "prefixDelete" ] }, "prefixDelete": { "description": "Details specific to the prefix-delete job.", "type": "object", "properties": { "deletedObjects": { "description": "Number of objects deleted by the job so far.", "type": "integer", "example": 0 }, "isBucketClear": { "description": "True when the job was created to clear the entire bucket. This field can be absent\non jobs created before Empty Bucket job tracking was introduced.\n", "type": "boolean" }, "prefix": { "description": "The prefix matched against object keys. An empty string means the entire bucket.", "type": "string", "example": "path/to/" } }, "required": [ "prefix", "deletedObjects" ] }, "startTime": { "description": "When the job was created.", "type": "string", "format": "date-time" }, "status": { "$ref": "#/components/schemas/r2_r2_bucket_job_status" } }, "required": [ "id", "jobType", "status", "startTime", "prefixDelete" ] }, "r2_r2_bucket_job_status": { "description": "Lifecycle status of a bucket background job.", "type": "string", "enum": [ "ENQUEUED", "RUNNING", "COMPLETED", "FAILED", "CANCELLED" ] }, "r2_r2_bucket_jobs_result": { "type": "object", "properties": { "jobs": { "description": "Bucket jobs in the current page.", "type": "array", "items": { "$ref": "#/components/schemas/r2_r2_bucket_job" } }, "nextContinuationToken": { "description": "Token to pass as `continuationToken` to retrieve the next page.", "type": "string" } }, "required": [ "jobs" ] }, "r2_r2_delete_object_result": { "description": "Result of a successful object deletion.", "type": "object", "properties": { "key": { "description": "The key (name) of the deleted object.", "type": "string", "example": "path/to/my-object.txt" } } }, "r2_r2_list_objects_result_info": { "description": "Pagination information for list objects responses.", "type": "object", "properties": { "cursor": { "description": "Pagination cursor to use in the next List Objects call to retrieve the next page of results.", "type": "string", "example": "eyJrZXkiOiJwYXRoL3RvL215LW9iamVjdC50eHQifQ==" }, "delimited": { "description": "Common prefixes found when a delimiter is specified. Each entry represents a group\nof keys sharing a common prefix up to the delimiter. Equivalent to S3's `CommonPrefixes`\nin `ListObjectsV2`; the field name differs because of the existing R2 API wire format.\n", "type": "array", "items": { "type": "string" }, "example": [ "path/to/", "another/path/" ] }, "is_truncated": { "description": "Whether the result was truncated. If true, use the cursor to retrieve the next page.", "type": "boolean", "example": true }, "per_page": { "description": "The maximum number of objects returned per page.", "type": "integer", "example": 20 } } }, "r2_r2_object": { "description": "Metadata for an R2 object.", "type": "object", "properties": { "custom_metadata": { "description": "Custom metadata key-value pairs associated with the object.", "type": "object", "example": {}, "additionalProperties": { "type": "string" } }, "etag": { "description": "The entity tag for the object. In JSON list/get responses this is the raw\nhex digest (without surrounding quotes). The HTTP `ETag` response header on\nGet Object follows RFC 7232 and IS wrapped in surrounding double-quotes.\n", "type": "string", "example": "d41d8cd98f00b204e9800998ecf8427e" }, "http_metadata": { "$ref": "#/components/schemas/r2_r2_object_http_metadata" }, "key": { "description": "The object key (name).", "type": "string", "example": "path/to/my-object.txt" }, "last_modified": { "description": "The date and time the object was last modified.", "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" }, "size": { "description": "The size of the object in bytes.", "type": "integer", "example": 1048576 }, "ssec": { "description": "Whether the object is encrypted with a customer-supplied encryption key.", "type": "boolean", "example": false }, "storage_class": { "$ref": "#/components/schemas/r2_storage_class" } } }, "r2_r2_object_http_metadata": { "description": "HTTP metadata associated with an R2 object.", "type": "object", "properties": { "cacheControl": { "description": "Specifies caching behavior for the object.", "type": "string", "example": "max-age=3600" }, "cacheExpiry": { "description": "The date and time at which the object's cache entry expires.", "type": "string", "format": "date-time", "example": "2024-12-31T23:59:59Z" }, "contentDisposition": { "description": "Specifies presentational information for the object.", "type": "string", "example": "attachment; filename=\"example.jpg\"" }, "contentEncoding": { "description": "Specifies the content encoding applied to the object.", "type": "string", "example": "gzip" }, "contentLanguage": { "description": "The language of the object content.", "type": "string", "example": "en-US" }, "contentType": { "description": "The MIME type of the object.", "type": "string", "example": "image/jpeg" } } }, "r2_r2_put_object_result": { "description": "Result of a successful object upload.", "type": "object", "properties": { "etag": { "description": "The entity tag for the uploaded object.", "type": "string", "example": "d41d8cd98f00b204e9800998ecf8427e" }, "key": { "description": "The key (name) of the uploaded object.", "type": "string", "example": "path/to/my-object.txt" }, "size": { "description": "The size of the uploaded object in bytes (as a string).", "type": "string", "example": "1048576" }, "storage_class": { "$ref": "#/components/schemas/r2_storage_class" }, "uploaded": { "description": "The date and time the object was uploaded.", "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" }, "version": { "description": "The version UUID of the uploaded object.", "type": "string", "example": "3fd5b4a8-1234-5678-abcd-ef0123456789" } } }, "r2_r2_storage_class_migration_job": { "description": "Descriptor of a bucket-wide storage-class migration job.", "type": "object", "properties": { "endTime": { "description": "When the job finished. Absent while the job is still `ENQUEUED` or `RUNNING`.\n", "type": "string", "format": "date-time" }, "id": { "description": "Unique identifier used to poll the job.", "type": "string" }, "jobType": { "description": "The job kind.", "type": "string", "enum": [ "storageClassMigration" ] }, "startTime": { "description": "When the job was created.", "type": "string", "format": "date-time" }, "status": { "$ref": "#/components/schemas/r2_r2_bucket_job_status" }, "storageClassMigration": { "type": "object", "properties": { "destinationStorageClass": { "description": "The storage class objects are migrated to. The source and destination storage\nclasses always differ.\n", "type": "string", "enum": [ "Standard", "InfrequentAccess" ] }, "failedBytes": { "description": "Payload bytes belonging to failed object versions.", "type": "integer", "minimum": 0 }, "failedObjects": { "description": "Number of object versions that failed migration.", "type": "integer", "minimum": 0 }, "migratedBytes": { "description": "Object payload bytes migrated successfully. Present for Metadata Worker jobs.", "type": "integer", "minimum": 0 }, "migratedMetadataBytes": { "description": "Object metadata bytes migrated successfully. Present for Metadata Worker jobs.", "type": "integer", "minimum": 0 }, "migratedObjects": { "description": "Number of object versions migrated successfully.", "type": "integer", "minimum": 0 }, "skippedBytes": { "description": "Payload bytes belonging to skipped object versions.", "type": "integer", "minimum": 0 }, "skippedObjects": { "description": "Number of object versions skipped.", "type": "integer", "minimum": 0 }, "sourceStorageClass": { "description": "The storage class objects are migrated from.", "type": "string", "enum": [ "Standard", "InfrequentAccess" ] } }, "required": [ "sourceStorageClass", "destinationStorageClass", "migratedObjects" ] } }, "required": [ "id", "jobType", "status", "startTime", "storageClassMigration" ] }, "r2_r2_storage_class_migration_jobs_result": { "type": "object", "properties": { "jobs": { "description": "Storage-class migration jobs in the current page.", "type": "array", "items": { "$ref": "#/components/schemas/r2_r2_storage_class_migration_job" } }, "nextContinuationToken": { "description": "Token to pass as `continuationToken` to retrieve the next page.", "type": "string" } }, "required": [ "jobs" ] }, "r2_remove_custom_domain_response": { "type": "object", "properties": { "domain": { "description": "Name of the removed custom domain.", "type": "string", "x-auditable": true } }, "example": { "domain": "example-domain/custom-domain.com" }, "required": [ "domain" ] }, "r2_result_info": { "type": "object", "properties": { "cursor": { "description": "A continuation token that should be used to fetch the next page of results.", "type": "string", "example": "1-JTdCJTIydiUyMiUzQTElMkMlMjJzdGFydEFmdGVyJTIyJTNBJTIyZGF2aWRwdWJsaWMlMjIlN0Q=" }, "per_page": { "description": "Maximum number of results on this page.", "type": "number", "example": 20 } } }, "r2_rule": { "type": "object", "properties": { "actions": { "description": "Array of R2 object actions that will trigger notifications.", "type": "array", "items": { "$ref": "#/components/schemas/r2_r2-action" }, "example": [ "PutObject", "CopyObject" ], "uniqueItems": true }, "description": { "description": "A description that can be used to identify the event notification rule after creation.", "type": "string", "example": "Notifications from source bucket to queue", "x-auditable": true }, "prefix": { "description": "Notifications will be sent only for objects with this prefix.", "type": "string", "example": "img/", "x-auditable": true }, "suffix": { "description": "Notifications will be sent only for objects with this suffix.", "type": "string", "example": ".jpeg", "x-auditable": true } }, "required": [ "actions" ] }, "r2_sippy": { "type": "object", "properties": { "destination": { "description": "Details about the configured destination bucket.", "type": "object", "properties": { "accessKeyId": { "description": "ID of the Cloudflare API token used when writing objects to this\nbucket.\n", "type": "string" }, "account": { "type": "string", "x-auditable": true }, "bucket": { "description": "Name of the bucket on the provider.", "type": "string", "x-auditable": true }, "provider": { "type": "string", "enum": [ "r2" ], "x-auditable": true } } }, "enabled": { "description": "State of Sippy for this bucket.", "type": "boolean", "x-auditable": true }, "source": { "description": "Details about the configured source bucket.", "type": "object", "properties": { "bucket": { "description": "Name of the bucket on the provider (AWS, GCS only).", "type": "string", "nullable": true, "x-auditable": true }, "bucketUrl": { "description": "S3-compatible URL (Generic S3-compatible providers only).", "type": "string", "nullable": true, "x-auditable": true }, "container": { "description": "Name of the Azure Blob Storage container (Azure only).", "type": "string", "nullable": true, "x-auditable": true }, "provider": { "type": "string", "enum": [ "aws", "gcs", "s3", "azure" ], "x-auditable": true }, "region": { "description": "Region where the bucket resides (AWS only).", "type": "string", "nullable": true, "x-auditable": true } } } } }, "r2_storage_class": { "description": "Storage class for newly uploaded objects, unless specified otherwise.", "type": "string", "default": "Standard", "enum": [ "Standard", "InfrequentAccess" ], "x-auditable": true }, "r2_temp_access_creds_request": { "type": "object", "properties": { "bucket": { "description": "Name of the R2 bucket.", "type": "string", "x-auditable": true }, "objects": { "description": "Optional object paths to scope the credentials to.", "type": "array", "items": { "type": "string", "x-auditable": true } }, "parentAccessKeyId": { "description": "The parent access key id to use for signing.", "type": "string" }, "permission": { "description": "Permissions allowed on the credentials.", "type": "string", "enum": [ "admin-read-write", "admin-read-only", "object-read-write", "object-read-only" ], "x-auditable": true }, "prefixes": { "description": "Optional prefix paths to scope the credentials to.", "type": "array", "items": { "type": "string", "x-auditable": true } }, "ttlSeconds": { "description": "How long the credentials will live for in seconds.", "type": "number", "default": 900, "maximum": 604800, "x-auditable": true } }, "example": { "bucket": "example-bucket", "objects": [ "example-object" ], "parentAccessKeyId": "example-access-key-id", "permission": "object-read-write", "prefixes": [ "example-prefix/" ], "ttlSeconds": 3600 }, "required": [ "bucket", "permission", "ttlSeconds", "parentAccessKeyId" ] }, "r2_temp_access_creds_response": { "type": "object", "properties": { "accessKeyId": { "description": "ID for new access key.", "type": "string" }, "secretAccessKey": { "description": "Secret access key.", "type": "string", "x-sensitive": true }, "sessionToken": { "description": "Security token.", "type": "string", "x-sensitive": true } }, "example": { "accessKeyId": "example-access-key-id", "secretAccessKey": "example-secret-key", "sessionToken": "example-session-token" } }, "r2_v4_response": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/r2_errors" }, "messages": { "$ref": "#/components/schemas/r2_messages" }, "result": { "type": "object" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "r2_v4_response_failure": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/r2_errors" }, "messages": { "$ref": "#/components/schemas/r2_messages" }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "r2_v4_response_list": { "allOf": [ { "$ref": "#/components/schemas/r2_v4_response" }, { "properties": { "result_info": { "$ref": "#/components/schemas/r2_result_info" } }, "type": "object" } ] }, "realtimekit_AIConfig": { "description": "The AI Config allows you to customize the behavior of meeting transcriptions and summaries", "type": "object", "properties": { "summarization": { "$ref": "#/components/schemas/realtimekit_SummarizationConfig" }, "transcription": { "$ref": "#/components/schemas/realtimekit_TranscriptionConfig" } }, "title": "AIConfig" }, "realtimekit_ActiveSession": { "type": "object", "properties": { "associated_id": { "description": "ID of the meeting this session is associated with. In the case of V2 meetings, it is always a UUID. In V1 meetings, it is a room name of the form `abcdef-ghijkl`", "type": "string" }, "breakout_rooms": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_ActiveSession" }, "readOnly": true }, "created_at": { "description": "timestamp when session created", "type": "string" }, "ended_at": { "description": "timestamp when session ended", "type": "string" }, "id": { "description": "ID of the session", "type": "string", "readOnly": true }, "live_participants": { "description": "number of participants currently in the session", "type": "number" }, "max_concurrent_participants": { "description": "number of maximum participants that were in the session", "type": "number" }, "meeting_display_name": { "description": "Title of the meeting this session belongs to", "type": "string" }, "minutes_consumed": { "description": "number of minutes consumed since the session started", "type": "number" }, "organization_id": { "description": "App id that hosted this session", "type": "string" }, "started_at": { "description": "timestamp when session started", "type": "string" }, "status": { "description": "current status of session", "type": "string", "enum": [ "LIVE", "ENDED" ] }, "type": { "description": "type of session", "type": "string", "enum": [ "meeting", "livestream", "participant" ] }, "updated_at": { "description": "timestamp when session was last updated", "type": "string" } }, "required": [ "id", "associated_id", "meeting_display_name", "type", "status", "live_participants", "max_concurrent_participants", "minutes_consumed", "organization_id", "started_at", "created_at", "updated_at" ] }, "realtimekit_AudioConfig": { "description": "Object containing configuration regarding the audio that is being recorded.", "type": "object", "properties": { "channel": { "description": "Audio signal pathway within an audio file that carries a specific sound source.", "type": "string", "default": "stereo", "enum": [ "mono", "stereo" ] }, "codec": { "description": "Codec using which the recording will be encoded. If VP8/VP9 is selected for videoConfig, changing audioConfig is not allowed. In this case, the codec in the audioConfig is automatically set to vorbis.", "type": "string", "default": "AAC", "enum": [ "MP3", "AAC" ] }, "export_file": { "description": "Controls whether to export audio file seperately", "type": "boolean", "default": true } }, "title": "AudioConfig" }, "realtimekit_AudioConsumerStats": { "description": "Per-sample inbound (consumer) audio statistics.", "type": "object", "properties": { "bytes_received": { "type": "number" }, "concealment_events": { "type": "number" }, "consumer_id": { "type": "string" }, "jitter": { "type": "number" }, "jitter_buffer_delay": { "type": "number" }, "jitter_buffer_emitted_count": { "type": "number" }, "mid": { "type": "string" }, "mos_quality": { "type": "number" }, "packets_lost": { "type": "number" }, "packets_received": { "type": "number" }, "peer_id": { "type": "string" }, "producer_id": { "type": "string" }, "ssrc": { "type": "number" }, "timestamp": { "type": "string" } } }, "realtimekit_AudioConsumerStatsCumulative": { "description": "Aggregated inbound (consumer) audio statistics for the session.", "type": "object", "properties": { "jitter_buffer_delay": { "$ref": "#/components/schemas/realtimekit_LatencyCumulative" }, "packet_loss": { "$ref": "#/components/schemas/realtimekit_PacketLossCumulative" }, "quality_mos": { "$ref": "#/components/schemas/realtimekit_PercentileStats" } } }, "realtimekit_AudioProducerStats": { "description": "Per-sample outbound (producer) audio statistics.", "type": "object", "properties": { "bytes_sent": { "type": "number" }, "jitter": { "type": "number" }, "mid": { "type": "string" }, "mos_quality": { "type": "number" }, "packets_lost": { "type": "number" }, "packets_sent": { "type": "number" }, "producer_id": { "type": "string" }, "rtt": { "type": "number" }, "ssrc": { "type": "number" }, "timestamp": { "type": "string" } } }, "realtimekit_AudioProducerStatsCumulative": { "description": "Aggregated outbound (producer) audio statistics for the session.", "type": "object", "properties": { "packet_loss": { "$ref": "#/components/schemas/realtimekit_PacketLossCumulative" }, "quality_mos": { "$ref": "#/components/schemas/realtimekit_PercentileStats" }, "rtt": { "$ref": "#/components/schemas/realtimekit_LatencyCumulative" } } }, "realtimekit_CandidatePairStats": { "description": "ICE candidate pair statistics for a transport.", "type": "object", "properties": { "available_incoming_bitrate": { "type": "number" }, "available_outgoing_bitrate": { "type": "number" }, "bytes_discarded_on_send": { "type": "number" }, "bytes_received": { "type": "number" }, "bytes_sent": { "type": "number" }, "current_round_trip_time": { "type": "number" }, "last_packet_received_timestamp": { "description": "Epoch milliseconds when the last packet was received.", "type": "number" }, "last_packet_sent_timestamp": { "description": "Epoch milliseconds when the last packet was sent.", "type": "number" }, "local_candidate_address": { "type": "string" }, "local_candidate_id": { "type": "string" }, "local_candidate_network_type": { "type": "string" }, "local_candidate_port": { "type": "number" }, "local_candidate_protocol": { "type": "string" }, "local_candidate_related_address": { "type": "string" }, "local_candidate_related_port": { "type": "number" }, "local_candidate_type": { "type": "string" }, "local_candidate_url": { "type": "string" }, "nominated": { "type": "boolean" }, "packets_discarded_on_send": { "type": "number" }, "packets_received": { "type": "number" }, "packets_sent": { "type": "number" }, "remote_candidate_address": { "type": "string" }, "remote_candidate_id": { "type": "string" }, "remote_candidate_port": { "type": "number" }, "remote_candidate_protocol": { "type": "string" }, "remote_candidate_type": { "type": "string" }, "remote_candidate_url": { "type": "string" }, "total_round_trip_time": { "type": "number" } } }, "realtimekit_ChatMessage": { "type": "object", "properties": { "chat_download_url": { "description": "URL where the chat logs can be downloaded", "type": "string" }, "chat_download_url_expiry": { "description": "Time when the download URL will expire", "type": "string" } }, "required": [ "chat_download_url", "chat_download_url_expiry" ] }, "realtimekit_CreateChatChannelInfo": { "type": "object", "properties": { "custom_participant_ids": { "type": "array", "items": { "type": "string" } }, "display_name": { "type": "string" }, "visibility": { "type": "string", "enum": [ "public", "private" ] } } }, "realtimekit_DaywiseStats": { "type": "object", "properties": { "date": { "description": "Date in YYYY-MM-DD format", "type": "string" }, "recordings_minutes_consumed": { "description": "Total recordings minutes consumed across all sessions in the given time period.", "type": "number" }, "sessions_count": { "description": "Number of sessions_count happened in the given time period", "type": "number" }, "sessions_minutes_consumed": { "description": "Total meetings minutes consumed across all sessions in the given time period.", "type": "number" } } }, "realtimekit_ErrorResponse": { "type": "object", "properties": { "error": { "description": "Object containing details of the error that occurred", "type": "object", "properties": { "code": { "description": "Error code", "type": "number", "example": 404 }, "message": { "description": "Error message", "type": "string", "example": "Error: resource not found" } }, "required": [ "code", "message" ] }, "success": { "description": "Whether the operation succeeded or not", "type": "boolean", "example": false } }, "required": [ "success", "error" ] }, "realtimekit_GenericErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "HTTP status code of the error.", "type": "number" }, "message": { "description": "Error message describing what went wrong.", "type": "string" } }, "required": [ "code", "message" ] }, "success": { "description": "Success status of the request.", "type": "boolean", "default": false } }, "required": [ "success", "error" ] }, "realtimekit_GenericSuccessResponse": { "type": "object", "properties": { "data": { "description": "Data returned by the operation", "type": "object" }, "success": { "description": "Success status of the operation", "type": "boolean", "default": true } }, "required": [ "success" ], "title": "GenericSuccessResponse" }, "realtimekit_InteractiveConfig": { "description": "Allows you to add timed metadata to your recordings, which are digital markers inserted into a video file to provide contextual information at specific points in the content range. The ID3 tags containing this information are available to clients on the playback timeline in HLS format. The output files are generated in a compressed .tar format.", "type": "object", "properties": { "type": { "description": "The metadata is presented in the form of ID3 tags.", "type": "string", "enum": [ "ID3" ] } }, "title": "InteractiveConfig" }, "realtimekit_LatencyCumulative": { "description": "Cumulative latency distribution (milliseconds-based thresholds).", "type": "object", "properties": { "100ms_or_greater_event_fraction": { "type": "number" }, "250ms_or_greater_event_fraction": { "type": "number" }, "500ms_or_greater_event_fraction": { "type": "number" }, "avg": { "type": "number" } } }, "realtimekit_LivestreamBase": { "type": "object", "properties": { "created_at": { "description": "The timestamp at which the livestream was created. The time is returned in ISO format.", "type": "string", "format": "date-time" }, "disabled": { "description": "Specifies if the livestream was disabled.", "type": "boolean" }, "id": { "description": "The livestream ID.", "type": "string" }, "ingest_server": { "description": "The server URL to which the RTMP encoder sends the video and audio data.", "type": "string" }, "meeting_id": { "description": "ID of the meeting.", "type": "string", "nullable": true }, "name": { "description": "Name of the livestream.", "type": "string", "nullable": true }, "org_id": { "type": "string" }, "playback_url": { "description": "The web address that viewers can use to watch the livestream.", "type": "string" }, "status": { "description": "The status of the livestream.", "type": "string", "enum": [ "LIVE", "IDLE", "ERRORED", "INVOKED" ] }, "stream_key": { "description": "Unique key for accessing each livestream.", "type": "string", "x-sensitive": true }, "updated_at": { "description": "The timestamp at which the livestream was updated. The time is returned in ISO format.", "type": "string", "format": "date-time" } } }, "realtimekit_LivestreamingConfig": { "type": "object", "properties": { "rtmp_url": { "description": "RTMP URL to stream to", "type": "string", "format": "uri", "example": "rtmp://a.rtmp.youtube.com/live2" } }, "title": "LivestreamingConfig" }, "realtimekit_Meeting": { "type": "object", "properties": { "created_at": { "description": "Timestamp the object was created at. The time is returned in ISO format.", "type": "string", "format": "date-time", "readOnly": true }, "id": { "description": "ID of the meeting.", "type": "string", "format": "uuid", "readOnly": true }, "live_stream_on_start": { "description": "Specifies if the meeting should start getting livestreamed on start.", "type": "boolean" }, "persist_chat": { "description": "Specifies if Chat within a meeting should persist for a week.", "type": "boolean" }, "record_on_start": { "description": "Specifies if the meeting should start getting recorded as soon as someone joins the meeting.", "type": "boolean" }, "recording_config": { "$ref": "#/components/schemas/realtimekit_RecordingConfig" }, "session_keep_alive_time_in_secs": { "description": "Time in seconds, for which a session remains active, after the last participant has left the meeting.", "type": "number", "default": 60, "maximum": 600, "minimum": 60 }, "status": { "description": "Whether the meeting is `ACTIVE` or `INACTIVE`. Users will not be able to join an `INACTIVE` meeting.", "type": "string", "enum": [ "ACTIVE", "INACTIVE" ] }, "summarize_on_end": { "description": "Automatically generate summary of meetings using transcripts. Requires Transcriptions to be enabled, and can be retrieved via Webhooks or summary API.", "type": "boolean" }, "title": { "description": "Title of the meeting.", "type": "string" }, "transcribe_on_end": { "description": "Automatically generate transcripts when the meeting ends.", "type": "boolean" }, "updated_at": { "description": "Timestamp the object was updated at. The time is returned in ISO format.", "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "id", "created_at", "updated_at" ] }, "realtimekit_OverallStats": { "type": "object", "properties": { "recordings_minutes_consumed": { "description": "Total recordings minutes consumed across all sessions in the given time period.", "type": "number" }, "sessions_count": { "description": "Number of sessions_count happened in the given time period", "type": "number" }, "sessions_minutes_consumed": { "description": "Total meetings minutes consumed across all sessions in the given time period.", "type": "number" } } }, "realtimekit_PacketLossCumulative": { "description": "Cumulative packet loss distribution.", "type": "object", "properties": { "10_or_greater_event_fraction": { "type": "number" }, "25_or_greater_event_fraction": { "type": "number" }, "50_or_greater_event_fraction": { "type": "number" }, "5_or_greater_event_fraction": { "type": "number" }, "avg": { "type": "number" } } }, "realtimekit_PagingResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "paging": { "type": "object", "properties": { "end_offset": { "type": "number", "example": 30 }, "start_offset": { "type": "number", "example": 1 }, "total_count": { "type": "number", "example": 30, "minimum": 0 } }, "required": [ "total_count", "start_offset", "end_offset" ] }, "success": { "type": "boolean", "example": true } }, "required": [ "success", "data", "paging" ], "title": "PagingResponse" }, "realtimekit_Participant": { "description": "Represents a participant.", "type": "object", "properties": { "created_at": { "description": "When this object was created. The time is returned in ISO format.", "type": "string", "format": "date-time" }, "custom_participant_id": { "description": "A unique participant ID generated by the client.", "type": "string" }, "id": { "description": "ID of the participant.", "type": "string", "format": "uuid" }, "name": { "description": "Name of the participant.", "type": "string", "nullable": true }, "picture": { "description": "URL to a picture of the participant.", "type": "string", "format": "uri", "nullable": true }, "preset_name": { "description": "Preset applied to the participant.", "type": "string" }, "updated_at": { "description": "When this object was updated. The time is returned in ISO format.", "type": "string", "format": "date-time" } }, "required": [ "id", "custom_participant_id", "preset_name", "created_at", "updated_at" ], "title": "Participant" }, "realtimekit_ParticipantsList": { "type": "object", "properties": { "created_at": { "description": "timestamp when this participant was created.", "type": "string" }, "custom_participant_id": { "description": "ID passed by client to create this participant.", "type": "string" }, "display_name": { "description": "Display name of participant when joining the session.", "type": "string" }, "duration": { "description": "number of minutes for which the participant was in the session.", "type": "number" }, "id": { "description": "Participant ID. This maps to the corresponding peerId.", "type": "string" }, "joined_at": { "description": "timestamp at which participant joined the session.", "type": "string" }, "left_at": { "description": "timestamp at which participant left the session.", "type": "string" }, "peer_events": { "description": "Connection lifecycle events for the participant's peer. Only included when `include_peer_events` is true.", "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_PeerEvent" } }, "preset_name": { "description": "Name of the preset associated with the participant.", "type": "string" }, "updated_at": { "description": "timestamp when this participant's data was last updated.", "type": "string" }, "user_id": { "description": "User id for this participant.", "type": "string" } } }, "realtimekit_PatchWebhookRequest": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true }, "events": { "description": "Events that the webhook will get triggered by", "type": "array", "items": { "enum": [ "meeting.started", "meeting.ended", "meeting.participantJoined", "meeting.participantLeft", "recording.statusUpdate", "livestreaming.statusUpdate", "meeting.chatSynced", "meeting.transcript", "meeting.summary" ], "type": "string" } }, "name": { "description": "Name of the webhook", "type": "string" }, "url": { "description": "URL the webhook will send events to", "type": "string", "format": "uri", "example": "https://webhook.site/b23a5bbd-c7b0-4ced-a9e2-78ae7889897e" } } }, "realtimekit_PeerEvent": { "description": "A connection lifecycle event recorded for a participant's peer.", "type": "object", "properties": { "created_at": { "description": "Timestamp when this peer event was created.", "type": "string" }, "event_name": { "description": "Name of the peer event.", "type": "string", "enum": [ "PEER_CREATED", "PEER_JOINING", "PEER_LEAVING" ] }, "id": { "description": "ID of the peer event.", "type": "string" }, "minutes_consumed": { "description": "Minutes consumed attributed to this event.", "type": "number" }, "participant_id": { "description": "ID of the participant this event belongs to.", "type": "string", "nullable": true }, "peer_id": { "description": "Peer ID this event belongs to.", "type": "string" }, "preset_view_type": { "description": "View type of the preset associated with the peer.", "type": "string", "enum": [ "GROUP_CALL", "WEBINAR", "AUDIO_ROOM", "LIVESTREAM", "CHAT" ], "nullable": true }, "session_id": { "description": "ID of the session this event belongs to.", "type": "string", "nullable": true }, "socket_session_id": { "description": "ID of the socket session associated with this event.", "type": "string", "nullable": true }, "updated_at": { "description": "Timestamp when this peer event was last updated.", "type": "string" } } }, "realtimekit_PeerParticipantDetails": { "type": "object", "properties": { "created_at": { "description": "timestamp when this participant was created.", "type": "string" }, "custom_participant_id": { "description": "ID passed by client to create this participant.", "type": "string" }, "display_name": { "description": "Display name of participant when joining the session.", "type": "string" }, "duration": { "description": "number of minutes for which the participant was in the session.", "type": "number" }, "id": { "description": "ID of the participant.", "type": "string", "format": "uuid" }, "joined_at": { "description": "timestamp at which participant joined the session.", "type": "string" }, "left_at": { "description": "timestamp at which participant left the session.", "type": "string" }, "peer_events": { "description": "Connection lifecycle events for the participant's peer.", "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_PeerEvent" } }, "peer_report": { "$ref": "#/components/schemas/realtimekit_PeerReport" }, "role": { "description": "Name of the preset associated with the participant.", "type": "string" }, "session_id": { "type": "string", "format": "uuid" }, "updated_at": { "description": "timestamp when this participant's data was last updated.", "type": "string" }, "user_id": { "description": "User id for this participant.", "type": "string" } } }, "realtimekit_PeerReport": { "description": "Peer call statistics report.", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/realtimekit_PeerReportMetadata" }, "quality": { "$ref": "#/components/schemas/realtimekit_PeerReportQuality" } } }, "realtimekit_PeerReportDevice": { "description": "A media device (camera, microphone, or speaker).", "type": "object", "properties": { "device_id": { "description": "ID of the device.", "type": "string" }, "kind": { "description": "Kind of device, for example audioinput or videoinput.", "type": "string" }, "label": { "description": "Human-readable label of the device.", "type": "string" } } }, "realtimekit_PeerReportDeviceUpdate": { "description": "A change to the set of available devices at a point in time.", "type": "object", "properties": { "added": { "description": "Devices that became available.", "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_PeerReportDevice" } }, "removed": { "description": "Devices that became unavailable.", "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_PeerReportDevice" } }, "timestamp": { "description": "Timestamp of the device update.", "type": "string" } } }, "realtimekit_PeerReportEvent": { "description": "A timestamped event recorded during the participant's connection.", "type": "object", "properties": { "metadata": { "description": "Event-specific metadata. Keys vary per event; values are primitive scalars (string, number, boolean, or null).", "type": "object", "additionalProperties": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "name": { "description": "Name of the event.", "type": "string" }, "timestamp": { "description": "Timestamp when the event occurred.", "type": "string" } } }, "realtimekit_PeerReportMetadata": { "description": "Connection and device metadata for the participant.", "type": "object", "properties": { "audio_devices_updates": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_PeerReportDeviceUpdate" } }, "browser_metadata": { "type": "object", "properties": { "browser": { "type": "string" }, "browser_version": { "type": "string" }, "engine": { "type": "string" }, "user_agent": { "type": "string" }, "webgl_support": { "type": "boolean", "nullable": true } } }, "candidate_pairs": { "type": "object", "properties": { "consuming_transport": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_CandidatePairStats" } }, "producing_transport": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_CandidatePairStats" } } } }, "device_info": { "type": "object", "properties": { "cpus": { "type": "number" }, "is_mobile": { "type": "boolean" }, "os": { "type": "string" }, "os_version": { "type": "string" } } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_PeerReportEvent" } }, "ip_information": { "type": "object", "properties": { "asn": { "type": "object", "properties": { "asn": { "type": "string" }, "domain": { "type": "string" }, "name": { "type": "string" }, "route": { "type": "string" }, "type": { "type": "string" } } }, "city": { "type": "string" }, "country": { "type": "string" }, "ipv4": { "type": "string" }, "org": { "type": "string" }, "region": { "type": "string" }, "timezone": { "type": "string" } } }, "native_metadata": { "type": "object", "properties": { "audio_encoder": { "type": "string" }, "video_encoder": { "type": "string" } } }, "pc_metadata": { "type": "array", "items": { "properties": { "effective_network_type": { "type": "string" }, "reflexive_connectivity": { "type": "boolean" }, "relay_connectivity": { "type": "boolean" }, "sdp": { "type": "array", "items": { "type": "string" } }, "timestamp": { "type": "string" }, "turn_connectivity": { "type": "boolean" } }, "type": "object" } }, "room_view_type": { "type": "string" }, "sdk_name": { "type": "string" }, "sdk_type": { "type": "string" }, "sdk_version": { "type": "string" }, "selected_device_updates": { "type": "array", "items": { "properties": { "device": { "$ref": "#/components/schemas/realtimekit_PeerReportDevice" }, "timestamp": { "type": "string" } }, "type": "object" } }, "speaker_devices_updates": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_PeerReportDeviceUpdate" } }, "video_devices_updates": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_PeerReportDeviceUpdate" } } } }, "realtimekit_PeerReportQuality": { "description": "Media quality statistics for the participant.", "type": "object", "properties": { "audio_consumer": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_AudioConsumerStats" } }, "audio_consumer_cumulative": { "$ref": "#/components/schemas/realtimekit_AudioConsumerStatsCumulative" }, "audio_producer": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_AudioProducerStats" } }, "audio_producer_cumulative": { "$ref": "#/components/schemas/realtimekit_AudioProducerStatsCumulative" }, "screenshare_audio_consumer": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_AudioConsumerStats" } }, "screenshare_audio_consumer_cumulative": { "$ref": "#/components/schemas/realtimekit_AudioConsumerStatsCumulative" }, "screenshare_audio_producer": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_AudioProducerStats" } }, "screenshare_audio_producer_cumulative": { "$ref": "#/components/schemas/realtimekit_AudioProducerStatsCumulative" }, "screenshare_video_consumer": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_VideoConsumerStats" } }, "screenshare_video_consumer_cumulative": { "$ref": "#/components/schemas/realtimekit_VideoConsumerStatsCumulative" }, "screenshare_video_producer": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_VideoProducerStats" } }, "screenshare_video_producer_cumulative": { "$ref": "#/components/schemas/realtimekit_VideoProducerStatsCumulative" }, "video_consumer": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_VideoConsumerStats" } }, "video_consumer_cumulative": { "$ref": "#/components/schemas/realtimekit_VideoConsumerStatsCumulative" }, "video_producer": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_VideoProducerStats" } }, "video_producer_cumulative": { "$ref": "#/components/schemas/realtimekit_VideoProducerStatsCumulative" } } }, "realtimekit_PercentileStats": { "description": "Distribution summary with average and percentiles.", "type": "object", "properties": { "avg": { "type": "number" }, "p50": { "type": "number" }, "p75": { "type": "number" }, "p90": { "type": "number" } } }, "realtimekit_Poll": { "type": "object", "properties": { "anonymous": { "type": "boolean" }, "created_by": { "type": "string" }, "hide_votes": { "type": "boolean" }, "id": { "description": "ID of the poll", "type": "string", "readOnly": true }, "options": { "description": "Answer options", "type": "array", "items": { "properties": { "count": { "type": "number" }, "text": { "description": "Text of the answer option", "type": "string" }, "votes": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" } } }, "required": [ "text", "count", "votes" ], "type": "object" } }, "question": { "description": "Question asked by the poll", "type": "string" }, "voted": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "question", "options" ] }, "realtimekit_Preset": { "type": "object", "properties": { "config": { "type": "object", "properties": { "livestream_viewer_qualities": { "description": "Livestream viewer quality levels.", "type": "array", "items": { "minimum": 0, "type": "integer" }, "default": [], "nullable": true }, "max_screenshare_count": { "description": "Maximum number of screen shares that can be active at a given time", "type": "number" }, "max_video_streams": { "description": "Maximum number of streams that are visible on a device", "type": "object", "properties": { "desktop": { "description": "Maximum number of video streams visible on desktop devices", "type": "number" }, "mobile": { "description": "Maximum number of streams visible on mobile devices", "type": "number" } }, "required": [ "mobile", "desktop" ] }, "media": { "description": "Media configuration options. eg: Video quality", "type": "object", "properties": { "audio": { "description": "Control options for Audio quality.", "type": "object", "properties": { "enable_high_bitrate": { "description": "Enable High Quality Audio for your meetings", "type": "boolean" }, "enable_stereo": { "description": "Enable Stereo for your meetings", "type": "boolean" } } }, "screenshare": { "description": "Configuration options for participant screen shares", "type": "object", "properties": { "frame_rate": { "description": "Frame rate of screen share", "type": "number" }, "quality": { "description": "Quality of screen share ", "type": "string", "enum": [ "hd", "vga", "qvga", "fhd", "uhd" ] } }, "required": [ "quality", "frame_rate" ] }, "video": { "description": "Configuration options for participant videos", "type": "object", "properties": { "frame_rate": { "description": "Frame rate of participants' video", "type": "number", "maximum": 30 }, "quality": { "description": "Video quality of participants", "type": "string", "enum": [ "hd", "vga", "qvga", "fhd", "uhd" ] }, "simulcast": { "description": "Enable simulcast for participant videos.", "type": "boolean", "default": false } }, "required": [ "quality", "frame_rate" ] } }, "required": [ "video", "screenshare" ] }, "view_type": { "description": "Type of the meeting", "type": "string", "enum": [ "GROUP_CALL", "WEBINAR", "AUDIO_ROOM", "LIVESTREAM" ] } }, "required": [ "view_type", "max_video_streams", "max_screenshare_count", "media" ] }, "name": { "description": "Name of the preset", "type": "string" }, "permissions": { "type": "object", "properties": { "accept_stage_requests": { "type": "boolean" }, "accept_waiting_requests": { "description": "Whether this participant can accept waiting requests", "type": "boolean" }, "can_accept_production_requests": { "type": "boolean" }, "can_change_participant_permissions": { "type": "boolean" }, "can_edit_display_name": { "type": "boolean" }, "can_livestream": { "type": "boolean" }, "can_record": { "type": "boolean" }, "can_spotlight": { "type": "boolean" }, "chat": { "type": "object", "properties": { "private": { "type": "object", "properties": { "can_receive": { "type": "boolean" }, "can_send": { "type": "boolean" }, "files": { "type": "boolean" }, "text": { "type": "boolean" } }, "required": [ "can_send", "can_receive", "text", "files" ] }, "public": { "type": "object", "properties": { "can_send": { "description": "Can send messages in general", "type": "boolean" }, "files": { "description": "Can send file messages", "type": "boolean" }, "text": { "description": "Can send text messages", "type": "boolean" } }, "required": [ "can_send", "text", "files" ] } }, "required": [ "public", "private" ] }, "connected_meetings": { "type": "object", "properties": { "can_alter_connected_meetings": { "type": "boolean" }, "can_switch_connected_meetings": { "type": "boolean" }, "can_switch_to_parent_meeting": { "type": "boolean" } }, "required": [ "can_alter_connected_meetings", "can_switch_connected_meetings", "can_switch_to_parent_meeting" ] }, "disable_participant_audio": { "type": "boolean" }, "disable_participant_screensharing": { "type": "boolean" }, "disable_participant_video": { "type": "boolean" }, "hidden_participant": { "description": "Whether this participant is visible to others or not", "type": "boolean" }, "is_recorder": { "type": "boolean" }, "kick_participant": { "type": "boolean" }, "media": { "description": "Media permissions", "type": "object", "properties": { "audio": { "description": "Audio permissions", "type": "object", "properties": { "can_produce": { "description": "Can produce audio", "type": "string", "enum": [ "ALLOWED", "NOT_ALLOWED", "CAN_REQUEST" ] } }, "required": [ "can_produce" ] }, "screenshare": { "description": "Screenshare permissions", "type": "object", "properties": { "can_produce": { "description": "Can produce screen share video", "type": "string", "enum": [ "ALLOWED", "NOT_ALLOWED", "CAN_REQUEST" ] } }, "required": [ "can_produce" ] }, "video": { "description": "Video permissions", "type": "object", "properties": { "can_produce": { "description": "Can produce video", "type": "string", "enum": [ "ALLOWED", "NOT_ALLOWED", "CAN_REQUEST" ] } }, "required": [ "can_produce" ] } }, "required": [ "video", "audio", "screenshare" ] }, "pin_participant": { "type": "boolean" }, "plugins": { "description": "Plugin permissions", "type": "object", "properties": { "can_close": { "description": "Can close plugins that are already open", "type": "boolean" }, "can_edit_config": { "description": "Can edit plugin config", "type": "boolean" }, "can_start": { "description": "Can start plugins", "type": "boolean" }, "config": { "$ref": "#/components/schemas/realtimekit_PresetPluginConfig" } }, "required": [ "can_close", "can_start", "can_edit_config", "config" ] }, "polls": { "description": "Poll permissions", "type": "object", "properties": { "can_create": { "description": "Can create polls", "type": "boolean" }, "can_view": { "description": "Can view polls", "type": "boolean" }, "can_vote": { "description": "Can vote on polls", "type": "boolean" } }, "required": [ "can_create", "can_vote", "can_view" ] }, "recorder_type": { "description": "Type of the recording peer", "type": "string", "enum": [ "RECORDER", "LIVESTREAMER", "NONE" ] }, "show_participant_list": { "type": "boolean" }, "stage_access": { "type": "string", "enum": [ "ALLOWED", "NOT_ALLOWED", "CAN_REQUEST" ] }, "stage_enabled": { "type": "boolean" }, "transcription_enabled": { "type": "boolean" }, "waiting_room_type": { "description": "Waiting room type", "type": "string", "enum": [ "SKIP", "ON_PRIVILEGED_USER_ENTRY", "SKIP_ON_ACCEPT" ] } }, "required": [ "accept_waiting_requests", "can_accept_production_requests", "can_edit_display_name", "can_spotlight", "recorder_type", "disable_participant_audio", "disable_participant_screensharing", "disable_participant_video", "kick_participant", "pin_participant", "can_record", "can_livestream", "waiting_room_type", "plugins", "connected_meetings", "polls", "media", "chat", "hidden_participant", "show_participant_list", "can_change_participant_permissions" ] }, "ui": { "type": "object", "properties": { "design_tokens": { "type": "object", "properties": { "border_radius": { "type": "string", "enum": [ "sharp", "rounded", "extra-rounded", "circular" ] }, "border_width": { "type": "string", "enum": [ "none", "thin", "fat" ] }, "colors": { "type": "object", "properties": { "background": { "type": "object", "properties": { "600": { "type": "string" }, "700": { "type": "string" }, "800": { "type": "string" }, "900": { "type": "string" }, "1000": { "type": "string" } }, "required": [ "600", "700", "800", "900", "1000" ] }, "brand": { "type": "object", "properties": { "300": { "type": "string" }, "400": { "type": "string" }, "500": { "type": "string" }, "600": { "type": "string" }, "700": { "type": "string" } }, "required": [ "300", "400", "500", "600", "700" ] }, "danger": { "type": "string" }, "success": { "type": "string" }, "text": { "type": "string" }, "text_on_brand": { "type": "string" }, "video_bg": { "type": "string" }, "warning": { "type": "string" } }, "required": [ "brand", "background", "danger", "text", "text_on_brand", "success", "video_bg", "warning" ] }, "font_family": { "type": "string" }, "google_font": { "type": "string" }, "logo": { "type": "string", "format": "uri" }, "spacing_base": { "type": "number", "minimum": 1 }, "theme": { "type": "string", "enum": [ "darkest", "dark", "light" ] } }, "required": [ "border_radius", "border_width", "spacing_base", "theme", "colors" ] } }, "required": [ "design_tokens" ] } }, "required": [ "name", "config", "permissions", "ui" ], "title": "Preset" }, "realtimekit_PresetListItem": { "description": "Returned by Get All Presets route", "type": "object", "properties": { "created_at": { "description": "Timestamp this preset was created at", "type": "string", "format": "date-time" }, "id": { "description": "ID of the preset", "type": "string", "format": "uuid" }, "name": { "description": "Name of the preset", "type": "string" }, "updated_at": { "description": "Timestamp this preset was last updated", "type": "string", "format": "date-time" } }, "title": "PresetListItem" }, "realtimekit_PresetPluginConfig": { "description": "Plugin configuration keyed by plugin UUID.", "type": "object", "additionalProperties": { "additionalProperties": true, "properties": { "access_control": { "type": "string", "enum": [ "FULL_ACCESS", "VIEW_ONLY" ] }, "handles_view_only": { "type": "boolean" } }, "type": "object" } }, "realtimekit_Recording": { "type": "object", "properties": { "audio_download_url": { "description": "If the audio_config is passed, the URL for downloading the audio recording is returned.", "type": "string", "format": "uri", "nullable": true, "readOnly": true }, "download_url": { "description": "URL where the recording can be downloaded.", "type": "string", "format": "uri", "nullable": true, "readOnly": true }, "download_url_expiry": { "description": "Timestamp when the download URL expires.", "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "file_size": { "description": "File size of the recording, in bytes.", "type": "number", "nullable": true, "readOnly": true }, "id": { "description": "ID of the recording", "type": "string", "format": "uuid", "readOnly": true }, "invoked_time": { "description": "Timestamp when this recording was invoked.", "type": "string", "format": "date-time" }, "output_file_name": { "description": "File name of the recording.", "type": "string" }, "recording_duration": { "description": "Total recording time in seconds.", "type": "integer" }, "session_id": { "description": "ID of the meeting session this recording is for.", "type": "string", "format": "uuid", "nullable": true, "readOnly": true }, "started_time": { "description": "Timestamp when this recording actually started after being invoked. Usually a few seconds after `invoked_time`.", "type": "string", "format": "date-time", "nullable": true }, "status": { "description": "Current status of the recording.", "type": "string", "enum": [ "INVOKED", "RECORDING", "UPLOADING", "UPLOADED", "ERRORED", "PAUSED" ] }, "stopped_time": { "description": "Timestamp when this recording was stopped. Optional; is present only when the recording has actually been stopped.", "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "download_url", "download_url_expiry", "audio_download_url", "file_size", "session_id", "output_file_name", "status", "invoked_time", "started_time", "stopped_time" ], "title": "Recording" }, "realtimekit_RecordingConfig": { "description": "Recording Configurations to be used for this meeting. This level of configs takes higher preference over App level configs on the RealtimeKit developer portal.\n", "type": "object", "properties": { "audio_config": { "$ref": "#/components/schemas/realtimekit_AudioConfig" }, "file_name_prefix": { "description": "Adds a prefix to the beginning of the file name of the recording.", "type": "string" }, "live_streaming_config": { "$ref": "#/components/schemas/realtimekit_LivestreamingConfig" }, "max_seconds": { "description": "Specifies the maximum duration for recording in seconds, ranging from a minimum of 60 seconds to a maximum of 24 hours.", "type": "number", "maximum": 86400, "minimum": 60 }, "realtimekit_bucket_config": { "$ref": "#/components/schemas/realtimekit_realtimekitBucketConfig" }, "storage_config": { "$ref": "#/components/schemas/realtimekit_StorageConfig" }, "video_config": { "$ref": "#/components/schemas/realtimekit_VideoConfig" } }, "title": "RecordingConfig" }, "realtimekit_SessionParticipant": { "type": "object", "properties": { "created_at": { "type": "string" }, "email": { "description": "Email of the session participant.", "type": "string" }, "id": { "description": "ID of the session participant", "type": "string" }, "name": { "description": "Name of the session participant.", "type": "string" }, "picture": { "description": "A URL pointing to a picture of the participant.", "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "created_at", "updated_at" ], "title": "SessionParticipant" }, "realtimekit_StorageConfig": { "type": "object", "properties": { "access_key": { "description": "Access key of the storage medium. Access key is not required for the `gcs` storage media type.\n\nNote that this field is not readable by clients, only writeable.", "type": "string", "writeOnly": true, "x-sensitive": true }, "auth_method": { "description": "Authentication method used for \"sftp\" type storage medium\n", "type": "string", "enum": [ "KEY", "PASSWORD" ] }, "bucket": { "description": "Name of the storage medium's bucket.", "type": "string" }, "host": { "description": "SSH destination server host for SFTP type storage medium", "type": "string" }, "password": { "description": "SSH destination server password for SFTP type storage medium when auth_method is \"PASSWORD\". If auth_method is \"KEY\", this specifies the password for the ssh private key.", "type": "string", "writeOnly": true, "x-sensitive": true }, "path": { "description": "Path relative to the bucket root at which the recording will be placed.", "type": "string" }, "port": { "description": "SSH destination server port for SFTP type storage medium", "type": "number" }, "private_key": { "description": "Private key used to login to destination SSH server for SFTP type storage medium, when auth_method used is \"KEY\"", "type": "string", "writeOnly": true, "x-sensitive": true }, "region": { "description": "Region of the storage medium.", "type": "string", "example": "us-east-1" }, "secret": { "description": "Secret key of the storage medium. Similar to `access_key`, it is only writeable by clients, not readable.", "type": "string", "writeOnly": true, "x-sensitive": true }, "type": { "description": "Type of storage media.", "type": "string", "enum": [ "aws", "azure", "digitalocean", "gcs", "sftp" ] }, "username": { "description": "SSH destination server username for SFTP type storage medium", "type": "string" } }, "nullable": true, "oneOf": [ { "properties": { "type": { "enum": [ "gcs" ] } } }, { "properties": { "access_key": { "minLength": 1 }, "region": { "minLength": 1 }, "type": { "enum": [ "aws", "azure", "digitalocean" ] } }, "required": [ "access_key", "region" ] }, { "oneOf": [ { "properties": { "auth_method": { "enum": [ "KEY" ] } }, "required": [ "private_key" ] }, { "properties": { "auth_method": { "enum": [ "PASSWORD" ] } }, "required": [ "password" ] } ], "properties": { "access_key": { "minLength": 1 }, "region": { "minLength": 1 }, "type": { "enum": [ "sftp" ] } }, "required": [ "access_key", "region", "auth_method", "username", "host", "port" ] } ], "required": [ "type", "bucket" ], "title": "StorageConfig" }, "realtimekit_SummarizationConfig": { "description": "Summary Config", "type": "object", "properties": { "summary_type": { "description": "Defines the style of the summary, such as general, team meeting, or sales call.", "type": "string", "default": "general", "enum": [ "general", "team_meeting", "sales_call", "client_check_in", "interview", "daily_standup", "one_on_one_meeting", "lecture", "code_review" ] }, "text_format": { "description": "Determines the text format of the summary, such as plain text or markdown.", "type": "string", "default": "markdown", "enum": [ "plain_text", "markdown" ] }, "word_limit": { "description": "Sets the maximum number of words in the meeting summary.", "type": "integer", "default": 500, "maximum": 1000, "minimum": 150 } }, "title": "SummarizationConfig" }, "realtimekit_TrackConfigLayer": { "type": "object", "properties": { "file_name_prefix": { "description": "A file name prefix to apply for files generated from this layer", "type": "string", "pattern": "^[-\\w\\s]+$" }, "media_kind": { "description": "Media kind to record. Track recording currently supports audio only.", "type": "string", "default": "audio", "enum": [ "audio" ] } }, "title": "TrackLayerConfig" }, "realtimekit_Transcript": { "type": "object", "properties": { "sessionId": { "type": "string" }, "transcript_download_url": { "description": "URL where the transcript can be downloaded", "type": "string" }, "transcript_download_url_expiry": { "description": "Time when the download URL will expire", "type": "string" } }, "required": [ "sessionId", "transcript_download_url", "transcript_download_url_expiry" ] }, "realtimekit_TranscriptSummary": { "type": "object", "properties": { "sessionId": { "type": "string" }, "summaryDownloadUrl": { "description": "URL where the summary of transcripts can be downloaded", "type": "string" }, "summaryDownloadUrlExpiry": { "description": "Time of Expiry before when you need to download the csv file.", "type": "string" } }, "required": [ "sessionId", "summaryDownloadUrl", "summaryDownloadUrlExpiry" ], "title": "TranscriptSummary" }, "realtimekit_TranscriptionConfig": { "description": "Transcription Configurations", "type": "object", "properties": { "keywords": { "description": "Adds specific terms to improve accurate detection during transcription.", "type": "array", "items": { "type": "string" } }, "language": { "description": "Specifies the language code for transcription to ensure accurate results.", "type": "string", "default": "en-US", "enum": [ "en-US", "en-IN", "de", "hi", "sv", "ru", "pl", "el", "fr", "nl" ] }, "profanity_filter": { "description": "Control the inclusion of offensive language in transcriptions.", "type": "boolean", "default": false } }, "title": "TranscriptionConfig" }, "realtimekit_UpdatePreset": { "type": "object", "properties": { "config": { "type": "object", "properties": { "livestream_viewer_qualities": { "description": "Livestream viewer quality levels.", "type": "array", "items": { "minimum": 0, "type": "integer" }, "default": [], "nullable": true }, "max_screenshare_count": { "description": "Maximum number of screen shares that can be active at a given time", "type": "number" }, "max_video_streams": { "description": "Maximum number of streams that are visible on a device", "type": "object", "properties": { "desktop": { "description": "Maximum number of video streams visible on desktop devices", "type": "number" }, "mobile": { "description": "Maximum number of streams visible on mobile devices", "type": "number" } } }, "media": { "description": "Media configuration options. eg: Video quality", "type": "object", "properties": { "audio": { "description": "Control options for Audio quality.", "type": "object", "properties": { "enable_high_bitrate": { "description": "Enable High Quality Audio for your meetings", "type": "boolean" }, "enable_stereo": { "description": "Enable Stereo for your meetings", "type": "boolean" } } }, "screenshare": { "description": "Configuration options for participant screen shares", "type": "object", "properties": { "frame_rate": { "description": "Frame rate of screen share", "type": "number" }, "quality": { "description": "Quality of screen share ", "type": "string", "enum": [ "hd", "vga", "qvga", "fhd", "uhd" ] } } }, "video": { "description": "Configuration options for participant videos", "type": "object", "properties": { "frame_rate": { "description": "Frame rate of participants' video", "type": "number", "maximum": 30 }, "quality": { "description": "Video quality of participants", "type": "string", "enum": [ "hd", "vga", "qvga", "fhd", "uhd" ] }, "simulcast": { "description": "Enable simulcast for participant videos.", "type": "boolean" } } } } }, "view_type": { "description": "Type of the meeting", "type": "string", "enum": [ "GROUP_CALL", "WEBINAR", "AUDIO_ROOM", "LIVESTREAM" ] } } }, "name": { "description": "Name of the preset", "type": "string" }, "permissions": { "type": "object", "properties": { "accept_stage_requests": { "type": "boolean" }, "accept_waiting_requests": { "description": "Whether this participant can accept waiting requests", "type": "boolean" }, "can_accept_production_requests": { "type": "boolean" }, "can_change_participant_permissions": { "type": "boolean" }, "can_edit_display_name": { "type": "boolean" }, "can_livestream": { "type": "boolean" }, "can_record": { "type": "boolean" }, "can_spotlight": { "type": "boolean" }, "chat": { "type": "object", "properties": { "private": { "type": "object", "properties": { "can_receive": { "type": "boolean" }, "can_send": { "type": "boolean" }, "files": { "type": "boolean" }, "text": { "type": "boolean" } } }, "public": { "type": "object", "properties": { "can_send": { "description": "Can send messages in general", "type": "boolean" }, "files": { "description": "Can send file messages", "type": "boolean" }, "text": { "description": "Can send text messages", "type": "boolean" } } } } }, "connected_meetings": { "type": "object", "properties": { "can_alter_connected_meetings": { "type": "boolean" }, "can_switch_connected_meetings": { "type": "boolean" }, "can_switch_to_parent_meeting": { "type": "boolean" } } }, "disable_participant_audio": { "type": "boolean" }, "disable_participant_screensharing": { "type": "boolean" }, "disable_participant_video": { "type": "boolean" }, "hidden_participant": { "description": "Whether this participant is visible to others or not", "type": "boolean" }, "is_recorder": { "type": "boolean" }, "kick_participant": { "type": "boolean" }, "media": { "description": "Media permissions", "type": "object", "properties": { "audio": { "description": "Audio permissions", "type": "object", "properties": { "can_produce": { "description": "Can produce audio", "type": "string", "enum": [ "ALLOWED", "NOT_ALLOWED", "CAN_REQUEST" ] } } }, "screenshare": { "description": "Screenshare permissions", "type": "object", "properties": { "can_produce": { "description": "Can produce screen share video", "type": "string", "enum": [ "ALLOWED", "NOT_ALLOWED", "CAN_REQUEST" ] } } }, "video": { "description": "Video permissions", "type": "object", "properties": { "can_produce": { "description": "Can produce video", "type": "string", "enum": [ "ALLOWED", "NOT_ALLOWED", "CAN_REQUEST" ] } } } } }, "pin_participant": { "type": "boolean" }, "plugins": { "description": "Plugin permissions", "type": "object", "properties": { "can_close": { "description": "Can close plugins that are already open", "type": "boolean" }, "can_edit_config": { "description": "Can edit plugin config", "type": "boolean" }, "can_start": { "description": "Can start plugins", "type": "boolean" }, "config": { "$ref": "#/components/schemas/realtimekit_PresetPluginConfig" } } }, "polls": { "description": "Poll permissions", "type": "object", "properties": { "can_create": { "description": "Can create polls", "type": "boolean" }, "can_view": { "description": "Can view polls", "type": "boolean" }, "can_vote": { "description": "Can vote on polls", "type": "boolean" } } }, "recorder_type": { "description": "Type of the recording peer", "type": "string", "enum": [ "RECORDER", "LIVESTREAMER", "NONE" ] }, "show_participant_list": { "type": "boolean" }, "stage_access": { "type": "string", "enum": [ "ALLOWED", "NOT_ALLOWED", "CAN_REQUEST" ] }, "stage_enabled": { "type": "boolean" }, "transcription_enabled": { "type": "boolean" }, "waiting_room_type": { "description": "Waiting room type", "type": "string", "enum": [ "SKIP", "ON_PRIVILEGED_USER_ENTRY", "SKIP_ON_ACCEPT" ] } } }, "ui": { "type": "object", "properties": { "design_tokens": { "type": "object", "properties": { "border_radius": { "type": "string", "enum": [ "sharp", "rounded", "extra-rounded", "circular" ] }, "border_width": { "type": "string", "enum": [ "none", "thin", "fat" ] }, "colors": { "type": "object", "properties": { "background": { "type": "object", "properties": { "600": { "type": "string" }, "700": { "type": "string" }, "800": { "type": "string" }, "900": { "type": "string" }, "1000": { "type": "string" } } }, "brand": { "type": "object", "properties": { "300": { "type": "string" }, "400": { "type": "string" }, "500": { "type": "string" }, "600": { "type": "string" }, "700": { "type": "string" } } }, "danger": { "type": "string" }, "success": { "type": "string" }, "text": { "type": "string" }, "text_on_brand": { "type": "string" }, "video_bg": { "type": "string" }, "warning": { "type": "string" } } }, "font_family": { "type": "string" }, "google_font": { "type": "string" }, "logo": { "type": "string", "format": "uri" }, "spacing_base": { "type": "number", "minimum": 1 }, "theme": { "type": "string", "enum": [ "darkest", "dark", "light" ] } } } } } }, "title": "UpdatePreset" }, "realtimekit_VideoConfig": { "type": "object", "properties": { "codec": { "description": "Codec using which the recording will be encoded.", "type": "string", "default": "H264", "enum": [ "H264", "VP8", "VP9" ] }, "export_file": { "description": "Controls whether to export video file seperately", "type": "boolean", "default": true }, "height": { "description": "Height of the recording video in pixels", "type": "integer", "example": 720, "default": 720, "maximum": 1920, "minimum": 1 }, "watermark": { "description": "Watermark to be added to the recording", "type": "object", "properties": { "position": { "description": "Position of the watermark", "type": "string", "default": "left top", "enum": [ "left top", "right top", "left bottom", "right bottom" ] }, "size": { "description": "Size of the watermark", "type": "object", "properties": { "height": { "description": "Height of the watermark in px", "type": "integer", "minimum": 1 }, "width": { "description": "Width of the watermark in px", "type": "integer", "minimum": 1 } } }, "url": { "description": "URL of the watermark image", "type": "string", "format": "uri" } } }, "width": { "description": "Width of the recording video in pixels", "type": "integer", "example": 1280, "default": 1280, "maximum": 1920, "minimum": 1 } }, "title": "VideoConfig" }, "realtimekit_VideoConsumerStats": { "description": "Per-sample inbound (consumer) video statistics.", "type": "object", "properties": { "bytes_received": { "type": "number" }, "consumer_id": { "type": "string" }, "fir_count": { "type": "number" }, "frame_height": { "type": "number" }, "frame_width": { "type": "number" }, "frames_decoded": { "type": "number" }, "frames_dropped": { "type": "number" }, "frames_per_second": { "type": "number" }, "jitter": { "type": "number" }, "jitter_buffer_delay": { "type": "number" }, "jitter_buffer_emitted_count": { "type": "number" }, "key_frames_decoded": { "type": "number" }, "mid": { "type": "string" }, "mos_quality": { "type": "number" }, "packets_lost": { "type": "number" }, "packets_received": { "type": "number" }, "peer_id": { "type": "string" }, "producer_id": { "type": "string" }, "ssrc": { "type": "number" }, "timestamp": { "type": "string" } } }, "realtimekit_VideoConsumerStatsCumulative": { "description": "Aggregated inbound (consumer) video statistics for the session.", "type": "object", "properties": { "frame_per_second": { "$ref": "#/components/schemas/realtimekit_PercentileStats" }, "frame_width": { "$ref": "#/components/schemas/realtimekit_PercentileStats" }, "issues": { "type": "object", "properties": { "lag_fraction": { "type": "number" }, "no_video_fraction": { "type": "number" }, "poor_resolution_fraction": { "type": "number" } } }, "jitter_buffer_delay": { "$ref": "#/components/schemas/realtimekit_LatencyCumulative" }, "key_frames_decoded_fraction": { "type": "number" }, "packet_loss": { "$ref": "#/components/schemas/realtimekit_PacketLossCumulative" }, "quality_mos": { "$ref": "#/components/schemas/realtimekit_PercentileStats" } } }, "realtimekit_VideoProducerStats": { "description": "Per-sample outbound (producer) video statistics.", "type": "object", "properties": { "bytes_sent": { "type": "number" }, "fir_count": { "type": "number" }, "frame_height": { "type": "number" }, "frame_width": { "type": "number" }, "frames_encoded": { "type": "number" }, "frames_per_second": { "type": "number" }, "jitter": { "type": "number" }, "key_frames_encoded": { "type": "number" }, "mid": { "type": "string" }, "mos_quality": { "type": "number" }, "packets_lost": { "type": "number" }, "packets_sent": { "type": "number" }, "pli_count": { "type": "number" }, "producer_id": { "type": "string" }, "quality_limitation_durations": { "type": "object", "properties": { "bandwidth": { "type": "number" }, "cpu": { "type": "number" }, "none": { "type": "number" }, "other": { "type": "number" } } }, "quality_limitation_reason": { "type": "string", "enum": [ "cpu", "bandwidth", "none", "other" ] }, "quality_limitation_resolution_changes": { "type": "number" }, "rtt": { "type": "number" }, "ssrc": { "type": "number" }, "timestamp": { "type": "string" } } }, "realtimekit_VideoProducerStatsCumulative": { "description": "Aggregated outbound (producer) video statistics for the session.", "type": "object", "properties": { "frame_per_second": { "$ref": "#/components/schemas/realtimekit_PercentileStats" }, "frame_width": { "$ref": "#/components/schemas/realtimekit_PercentileStats" }, "high_negative_feedback_fraction": { "type": "number" }, "issues": { "type": "object", "properties": { "bandwidth_quality_limitation_fraction": { "type": "number" }, "cpu_quality_limitation_fraction": { "type": "number" }, "no_video_fraction": { "type": "number" }, "poor_resolution_fraction": { "type": "number" }, "quality_limitation_fraction": { "type": "number" } } }, "key_frames_encoded_fraction": { "type": "number" }, "packet_loss": { "$ref": "#/components/schemas/realtimekit_PacketLossCumulative" }, "quality_mos": { "$ref": "#/components/schemas/realtimekit_PercentileStats" }, "rtt": { "$ref": "#/components/schemas/realtimekit_LatencyCumulative" } } }, "realtimekit_Webhook": { "type": "object", "properties": { "created_at": { "description": "Timestamp when this webhook was created", "type": "string", "format": "date-time", "example": "2022-05-28T07:01:53.075Z" }, "enabled": { "description": "Set to true if the webhook is active", "type": "boolean" }, "events": { "description": "Events this webhook will send updates for", "type": "array", "items": { "enum": [ "meeting.started", "meeting.ended", "meeting.participantJoined", "meeting.participantLeft", "meeting.chatSynced", "recording.statusUpdate", "livestreaming.statusUpdate", "meeting.transcript", "meeting.summary" ], "type": "string" }, "example": [ "meeting.started", "meeting.ended", "meeting.participantJoined", "meeting.participantLeft", "meeting.chatSynced", "recording.statusUpdate", "livestreaming.statusUpdate", "meeting.transcript", "meeting.summary" ] }, "id": { "description": "ID of the webhook", "type": "string", "format": "uuid", "example": "0d1f069d-43bb-489a-ad8c-7eb95592ba8e", "readOnly": true }, "name": { "description": "Name of the webhook", "type": "string", "example": "All events webhook" }, "updated_at": { "description": "Timestamp when this webhook was updated", "type": "string", "format": "date-time", "example": "2022-05-28T07:01:53.075Z" }, "url": { "description": "URL the webhook will send events to", "type": "string", "format": "uri", "example": "https://webhook.site/b23a5bbd-c7b0-4ced-a9e2-78ae7889897e" } }, "required": [ "id", "name", "url", "events", "created_at", "updated_at", "enabled" ] }, "realtimekit_WebhookEventsSuccessResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "enum": [ "meeting.started", "meeting.ended", "meeting.participantJoined", "meeting.participantLeft", "meeting.chatSynced", "recording.statusUpdate", "livestreaming.statusUpdate", "meeting.transcript", "meeting.summary" ], "type": "string" } }, "success": { "type": "boolean", "example": true } }, "required": [ "success", "data" ] }, "realtimekit_WebhookLog": { "type": "object", "properties": { "event": { "description": "Webhook event name.", "type": "string" }, "headers": { "description": "Headers sent with the webhook delivery attempt.", "type": "object", "additionalProperties": { "type": "string" } }, "id": { "description": "ID of the webhook delivery log.", "type": "string" }, "payload": { "description": "Webhook delivery payload.", "type": "object", "additionalProperties": true }, "status_code": { "description": "HTTP status code returned by the webhook endpoint.", "type": "integer" }, "timestamp": { "description": "Timestamp for the webhook delivery attempt.", "type": "string", "format": "date-time" } } }, "realtimekit_WebhookRequest": { "type": "object", "properties": { "enabled": { "description": "Set whether or not the webhook should be active when created", "type": "boolean", "default": true }, "events": { "description": "Events that this webhook will get triggered by", "type": "array", "items": { "enum": [ "meeting.started", "meeting.ended", "meeting.participantJoined", "meeting.participantLeft", "meeting.chatSynced", "recording.statusUpdate", "livestreaming.statusUpdate", "meeting.transcript", "meeting.summary" ], "type": "string" }, "example": [ "meeting.started", "meeting.ended", "meeting.participantJoined", "meeting.participantLeft", "meeting.chatSynced", "recording.statusUpdate", "livestreaming.statusUpdate", "meeting.transcript", "meeting.summary" ] }, "name": { "description": "Name of the webhook", "type": "string", "example": "All events webhook" }, "url": { "description": "URL this webhook will send events to", "type": "string", "format": "uri", "example": "https://webhook.site/b23a5bbd-c7b0-4ced-a9e2-78ae7889897e" } }, "required": [ "name", "url", "events" ] }, "realtimekit_WebhookSuccessResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/realtimekit_Webhook" }, "success": { "type": "boolean", "example": true } }, "required": [ "success", "data" ] }, "realtimekit_WebhooksListSuccessResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_Webhook" } }, "success": { "type": "boolean", "example": true } }, "required": [ "success", "data" ] }, "realtimekit_account_identifier": { "description": "The account identifier tag.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "realtimekit_app_id": { "description": "The app identifier tag.", "type": "string", "example": "14a396e7-ca44-4937-bf1f-050a69118543", "maxLength": 32 }, "realtimekit_created": { "description": "The date and time the item was created.", "type": "string", "format": "date-time", "example": "2025-01-02T02:20:00Z" }, "realtimekit_identifier": { "description": "A Cloudflare-generated unique identifier for a item.", "type": "string", "example": "2a95132c15732412d22c1476fa83f27a", "maxLength": 32, "minLength": 32, "x-auditable": true }, "realtimekit_modified": { "description": "The date and time the item was last modified.", "type": "string", "format": "date-time", "example": "2025-01-02T02:20:00Z" }, "realtimekit_realtimekitBucketConfig": { "type": "object", "properties": { "enabled": { "description": "Controls whether recordings are uploaded to RealtimeKit's bucket. If set to false, `download_url`, `audio_download_url`, `download_url_expiry` won't be generated for a recording.", "type": "boolean" } }, "required": [ "enabled" ], "title": "realtimekitBucketConfig" }, "realtimekit_secret": { "description": "Bearer token", "type": "string", "example": "66bcf64aa8907b9f9d90ac17746a77ce394c393b92b3916633dc02846e608ad4", "maxLength": 64, "minLength": 64, "x-sensitive": true }, "realtimekit_startReason": { "type": "object", "properties": { "caller": { "type": "object", "properties": { "name": { "description": "Name of the user who started the recording.", "type": "string", "example": "RealtimeKit_test" }, "type": { "description": "The type can be an App or a user. If the type is `user`, then only the `user_Id` and `name` are returned.", "type": "string", "enum": [ "ORGANIZATION", "USER" ] }, "user_Id": { "description": "The user ID of the person who started the recording.", "type": "string", "format": "uuid", "example": "d61f6956-e68f-4375-bf10-c38a704d1bec" } } }, "reason": { "description": "Specifies if the recording was started using the \"Start a Recording\"API or using the parameter RECORD_ON_START in the \"Create a meeting\" API. \n\nIf the recording is initiated using the \"RECORD_ON_START\" parameter, the user details will not be populated.", "type": "string", "enum": [ "API_CALL", "RECORD_ON_START" ] } }, "title": "startReason" }, "realtimekit_stopReason": { "type": "object", "properties": { "caller": { "type": "object", "properties": { "name": { "description": "Name of the user who stopped the recording.", "type": "string", "example": "RealtimeKit_test" }, "type": { "description": "The type can be an App or a user. If the type is `user`, then only the `user_Id` and `name` are returned.", "type": "string", "enum": [ "ORGANIZATION", "USER" ] }, "user_Id": { "description": "The user ID of the person who stopped the recording.", "type": "string", "format": "uuid", "example": "d61f6956-e68f-4375-bf10-c38a704d1bec" } } }, "reason": { "description": "Specifies the reason why the recording stopped.", "type": "string", "enum": [ "API_CALL", "INTERNAL_ERROR", "ALL_PEERS_LEFT" ] } }, "title": "stopReason" }, "realtimekit_success": { "type": "boolean" }, "registrar-api-sandbox_address": { "description": "Address.", "type": "string", "example": "123 Sesame St." }, "registrar-api-sandbox_address2": { "description": "Optional address line for unit, floor, suite, etc.", "type": "string", "example": "Suite 430" }, "registrar-api-sandbox_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "type": "object" }, "nullable": true }, "result_info": { "$ref": "#/components/schemas/registrar-api-sandbox_result_info" } }, "type": "object" } ] }, "registrar-api-sandbox_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/registrar-api-sandbox_messages" }, "messages": { "$ref": "#/components/schemas/registrar-api-sandbox_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": { "type": "object" }, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "registrar-api-sandbox_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_messages" } ], "minItems": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "registrar-api-sandbox_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_api-response-common" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, "registrar-api-sandbox_auto_renew": { "description": "Auto-renew controls whether subscription is automatically renewed upon domain expiration.", "type": "boolean", "example": true, "x-auditable": true }, "registrar-api-sandbox_available": { "description": "Shows if a domain is available for transferring into Cloudflare Registrar.", "type": "boolean", "example": false }, "registrar-api-sandbox_can_register": { "description": "Indicates eligibility to register the domain as a new domain.", "type": "boolean", "example": false }, "registrar-api-sandbox_city": { "description": "City.", "type": "string", "example": "Austin" }, "registrar-api-sandbox_contact_identifier": { "description": "Contact Identifier.", "type": "string", "example": "ea95132c15732412d22c1476fa83f27a", "maxLength": 32, "readOnly": true }, "registrar-api-sandbox_contact_properties": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/registrar-api-sandbox_address" }, "address2": { "$ref": "#/components/schemas/registrar-api-sandbox_address2" }, "city": { "$ref": "#/components/schemas/registrar-api-sandbox_city" }, "country": { "$ref": "#/components/schemas/registrar-api-sandbox_country" }, "email": { "$ref": "#/components/schemas/registrar-api-sandbox_email" }, "fax": { "$ref": "#/components/schemas/registrar-api-sandbox_fax" }, "first_name": { "$ref": "#/components/schemas/registrar-api-sandbox_first_name" }, "id": { "$ref": "#/components/schemas/registrar-api-sandbox_contact_identifier" }, "last_name": { "$ref": "#/components/schemas/registrar-api-sandbox_last_name" }, "organization": { "$ref": "#/components/schemas/registrar-api-sandbox_organization" }, "phone": { "$ref": "#/components/schemas/registrar-api-sandbox_telephone" }, "state": { "$ref": "#/components/schemas/registrar-api-sandbox_state" }, "zip": { "$ref": "#/components/schemas/registrar-api-sandbox_zipcode" } }, "required": [ "first_name", "last_name", "address", "city", "state", "zip", "country", "phone", "organization" ] }, "registrar-api-sandbox_contacts": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_contact_properties" } ] }, "registrar-api-sandbox_country": { "description": "The country in which the user lives.", "type": "string", "example": "US", "maxLength": 30, "nullable": true }, "registrar-api-sandbox_created_at": { "description": "Shows time of creation.", "type": "string", "format": "date-time", "example": "2018-08-28T17:26:26Z" }, "registrar-api-sandbox_current_registrar": { "description": "Shows name of current registrar.", "type": "string", "example": "Cloudflare" }, "registrar-api-sandbox_cursor_result_info": { "description": "Provides cursor-based pagination metadata. List endpoints use this\nmetadata for cursor pagination. Pass the `cursor` value as a query\nparameter in the next request to fetch the next page. An empty string\nindicates the end of pagination.\n", "type": "object", "properties": { "count": { "description": "Number of items in the current result set.", "type": "integer", "example": 20 }, "cursor": { "description": "Opaque cursor for fetching the next page. Pass this value as the\n`cursor` query parameter in a subsequent request. An empty string\nindicates the end of pagination.\n", "type": "string", "example": "eyJ0IjoiMjAyNS0wNi0xNVQxMjowMDowMC4wMDAwMDBaIiwibiI6ImJyYXZvLm5ldCJ9" }, "per_page": { "description": "Maximum number of items per page.", "type": "integer", "example": 20 } }, "required": [ "cursor", "per_page", "count" ] }, "registrar-api-sandbox_domain_check_request": { "description": "Request body for checking domain availability.", "type": "object", "properties": { "domains": { "description": "List of fully qualified domain names (FQDNs) to check for availability. Each domain must include the extension.\n- Minimum: 1 domain.\n- Maximum: 20 domains per request.\n- The response returns domains on unsupported extensions with `registrable: false` and a `reason` field.\n- The response may omit malformed domain names (e.g., names missing an extension).\n", "type": "array", "items": { "type": "string" }, "example": [ "example.com", "example.net" ], "maxItems": 20, "minItems": 1 } }, "required": [ "domains" ] }, "registrar-api-sandbox_domain_check_response": { "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_api-response-common" }, { "properties": { "result": { "description": "Contains the availability check results.", "type": "object", "properties": { "domains": { "description": "Array of domain availability results. Results for unsupported\nextensions contain `registrable: false` and a `reason`\nfield. The response may omit malformed domain names.\n", "type": "array", "items": { "$ref": "#/components/schemas/registrar-api-sandbox_domain_check_result" } } }, "required": [ "domains" ] } }, "required": [ "result" ], "type": "object" } ] }, "registrar-api-sandbox_domain_check_result": { "description": "Describes a single authoritative domain availability result from the Check endpoint. Check results reflect current registry status; use them immediately before registration.", "type": "object", "properties": { "name": { "description": "The fully qualified domain name (FQDN) in punycode format for internationalized domain names (IDNs).", "type": "string", "example": "example.com" }, "pricing": { "$ref": "#/components/schemas/registrar-api-sandbox_pricing" }, "reason": { "description": "Appears only when `registrable` is `false` and explains the result.\n- `extension_not_supported_via_api`: Cloudflare Registrar supports this extension in the dashboard but currently excludes it from programmatic registration through this API. The user can register via `https://dash.cloudflare.com/{account_id}/domains/registrations`.\n- `extension_not_supported`: Cloudflare Registrar excludes this extension entirely.\n- `extension_disallows_registration`: The extension's registry temporarily or permanently freezes new registrations. Registrars currently cannot register domains on this extension.\n- `domain_premium`: The domain carries premium pricing. This API currently supports standard registrations only.\n- `domain_unavailable`: An existing registration, reservation, or other registry restriction makes the domain unavailable on a supported extension.", "type": "string", "example": "domain_unavailable", "enum": [ "extension_not_supported_via_api", "extension_not_supported", "extension_disallows_registration", "domain_premium", "domain_unavailable" ] }, "registrable": { "description": "Indicates programmatic registration eligibility according to a real-time registry check.\n- `true`: The domain is available for registration. The response includes the `pricing` object.\n- `false`: A restriction prevents registration. See the `reason` field for details. Some results, such as premium domains, may still include `tier`.", "type": "boolean", "example": true }, "tier": { "description": "The pricing tier for this domain. A `registrable` value of `true` always includes this field, which defaults to `standard` for most domains. A `registrable` value of `false` may omit it.\n- `standard`: Standard registry pricing.\n- `premium`: Premium domain with higher pricing from the registry.", "type": "string", "example": "standard", "enum": [ "standard", "premium" ] } }, "required": [ "name", "registrable" ] }, "registrar-api-sandbox_domain_identifier": { "description": "Domain identifier.", "type": "string", "example": "ea95132c15732412d22c1476fa83f27a", "maxLength": 32, "readOnly": true }, "registrar-api-sandbox_domain_name": { "description": "Provides a fully qualified domain name (FQDN), including the extension\n(e.g., `example.com`, `mybrand.app`). The domain name uniquely identifies\na registration. Cloudflare permits only one registration per domain, making\nthe domain name a natural idempotency key for registration requests.\n", "type": "string", "example": "example.com", "x-auditable": true }, "registrar-api-sandbox_domain_properties": { "type": "object", "properties": { "available": { "$ref": "#/components/schemas/registrar-api-sandbox_available" }, "can_register": { "$ref": "#/components/schemas/registrar-api-sandbox_can_register" }, "created_at": { "$ref": "#/components/schemas/registrar-api-sandbox_created_at" }, "current_registrar": { "$ref": "#/components/schemas/registrar-api-sandbox_current_registrar" }, "expires_at": { "$ref": "#/components/schemas/registrar-api-sandbox_expires_at" }, "id": { "$ref": "#/components/schemas/registrar-api-sandbox_domain_identifier" }, "locked": { "$ref": "#/components/schemas/registrar-api-sandbox_locked" }, "registrant_contact": { "$ref": "#/components/schemas/registrar-api-sandbox_registrant_contact" }, "registry_statuses": { "$ref": "#/components/schemas/registrar-api-sandbox_registry_statuses" }, "supported_tld": { "$ref": "#/components/schemas/registrar-api-sandbox_supported_tld" }, "transfer_in": { "$ref": "#/components/schemas/registrar-api-sandbox_transfer_in" }, "updated_at": { "$ref": "#/components/schemas/registrar-api-sandbox_updated_at" } } }, "registrar-api-sandbox_domain_response_collection": { "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/registrar-api-sandbox_domains" } } }, "type": "object" } ] }, "registrar-api-sandbox_domain_response_single": { "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_api-response-single" }, { "properties": { "result": { "type": "object" } }, "type": "object" } ] }, "registrar-api-sandbox_domain_search_response": { "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_api-response-common" }, { "properties": { "result": { "description": "Contains the search results.", "type": "object", "properties": { "domains": { "description": "Lists domain suggestions in relevance order. An empty array indicates that the search criteria matched zero domains.", "type": "array", "items": { "$ref": "#/components/schemas/registrar-api-sandbox_domain_search_result" } } }, "required": [ "domains" ] } }, "required": [ "result" ], "type": "object" } ] }, "registrar-api-sandbox_domain_search_result": { "description": "Describes a single domain suggestion from the Search endpoint. Search results use non-authoritative data that may come from a cache. Use POST /domain-check to confirm real-time availability and pricing before registration.", "type": "object", "properties": { "name": { "description": "The fully qualified domain name (FQDN) in punycode format for internationalized domain names (IDNs).", "type": "string", "example": "example.com" }, "pricing": { "$ref": "#/components/schemas/registrar-api-sandbox_pricing" }, "reason": { "description": "Appears only when `registrable` is `false` and explains the advisory search result. Use POST /domain-check for authoritative status.\n- `extension_not_supported_via_api`: Cloudflare Registrar supports this extension in the dashboard but currently excludes it from programmatic registration through this API.\n- `extension_not_supported`: Cloudflare Registrar excludes this extension entirely.\n- `extension_disallows_registration`: The extension's registry temporarily or permanently freezes new registrations.\n- `domain_premium`: The domain carries premium pricing. This API currently supports standard registrations only.\n- `domain_unavailable`: The domain appears unavailable.", "type": "string", "example": "domain_unavailable", "enum": [ "extension_not_supported_via_api", "extension_not_supported", "extension_disallows_registration", "domain_premium", "domain_unavailable" ] }, "registrable": { "description": "Indicates domain availability according to potentially stale, non-authoritative search data.\n- `true`: The domain appears available. Use POST /domain-check to confirm before registration.\n- `false`: Search results mark the domain ineligible for registration through this API. See `reason` for details.", "type": "boolean", "example": true }, "tier": { "description": "The pricing tier for this domain.\nA `registrable` value of `true` always\nincludes this field, which defaults to `standard` for most domains. A\n`registrable` value of `false` may omit it.\n- `standard`: Standard registry pricing.\n- `premium`: Premium domain with higher pricing from the registry.\n", "type": "string", "example": "standard", "enum": [ "standard", "premium" ] } }, "required": [ "name", "registrable" ] }, "registrar-api-sandbox_domain_update_properties": { "type": "object", "properties": { "auto_renew": { "$ref": "#/components/schemas/registrar-api-sandbox_auto_renew" }, "locked": { "$ref": "#/components/schemas/registrar-api-sandbox_locked" }, "privacy": { "$ref": "#/components/schemas/registrar-api-sandbox_privacy" } } }, "registrar-api-sandbox_domains": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_domain_properties" } ] }, "registrar-api-sandbox_email": { "description": "The contact email address of the user.", "type": "string", "example": "user@example.com", "maxLength": 90 }, "registrar-api-sandbox_expires_at": { "description": "Shows when domain name registration expires.", "type": "string", "format": "date-time", "example": "2019-08-28T23:59:59Z" }, "registrar-api-sandbox_extension-item": { "description": "Extension entry with metadata and JSON Schema documents for the registration operation.", "type": "object", "properties": { "metadata": { "description": "Extension metadata.", "type": "object", "properties": { "name": { "description": "The full name of the extension. For example, \"co.uk\", or \"uk\".", "type": "string" }, "tld": { "description": "The TLD of the extension. For example, for \"co.uk\", it is \"uk\". For \"uk\", it is \"uk\".", "type": "string" } }, "required": [ "name", "tld" ] }, "registration_schema": { "description": "JSON Schema describing the expected input structure for registration operations on this extension.", "type": "object" } }, "required": [ "metadata", "registration_schema" ] }, "registrar-api-sandbox_extension-response-collection": { "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/registrar-api-sandbox_extension-item" } }, "result_info": { "description": "Cursor-based pagination metadata.", "type": "object", "properties": { "count": { "description": "Number of items in the current result set.", "type": "integer" }, "cursor": { "description": "Opaque token for the next page. Empty string when no more pages.", "type": "string" }, "per_page": { "description": "Number of items per page.", "type": "integer" } } } }, "type": "object" } ] }, "registrar-api-sandbox_extension-response-single": { "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/registrar-api-sandbox_extension-item" } }, "type": "object" } ] }, "registrar-api-sandbox_fax": { "description": "Contact fax number.", "type": "string", "example": "123-867-5309" }, "registrar-api-sandbox_first_name": { "description": "User's first name.", "type": "string", "example": "John", "maxLength": 60, "nullable": true }, "registrar-api-sandbox_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "registrar-api-sandbox_last_name": { "description": "User's last name.", "type": "string", "example": "Appleseed", "maxLength": 60, "nullable": true }, "registrar-api-sandbox_locked": { "description": "Shows whether a registrar lock is in place for a domain.", "type": "boolean", "example": false, "x-auditable": true }, "registrar-api-sandbox_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" }, "source": { "description": "Location of the invalid value that caused the error.", "type": "object", "properties": { "pointer": { "description": "JSON Pointer to the invalid or missing request value.", "type": "string" } }, "required": [ "pointer" ] } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "registrar-api-sandbox_organization": { "description": "Name of organization.", "type": "string", "example": "Cloudflare, Inc." }, "registrar-api-sandbox_pricing": { "description": "Provides annual pricing information for a registrable domain. This object\nappears only when `registrable` is `true`. The API returns all per-year\nprices as strings to preserve decimal precision.\n\n`registration_cost` and `renewal_cost` frequently have the same value, but\nmay differ, especially when registries set different premium rates for\ninitial registration and renewal. For a multi-year registration (e.g., 4\nyears), `registration_cost` applies to the first year and `renewal_cost`\napplies to each subsequent year. The values reflect the current registry\nrate, which may change over time. Search and Check may surface premium\npricing, but this API currently supports standard registrations only.\n", "type": "object", "properties": { "currency": { "description": "ISO-4217 currency code for the prices (e.g., \"USD\", \"EUR\", \"GBP\").", "type": "string", "example": "USD" }, "registration_cost": { "description": "The first-year cost to register this domain. For premium domains\n(`tier: premium`), the registry sets this price, which may significantly\nexceed standard pricing. For multi-year registrations, this cost applies\nto the first year only; `renewal_cost` applies to subsequent years.\n", "type": "string", "example": "8.57" }, "renewal_cost": { "description": "Per-year renewal cost for this domain. Applied to each year beyond\nthe first year of a multi-year registration, and to each annual\nauto-renewal thereafter. May differ from `registration_cost`,\nespecially for premium domains where initial registration often\ncosts more than renewals.\n", "type": "string", "example": "8.57" } }, "required": [ "currency", "registration_cost", "renewal_cost" ] }, "registrar-api-sandbox_privacy": { "description": "Privacy option controls redacting WHOIS information.", "type": "boolean", "example": true, "x-auditable": true }, "registrar-api-sandbox_registrant_contact": { "description": "Shows contact information for domain registrant.", "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_contacts" } ] }, "registrar-api-sandbox_registration": { "description": "A domain registration resource representing the current state of a registered domain.", "type": "object", "properties": { "auto_renew": { "description": "Whether automatic renewal occurs before expiration.", "type": "boolean", "example": true }, "created_at": { "description": "When the domain was registered. Present when the registration resource exists.", "type": "string", "format": "date-time", "example": "2025-01-15T10:00:00Z" }, "domain_name": { "$ref": "#/components/schemas/registrar-api-sandbox_domain_name" }, "expires_at": { "description": "When the domain registration expires. Ready registrations include this value; only `registration_pending` may return null.", "type": "string", "format": "date-time", "example": "2026-01-15T10:00:00Z", "nullable": true }, "locked": { "description": "Whether the domain is locked for transfer.", "type": "boolean", "example": true }, "privacy_mode": { "description": "Current WHOIS privacy mode for the registration.", "type": "string", "example": "redaction", "enum": [ "off", "redaction" ] }, "status": { "description": "Current registration status.\n- `active`: The domain operates with an active registration.\n- `registration_pending`: Registration remains in progress.\n- `expired`: The domain registration expired.\n- `suspended`: The registry suspended the domain.\n- `redemption_period`: The domain entered the redemption grace period.\n- `pending_delete`: The registry scheduled the domain for deletion.\n", "type": "string", "example": "active", "enum": [ "active", "registration_pending", "expired", "suspended", "redemption_period", "pending_delete" ] } }, "required": [ "domain_name", "status", "created_at", "expires_at", "auto_renew", "privacy_mode", "locked" ] }, "registrar-api-sandbox_registration-response-collection": { "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/registrar-api-sandbox_registration" } }, "result_info": { "$ref": "#/components/schemas/registrar-api-sandbox_cursor_result_info" } }, "required": [ "result", "result_info" ], "type": "object" } ] }, "registrar-api-sandbox_registration-response-single": { "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/registrar-api-sandbox_registration" } }, "type": "object" } ] }, "registrar-api-sandbox_registration_contact": { "description": "Contact data for the domain registration. This information\nis submitted to the domain registry and, depending on extension and\nprivacy settings, may appear in public WHOIS records.\n", "type": "object", "properties": { "email": { "description": "Email address for the registrant. Used for domain-related\ncommunications from the registry, including ownership verification\nand renewal notices.\n", "type": "string", "format": "email", "example": "ada@example.com" }, "fax": { "description": "Fax number in E.164 format (e.g., `+1.5555555555`). Optional.\nMost registrations do not require a fax number.\n", "type": "string", "example": "+1.5555555555" }, "phone": { "description": "Phone number in E.164 format: `+{country_code}.{number}` without spaces or dashes. Examples: `+1.5555555555` (US), `+44.2071234567` (UK), `+81.312345678` (Japan).", "type": "string", "example": "+1.5555555555" }, "postal_info": { "$ref": "#/components/schemas/registrar-api-sandbox_registration_contact_postal_info" } }, "required": [ "phone", "email", "postal_info" ] }, "registrar-api-sandbox_registration_contact_address": { "description": "Physical mailing address for the registrant contact.", "type": "object", "properties": { "city": { "description": "City or locality name.", "type": "string", "example": "Austin" }, "country_code": { "description": "Two-letter country code per ISO 3166-1 alpha-2 (e.g., `US`, `GB`, `CA`, `DE`).", "type": "string", "example": "US" }, "postal_code": { "description": "Postal or ZIP code.", "type": "string", "example": "78701" }, "state": { "description": "State, province, or region. Use the standard abbreviation where applicable (e.g., `TX` for Texas, `ON` for Ontario).", "type": "string", "example": "TX" }, "street": { "description": "Street address including building/suite number.", "type": "string", "example": "123 Main St" } }, "required": [ "street", "city", "state", "postal_code", "country_code" ] }, "registrar-api-sandbox_registration_contact_postal_info": { "description": "Postal/mailing information for the contact. The `name` field is the\ncomplete contact name in one string. Some registries require a complete\npersonal name, including a family or last name where applicable, but this\nAPI does not accept separate first-name and last-name fields for\nregistration contacts.\n", "type": "object", "properties": { "address": { "$ref": "#/components/schemas/registrar-api-sandbox_registration_contact_address" }, "name": { "description": "Full legal name of the contact, including all required name components for an individual or authorized representative. Some registries require a complete personal name that includes a family or last name where applicable. Provide the complete name in this single field, for example `Ada Lovelace`; do not send separate first-name or last-name fields.", "type": "string", "example": "Ada Lovelace" }, "organization": { "description": "Organization or company name. Optional for individual registrants.", "type": "string", "example": "Example Inc" } }, "required": [ "name", "address" ] }, "registrar-api-sandbox_registration_contacts": { "description": "Provides contact data for the registration request.\n\nThe per-extension schema from\n`GET /accounts/{account_id}/registrar/extensions/{extension}` defines the\naccepted contact roles. Every currently supported extension requires only\n`contacts.registrant` from API callers. Callers may provide additional roles\nsuch as `technical`, `administrator`, and `billing` when the extension\nschema includes them. When a registry requires an omitted role, Cloudflare\nmay derive that contact from `contacts.registrant`.\n\nWhen the request omits either the entire `contacts` object or\n`contacts.registrant`, the system uses the account's default address book\nentry as the registrant contact. The account owner must configure this\ndefault at `https://dash.cloudflare.com/{account_id}/domains/registrations`,\nwhere they can create or update the address book entry and accept the\nrequired agreement. Dashboard settings currently provide the only way to\nmanage address book entries.\n\nWithout either a default address book entry or a registrant contact, the\nregistration request fails validation.\n", "type": "object", "properties": { "administrator": { "description": "Optional administrator contact. Accepted only when the extension\nschema includes this role. When the registry requires an omitted\ncontact, Cloudflare may derive it from `contacts.registrant`.\n", "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_registration_contact" } ] }, "billing": { "description": "Optional billing contact. Accepted only when the extension schema\nincludes this role. When the registry requires an omitted contact,\nCloudflare may derive it from `contacts.registrant`.\n", "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_registration_contact" } ] }, "registrant": { "description": "Optional registrant contact. If omitted, the account's default\naddress book entry is used instead.\n", "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_registration_contact" } ] }, "technical": { "description": "Optional technical contact. Accepted only when the extension schema\nincludes this role. When the registry requires an omitted contact,\nCloudflare may derive it from `contacts.registrant`.\n", "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_registration_contact" } ] } } }, "registrar-api-sandbox_registration_create_request": { "type": "object", "properties": { "acknowledgements": { "description": "Provides user acknowledgements for a specific extension or premium\nregistration flow. The extension registration schema from the\nextension discovery endpoint identifies the required keys.\n", "type": "object", "example": { "fees": { "currency": "USD", "registration_fee": 10, "renewal_fee": 10 } }, "additionalProperties": true }, "auto_renew": { "description": "Enable or disable automatic renewal. Defaults to `false` if omitted.\nSetting this field to `true` is an explicit opt-in authorizing\nCloudflare to charge the account's default payment method up to 30\ndays before domain expiry to renew the domain automatically.\nRenewal pricing may change over time based on registry pricing.\n", "type": "boolean", "example": false, "default": false }, "contact_extensions": { "description": "Provides registry-specific contact extension values for the registrant.\n`GET /accounts/{account_id}/registrar/extensions/{extension}` identifies\nthe required keys and allowed values for each extension in the\n`registration_schema.properties.contact_extensions` object.\n\nExamples include `.us` nexus fields, `.uk` registrant type fields,\nand `.ca` legal type fields. Omit this object when the extension's\nregistration schema excludes `contact_extensions`.\n", "type": "object", "example": { "application_purpose": "P3", "nexus_category": "C11" }, "additionalProperties": true }, "contacts": { "$ref": "#/components/schemas/registrar-api-sandbox_registration_contacts" }, "domain_name": { "$ref": "#/components/schemas/registrar-api-sandbox_domain_name" }, "privacy_mode": { "description": "Sets the WHOIS privacy mode for the registration. Defaults to `redaction`.\n- `off`: Disables WHOIS privacy.\n- `redaction`: Requests WHOIS redaction where the extension supports it.\n Some extensions exclude privacy and redaction.\n", "type": "string", "example": "redaction", "default": "redaction", "enum": [ "off", "redaction" ] }, "years": { "description": "Sets the registration term from 1 to 10 years. When omitted, this\nfield defaults to the registry's minimum registration period for the\nextension. Most extensions require 1 year, while some require longer\nminimum terms (e.g., `.ai` requires 2 years).\n\nEach registry may also enforce its own maximum registration term. A\nrequest above that maximum fails. When uncertain, omit this field to\nuse the default.\n", "type": "integer", "example": 1, "maximum": 10, "minimum": 1 } }, "required": [ "domain_name" ] }, "registrar-api-sandbox_registration_update_request": { "description": "Request to update an existing domain registration.\n\nThis endpoint currently supports updating `auto_renew` only.\n", "type": "object", "properties": { "auto_renew": { "description": "Enable or disable automatic renewal.\nSetting this field to `true` authorizes Cloudflare to charge the\naccount's default payment method up to 30 days before domain expiry\nto renew the domain automatically. Renewal pricing may change over\ntime based on registry pricing.\n", "type": "boolean", "example": true } }, "minProperties": 1 }, "registrar-api-sandbox_registry_statuses": { "description": "A comma-separated list of registry status codes. Refer to [EPP Status Codes](https://www.icann.org/resources/pages/epp-status-codes-2014-06-16-en) for the full list.", "type": "string", "example": "ok,serverTransferProhibited" }, "registrar-api-sandbox_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 } } }, "registrar-api-sandbox_state": { "description": "State.", "type": "string", "example": "TX" }, "registrar-api-sandbox_supported_tld": { "description": "Indicates whether Cloudflare Registrar currently supports a particular TLD. Refer to [TLD Policies](https://www.cloudflare.com/tld-policies/) for a list of supported TLDs.", "type": "boolean", "example": true }, "registrar-api-sandbox_telephone": { "description": "User's telephone number.", "type": "string", "example": "+1 123-123-1234", "maxLength": 20, "nullable": true }, "registrar-api-sandbox_transfer_in": { "description": "Statuses for domain transfers into Cloudflare Registrar.", "properties": { "accept_foa": { "description": "Status of the registrant authorization step.", "type": "string", "example": "needed", "enum": [ "needed", "ok" ] }, "approve_transfer": { "description": "Status of the registry transfer-approval step.", "type": "string", "example": "unknown", "enum": [ "needed", "ok", "pending", "trying", "rejected", "unknown" ] }, "can_cancel_transfer": { "description": "Indicates if cancellation is still possible.", "type": "boolean", "example": true }, "disable_privacy": { "description": "Status of the privacy-guard disabling step at the foreign registrar.", "type": "string", "example": "ok", "enum": [ "needed", "ok", "unknown" ] }, "enter_auth_code": { "description": "Status of the auth-code entry and verification step.", "type": "string", "example": "needed", "enum": [ "needed", "ok", "pending", "trying", "rejected" ] }, "unlock_domain": { "description": "Status of the domain-unlock step at the foreign registrar.", "type": "string", "example": "ok", "enum": [ "needed", "ok", "pending", "trying", "unknown" ] } } }, "registrar-api-sandbox_updated_at": { "description": "Last updated.", "type": "string", "format": "date-time", "example": "2018-08-28T17:26:26Z" }, "registrar-api-sandbox_workflow-status-response-single": { "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/registrar-api-sandbox_workflow_status" } }, "type": "object" } ] }, "registrar-api-sandbox_workflow_error": { "description": "Provides error details when a workflow reaches the `failed` state. The workflow type (registration, update, etc.) and underlying registry response determine the specific codes and messages. Workflow error codes differ from immediate HTTP error `errors[].code` values in non-2xx responses. Surface `error.message` to the user for context.", "type": "object", "properties": { "code": { "description": "Machine-readable error code identifying the failure reason.", "type": "string", "example": "registry_rejected" }, "message": { "description": "Human-readable explanation of the failure. May include registry-specific details.", "type": "string", "example": "Registry rejected the request." } }, "required": [ "code", "message" ] }, "registrar-api-sandbox_workflow_links": { "type": "object", "properties": { "resource": { "description": "URL to the domain resource.", "type": "string", "example": "/accounts/{account_id}/registrar/registrations/example.com" }, "self": { "description": "URL to this status resource.", "type": "string", "example": "/accounts/{account_id}/registrar/registrations/example.com/registration-status" } }, "required": [ "self" ] }, "registrar-api-sandbox_workflow_status": { "description": "Status of an async registration workflow.", "type": "object", "properties": { "completed": { "description": "Indicates whether the workflow reached a terminal state. A `succeeded` or `failed` state returns `true`; `pending`, `in_progress`, `action_required`, and `blocked` return `false`.", "type": "boolean", "example": false }, "context": { "description": "Provides workflow-specific data.\n\nFor domain-centric workflows, `context.domain_name` identifies the\nworkflow subject.\n", "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "error": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/registrar-api-sandbox_workflow_error" } ], "nullable": true }, "links": { "$ref": "#/components/schemas/registrar-api-sandbox_workflow_links" }, "state": { "description": "Describes the workflow lifecycle state.\n- `pending`: The workflow awaits processing.\n- `in_progress`: Processing started. Continue polling `links.self`.\n An internal deadline limits the duration of this state.\n- `action_required`: The workflow pauses for user action. See\n `context.action` for details. Stop automated polling until the user\n completes the required action.\n- `blocked`: A third party, such as the domain extension's registry or\n a losing registrar, prevents progress. Continue polling because the\n block may resolve when the third party responds.\n- `succeeded`: Terminal state. The operation completed successfully.\n `completed` equals `true`. For registrations,\n `context.registration` contains the resulting registration resource.\n- `failed`: Terminal state. The operation failed. `completed` equals\n `true`. See `error.code` and `error.message` for the reason. Require\n user review before retrying.\n", "type": "string", "example": "in_progress", "enum": [ "pending", "in_progress", "action_required", "blocked", "succeeded", "failed" ] }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "state", "completed", "created_at", "updated_at", "links" ] }, "registrar-api-sandbox_zipcode": { "description": "The zipcode or postal code where the user lives.", "type": "string", "example": "12345", "maxLength": 20, "nullable": true }, "registrar-api_address": { "description": "Address.", "type": "string", "example": "123 Sesame St." }, "registrar-api_address2": { "description": "Optional address line for unit, floor, suite, etc.", "type": "string", "example": "Suite 430" }, "registrar-api_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/registrar-api_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "type": "object" }, "nullable": true }, "result_info": { "$ref": "#/components/schemas/registrar-api_result_info" } }, "type": "object" } ] }, "registrar-api_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/registrar-api_messages" }, "messages": { "$ref": "#/components/schemas/registrar-api_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": { "type": "object" }, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "registrar-api_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/registrar-api_messages" } ], "minItems": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/registrar-api_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "registrar-api_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/registrar-api_api-response-common" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, "registrar-api_auto_renew": { "description": "Auto-renew controls whether subscription is automatically renewed upon domain expiration.", "type": "boolean", "example": true, "x-auditable": true }, "registrar-api_available": { "description": "Shows if a domain is available for transferring into Cloudflare Registrar.", "type": "boolean", "example": false }, "registrar-api_can_register": { "description": "Indicates eligibility to register the domain as a new domain.", "type": "boolean", "example": false }, "registrar-api_city": { "description": "City.", "type": "string", "example": "Austin" }, "registrar-api_contact_identifier": { "description": "Contact Identifier.", "type": "string", "example": "ea95132c15732412d22c1476fa83f27a", "maxLength": 32, "readOnly": true }, "registrar-api_contact_properties": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/registrar-api_address" }, "address2": { "$ref": "#/components/schemas/registrar-api_address2" }, "city": { "$ref": "#/components/schemas/registrar-api_city" }, "country": { "$ref": "#/components/schemas/registrar-api_country" }, "email": { "$ref": "#/components/schemas/registrar-api_email" }, "fax": { "$ref": "#/components/schemas/registrar-api_fax" }, "first_name": { "$ref": "#/components/schemas/registrar-api_first_name" }, "id": { "$ref": "#/components/schemas/registrar-api_contact_identifier" }, "last_name": { "$ref": "#/components/schemas/registrar-api_last_name" }, "organization": { "$ref": "#/components/schemas/registrar-api_organization" }, "phone": { "$ref": "#/components/schemas/registrar-api_telephone" }, "state": { "$ref": "#/components/schemas/registrar-api_state" }, "zip": { "$ref": "#/components/schemas/registrar-api_zipcode" } }, "required": [ "first_name", "last_name", "address", "city", "state", "zip", "country", "phone", "organization" ] }, "registrar-api_contacts": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/registrar-api_contact_properties" } ] }, "registrar-api_country": { "description": "The country in which the user lives.", "type": "string", "example": "US", "maxLength": 30, "nullable": true }, "registrar-api_created_at": { "description": "Shows time of creation.", "type": "string", "format": "date-time", "example": "2018-08-28T17:26:26Z" }, "registrar-api_current_registrar": { "description": "Shows name of current registrar.", "type": "string", "example": "Cloudflare" }, "registrar-api_cursor_result_info": { "description": "Provides cursor-based pagination metadata. List endpoints use this\nmetadata for cursor pagination. Pass the `cursor` value as a query\nparameter in the next request to fetch the next page. An empty string\nindicates the end of pagination.\n", "type": "object", "properties": { "count": { "description": "Number of items in the current result set.", "type": "integer", "example": 20 }, "cursor": { "description": "Opaque cursor for fetching the next page. Pass this value as the\n`cursor` query parameter in a subsequent request. An empty string\nindicates the end of pagination.\n", "type": "string", "example": "eyJ0IjoiMjAyNS0wNi0xNVQxMjowMDowMC4wMDAwMDBaIiwibiI6ImJyYXZvLm5ldCJ9" }, "per_page": { "description": "Maximum number of items per page.", "type": "integer", "example": 20 } }, "required": [ "cursor", "per_page", "count" ] }, "registrar-api_domain_check_request": { "description": "Request body for checking domain availability.", "type": "object", "properties": { "domains": { "description": "List of fully qualified domain names (FQDNs) to check for availability. Each domain must include the extension.\n- Minimum: 1 domain.\n- Maximum: 20 domains per request.\n- The response returns domains on unsupported extensions with `registrable: false` and a `reason` field.\n- The response may omit malformed domain names (e.g., names missing an extension).\n", "type": "array", "items": { "type": "string" }, "example": [ "example.com", "example.net" ], "maxItems": 20, "minItems": 1 } }, "required": [ "domains" ] }, "registrar-api_domain_check_response": { "allOf": [ { "$ref": "#/components/schemas/registrar-api_api-response-common" }, { "properties": { "result": { "description": "Contains the availability check results.", "type": "object", "properties": { "domains": { "description": "Array of domain availability results. Results for unsupported\nextensions contain `registrable: false` and a `reason`\nfield. The response may omit malformed domain names.\n", "type": "array", "items": { "$ref": "#/components/schemas/registrar-api_domain_check_result" } } }, "required": [ "domains" ] } }, "required": [ "result" ], "type": "object" } ] }, "registrar-api_domain_check_result": { "description": "Describes a single authoritative domain availability result from the Check endpoint. Check results reflect current registry status; use them immediately before registration.", "type": "object", "properties": { "name": { "description": "The fully qualified domain name (FQDN) in punycode format for internationalized domain names (IDNs).", "type": "string", "example": "example.com" }, "pricing": { "$ref": "#/components/schemas/registrar-api_pricing" }, "reason": { "description": "Appears only when `registrable` is `false` and explains the result.\n- `extension_not_supported_via_api`: Cloudflare Registrar supports this extension in the dashboard but currently excludes it from programmatic registration through this API. The user can register via `https://dash.cloudflare.com/{account_id}/domains/registrations`.\n- `extension_not_supported`: Cloudflare Registrar excludes this extension entirely.\n- `extension_disallows_registration`: The extension's registry temporarily or permanently freezes new registrations. Registrars currently cannot register domains on this extension.\n- `domain_premium`: The domain carries premium pricing. This API currently supports standard registrations only.\n- `domain_unavailable`: An existing registration, reservation, or other registry restriction makes the domain unavailable on a supported extension.", "type": "string", "example": "domain_unavailable", "enum": [ "extension_not_supported_via_api", "extension_not_supported", "extension_disallows_registration", "domain_premium", "domain_unavailable" ] }, "registrable": { "description": "Indicates programmatic registration eligibility according to a real-time registry check.\n- `true`: The domain is available for registration. The response includes the `pricing` object.\n- `false`: A restriction prevents registration. See the `reason` field for details. Some results, such as premium domains, may still include `tier`.", "type": "boolean", "example": true }, "tier": { "description": "The pricing tier for this domain. A `registrable` value of `true` always includes this field, which defaults to `standard` for most domains. A `registrable` value of `false` may omit it.\n- `standard`: Standard registry pricing.\n- `premium`: Premium domain with higher pricing from the registry.", "type": "string", "example": "standard", "enum": [ "standard", "premium" ] } }, "required": [ "name", "registrable" ] }, "registrar-api_domain_identifier": { "description": "Domain identifier.", "type": "string", "example": "ea95132c15732412d22c1476fa83f27a", "maxLength": 32, "readOnly": true }, "registrar-api_domain_name": { "description": "Provides a fully qualified domain name (FQDN), including the extension\n(e.g., `example.com`, `mybrand.app`). The domain name uniquely identifies\na registration. Cloudflare permits only one registration per domain, making\nthe domain name a natural idempotency key for registration requests.\n", "type": "string", "example": "example.com", "x-auditable": true }, "registrar-api_domain_properties": { "type": "object", "properties": { "available": { "$ref": "#/components/schemas/registrar-api_available" }, "can_register": { "$ref": "#/components/schemas/registrar-api_can_register" }, "created_at": { "$ref": "#/components/schemas/registrar-api_created_at" }, "current_registrar": { "$ref": "#/components/schemas/registrar-api_current_registrar" }, "expires_at": { "$ref": "#/components/schemas/registrar-api_expires_at" }, "id": { "$ref": "#/components/schemas/registrar-api_domain_identifier" }, "locked": { "$ref": "#/components/schemas/registrar-api_locked" }, "registrant_contact": { "$ref": "#/components/schemas/registrar-api_registrant_contact" }, "registry_statuses": { "$ref": "#/components/schemas/registrar-api_registry_statuses" }, "supported_tld": { "$ref": "#/components/schemas/registrar-api_supported_tld" }, "transfer_in": { "$ref": "#/components/schemas/registrar-api_transfer_in" }, "updated_at": { "$ref": "#/components/schemas/registrar-api_updated_at" } } }, "registrar-api_domain_response_collection": { "allOf": [ { "$ref": "#/components/schemas/registrar-api_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/registrar-api_domains" } } }, "type": "object" } ] }, "registrar-api_domain_response_single": { "allOf": [ { "$ref": "#/components/schemas/registrar-api_api-response-single" }, { "properties": { "result": { "type": "object" } }, "type": "object" } ] }, "registrar-api_domain_search_response": { "allOf": [ { "$ref": "#/components/schemas/registrar-api_api-response-common" }, { "properties": { "result": { "description": "Contains the search results.", "type": "object", "properties": { "domains": { "description": "Lists domain suggestions in relevance order. An empty array indicates that the search criteria matched zero domains.", "type": "array", "items": { "$ref": "#/components/schemas/registrar-api_domain_search_result" } } }, "required": [ "domains" ] } }, "required": [ "result" ], "type": "object" } ] }, "registrar-api_domain_search_result": { "description": "Describes a single domain suggestion from the Search endpoint. Search results use non-authoritative data that may come from a cache. Use POST /domain-check to confirm real-time availability and pricing before registration.", "type": "object", "properties": { "name": { "description": "The fully qualified domain name (FQDN) in punycode format for internationalized domain names (IDNs).", "type": "string", "example": "example.com" }, "pricing": { "$ref": "#/components/schemas/registrar-api_pricing" }, "reason": { "description": "Appears only when `registrable` is `false` and explains the advisory search result. Use POST /domain-check for authoritative status.\n- `extension_not_supported_via_api`: Cloudflare Registrar supports this extension in the dashboard but currently excludes it from programmatic registration through this API.\n- `extension_not_supported`: Cloudflare Registrar excludes this extension entirely.\n- `extension_disallows_registration`: The extension's registry temporarily or permanently freezes new registrations.\n- `domain_premium`: The domain carries premium pricing. This API currently supports standard registrations only.\n- `domain_unavailable`: The domain appears unavailable.", "type": "string", "example": "domain_unavailable", "enum": [ "extension_not_supported_via_api", "extension_not_supported", "extension_disallows_registration", "domain_premium", "domain_unavailable" ] }, "registrable": { "description": "Indicates domain availability according to potentially stale, non-authoritative search data.\n- `true`: The domain appears available. Use POST /domain-check to confirm before registration.\n- `false`: Search results mark the domain ineligible for registration through this API. See `reason` for details.", "type": "boolean", "example": true }, "tier": { "description": "The pricing tier for this domain.\nA `registrable` value of `true` always\nincludes this field, which defaults to `standard` for most domains. A\n`registrable` value of `false` may omit it.\n- `standard`: Standard registry pricing.\n- `premium`: Premium domain with higher pricing from the registry.\n", "type": "string", "example": "standard", "enum": [ "standard", "premium" ] } }, "required": [ "name", "registrable" ] }, "registrar-api_domain_update_properties": { "type": "object", "properties": { "auto_renew": { "$ref": "#/components/schemas/registrar-api_auto_renew" }, "locked": { "$ref": "#/components/schemas/registrar-api_locked" }, "privacy": { "$ref": "#/components/schemas/registrar-api_privacy" } } }, "registrar-api_domains": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/registrar-api_domain_properties" } ] }, "registrar-api_email": { "description": "The contact email address of the user.", "type": "string", "example": "user@example.com", "maxLength": 90 }, "registrar-api_expires_at": { "description": "Shows when domain name registration expires.", "type": "string", "format": "date-time", "example": "2019-08-28T23:59:59Z" }, "registrar-api_extension-item": { "description": "Extension entry with metadata and JSON Schema documents for the registration operation.", "type": "object", "properties": { "metadata": { "description": "Extension metadata.", "type": "object", "properties": { "name": { "description": "The full name of the extension. For example, \"co.uk\", or \"uk\".", "type": "string" }, "tld": { "description": "The TLD of the extension. For example, for \"co.uk\", it is \"uk\". For \"uk\", it is \"uk\".", "type": "string" } }, "required": [ "name", "tld" ] }, "registration_schema": { "description": "JSON Schema describing the expected input structure for registration operations on this extension.", "type": "object" } }, "required": [ "metadata", "registration_schema" ] }, "registrar-api_extension-response-collection": { "allOf": [ { "$ref": "#/components/schemas/registrar-api_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/registrar-api_extension-item" } }, "result_info": { "description": "Cursor-based pagination metadata.", "type": "object", "properties": { "count": { "description": "Number of items in the current result set.", "type": "integer" }, "cursor": { "description": "Opaque token for the next page. Empty string when no more pages.", "type": "string" }, "per_page": { "description": "Number of items per page.", "type": "integer" } } } }, "type": "object" } ] }, "registrar-api_extension-response-single": { "allOf": [ { "$ref": "#/components/schemas/registrar-api_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/registrar-api_extension-item" } }, "type": "object" } ] }, "registrar-api_fax": { "description": "Contact fax number.", "type": "string", "example": "123-867-5309" }, "registrar-api_first_name": { "description": "User's first name.", "type": "string", "example": "John", "maxLength": 60, "nullable": true }, "registrar-api_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "registrar-api_last_name": { "description": "User's last name.", "type": "string", "example": "Appleseed", "maxLength": 60, "nullable": true }, "registrar-api_locked": { "description": "Shows whether a registrar lock is in place for a domain.", "type": "boolean", "example": false, "x-auditable": true }, "registrar-api_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" }, "source": { "description": "Location of the invalid value that caused the error.", "type": "object", "properties": { "pointer": { "description": "JSON Pointer to the invalid or missing request value.", "type": "string" } }, "required": [ "pointer" ] } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "registrar-api_organization": { "description": "Name of organization.", "type": "string", "example": "Cloudflare, Inc." }, "registrar-api_pricing": { "description": "Provides annual pricing information for a registrable domain. This object\nappears only when `registrable` is `true`. The API returns all per-year\nprices as strings to preserve decimal precision.\n\n`registration_cost` and `renewal_cost` frequently have the same value, but\nmay differ, especially when registries set different premium rates for\ninitial registration and renewal. For a multi-year registration (e.g., 4\nyears), `registration_cost` applies to the first year and `renewal_cost`\napplies to each subsequent year. The values reflect the current registry\nrate, which may change over time. Search and Check may surface premium\npricing, but this API currently supports standard registrations only.\n", "type": "object", "properties": { "currency": { "description": "ISO-4217 currency code for the prices (e.g., \"USD\", \"EUR\", \"GBP\").", "type": "string", "example": "USD" }, "registration_cost": { "description": "The first-year cost to register this domain. For premium domains\n(`tier: premium`), the registry sets this price, which may significantly\nexceed standard pricing. For multi-year registrations, this cost applies\nto the first year only; `renewal_cost` applies to subsequent years.\n", "type": "string", "example": "8.57" }, "renewal_cost": { "description": "Per-year renewal cost for this domain. Applied to each year beyond\nthe first year of a multi-year registration, and to each annual\nauto-renewal thereafter. May differ from `registration_cost`,\nespecially for premium domains where initial registration often\ncosts more than renewals.\n", "type": "string", "example": "8.57" } }, "required": [ "currency", "registration_cost", "renewal_cost" ] }, "registrar-api_privacy": { "description": "Privacy option controls redacting WHOIS information.", "type": "boolean", "example": true, "x-auditable": true }, "registrar-api_registrant_contact": { "description": "Shows contact information for domain registrant.", "allOf": [ { "$ref": "#/components/schemas/registrar-api_contacts" } ] }, "registrar-api_registration": { "description": "A domain registration resource representing the current state of a registered domain.", "type": "object", "properties": { "auto_renew": { "description": "Whether automatic renewal occurs before expiration.", "type": "boolean", "example": true }, "created_at": { "description": "When the domain was registered. Present when the registration resource exists.", "type": "string", "format": "date-time", "example": "2025-01-15T10:00:00Z" }, "domain_name": { "$ref": "#/components/schemas/registrar-api_domain_name" }, "expires_at": { "description": "When the domain registration expires. Ready registrations include this value; only `registration_pending` may return null.", "type": "string", "format": "date-time", "example": "2026-01-15T10:00:00Z", "nullable": true }, "locked": { "description": "Whether the domain is locked for transfer.", "type": "boolean", "example": true }, "privacy_mode": { "description": "Current WHOIS privacy mode for the registration.", "type": "string", "example": "redaction", "enum": [ "off", "redaction" ] }, "status": { "description": "Current registration status.\n- `active`: The domain operates with an active registration.\n- `registration_pending`: Registration remains in progress.\n- `expired`: The domain registration expired.\n- `suspended`: The registry suspended the domain.\n- `redemption_period`: The domain entered the redemption grace period.\n- `pending_delete`: The registry scheduled the domain for deletion.\n", "type": "string", "example": "active", "enum": [ "active", "registration_pending", "expired", "suspended", "redemption_period", "pending_delete" ] } }, "required": [ "domain_name", "status", "created_at", "expires_at", "auto_renew", "privacy_mode", "locked" ] }, "registrar-api_registration-response-collection": { "allOf": [ { "$ref": "#/components/schemas/registrar-api_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/registrar-api_registration" } }, "result_info": { "$ref": "#/components/schemas/registrar-api_cursor_result_info" } }, "required": [ "result", "result_info" ], "type": "object" } ] }, "registrar-api_registration-response-single": { "allOf": [ { "$ref": "#/components/schemas/registrar-api_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/registrar-api_registration" } }, "type": "object" } ] }, "registrar-api_registration_contact": { "description": "Contact data for the domain registration. This information\nis submitted to the domain registry and, depending on extension and\nprivacy settings, may appear in public WHOIS records.\n", "type": "object", "properties": { "email": { "description": "Email address for the registrant. Used for domain-related\ncommunications from the registry, including ownership verification\nand renewal notices.\n", "type": "string", "format": "email", "example": "ada@example.com" }, "fax": { "description": "Fax number in E.164 format (e.g., `+1.5555555555`). Optional.\nMost registrations do not require a fax number.\n", "type": "string", "example": "+1.5555555555" }, "phone": { "description": "Phone number in E.164 format: `+{country_code}.{number}` without spaces or dashes. Examples: `+1.5555555555` (US), `+44.2071234567` (UK), `+81.312345678` (Japan).", "type": "string", "example": "+1.5555555555" }, "postal_info": { "$ref": "#/components/schemas/registrar-api_registration_contact_postal_info" } }, "required": [ "phone", "email", "postal_info" ] }, "registrar-api_registration_contact_address": { "description": "Physical mailing address for the registrant contact.", "type": "object", "properties": { "city": { "description": "City or locality name.", "type": "string", "example": "Austin" }, "country_code": { "description": "Two-letter country code per ISO 3166-1 alpha-2 (e.g., `US`, `GB`, `CA`, `DE`).", "type": "string", "example": "US" }, "postal_code": { "description": "Postal or ZIP code.", "type": "string", "example": "78701" }, "state": { "description": "State, province, or region. Use the standard abbreviation where applicable (e.g., `TX` for Texas, `ON` for Ontario).", "type": "string", "example": "TX" }, "street": { "description": "Street address including building/suite number.", "type": "string", "example": "123 Main St" } }, "required": [ "street", "city", "state", "postal_code", "country_code" ] }, "registrar-api_registration_contact_postal_info": { "description": "Postal/mailing information for the contact. The `name` field is the\ncomplete contact name in one string. Some registries require a complete\npersonal name, including a family or last name where applicable, but this\nAPI does not accept separate first-name and last-name fields for\nregistration contacts.\n", "type": "object", "properties": { "address": { "$ref": "#/components/schemas/registrar-api_registration_contact_address" }, "name": { "description": "Full legal name of the contact, including all required name components for an individual or authorized representative. Some registries require a complete personal name that includes a family or last name where applicable. Provide the complete name in this single field, for example `Ada Lovelace`; do not send separate first-name or last-name fields.", "type": "string", "example": "Ada Lovelace" }, "organization": { "description": "Organization or company name. Optional for individual registrants.", "type": "string", "example": "Example Inc" } }, "required": [ "name", "address" ] }, "registrar-api_registration_contacts": { "description": "Provides contact data for the registration request.\n\nThe per-extension schema from\n`GET /accounts/{account_id}/registrar/extensions/{extension}` defines the\naccepted contact roles. Every currently supported extension requires only\n`contacts.registrant` from API callers. Callers may provide additional roles\nsuch as `technical`, `administrator`, and `billing` when the extension\nschema includes them. When a registry requires an omitted role, Cloudflare\nmay derive that contact from `contacts.registrant`.\n\nWhen the request omits either the entire `contacts` object or\n`contacts.registrant`, the system uses the account's default address book\nentry as the registrant contact. The account owner must configure this\ndefault at `https://dash.cloudflare.com/{account_id}/domains/registrations`,\nwhere they can create or update the address book entry and accept the\nrequired agreement. Dashboard settings currently provide the only way to\nmanage address book entries.\n\nWithout either a default address book entry or a registrant contact, the\nregistration request fails validation.\n", "type": "object", "properties": { "administrator": { "description": "Optional administrator contact. Accepted only when the extension\nschema includes this role. When the registry requires an omitted\ncontact, Cloudflare may derive it from `contacts.registrant`.\n", "allOf": [ { "$ref": "#/components/schemas/registrar-api_registration_contact" } ] }, "billing": { "description": "Optional billing contact. Accepted only when the extension schema\nincludes this role. When the registry requires an omitted contact,\nCloudflare may derive it from `contacts.registrant`.\n", "allOf": [ { "$ref": "#/components/schemas/registrar-api_registration_contact" } ] }, "registrant": { "description": "Optional registrant contact. If omitted, the account's default\naddress book entry is used instead.\n", "allOf": [ { "$ref": "#/components/schemas/registrar-api_registration_contact" } ] }, "technical": { "description": "Optional technical contact. Accepted only when the extension schema\nincludes this role. When the registry requires an omitted contact,\nCloudflare may derive it from `contacts.registrant`.\n", "allOf": [ { "$ref": "#/components/schemas/registrar-api_registration_contact" } ] } } }, "registrar-api_registration_create_request": { "type": "object", "properties": { "acknowledgements": { "description": "Provides user acknowledgements for a specific extension or premium\nregistration flow. The extension registration schema from the\nextension discovery endpoint identifies the required keys.\n", "type": "object", "example": { "fees": { "currency": "USD", "registration_fee": 10, "renewal_fee": 10 } }, "additionalProperties": true }, "auto_renew": { "description": "Enable or disable automatic renewal. Defaults to `false` if omitted.\nSetting this field to `true` is an explicit opt-in authorizing\nCloudflare to charge the account's default payment method up to 30\ndays before domain expiry to renew the domain automatically.\nRenewal pricing may change over time based on registry pricing.\n", "type": "boolean", "example": false, "default": false }, "contact_extensions": { "description": "Provides registry-specific contact extension values for the registrant.\n`GET /accounts/{account_id}/registrar/extensions/{extension}` identifies\nthe required keys and allowed values for each extension in the\n`registration_schema.properties.contact_extensions` object.\n\nExamples include `.us` nexus fields, `.uk` registrant type fields,\nand `.ca` legal type fields. Omit this object when the extension's\nregistration schema excludes `contact_extensions`.\n", "type": "object", "example": { "application_purpose": "P3", "nexus_category": "C11" }, "additionalProperties": true }, "contacts": { "$ref": "#/components/schemas/registrar-api_registration_contacts" }, "domain_name": { "$ref": "#/components/schemas/registrar-api_domain_name" }, "privacy_mode": { "description": "Sets the WHOIS privacy mode for the registration. Defaults to `redaction`.\n- `off`: Disables WHOIS privacy.\n- `redaction`: Requests WHOIS redaction where the extension supports it.\n Some extensions exclude privacy and redaction.\n", "type": "string", "example": "redaction", "default": "redaction", "enum": [ "off", "redaction" ] }, "years": { "description": "Sets the registration term from 1 to 10 years. When omitted, this\nfield defaults to the registry's minimum registration period for the\nextension. Most extensions require 1 year, while some require longer\nminimum terms (e.g., `.ai` requires 2 years).\n\nEach registry may also enforce its own maximum registration term. A\nrequest above that maximum fails. When uncertain, omit this field to\nuse the default.\n", "type": "integer", "example": 1, "maximum": 10, "minimum": 1 } }, "required": [ "domain_name" ] }, "registrar-api_registration_update_request": { "description": "Request to update an existing domain registration.\n\nThis endpoint currently supports updating `auto_renew` only.\n", "type": "object", "properties": { "auto_renew": { "description": "Enable or disable automatic renewal.\nSetting this field to `true` authorizes Cloudflare to charge the\naccount's default payment method up to 30 days before domain expiry\nto renew the domain automatically. Renewal pricing may change over\ntime based on registry pricing.\n", "type": "boolean", "example": true } }, "minProperties": 1 }, "registrar-api_registry_statuses": { "description": "A comma-separated list of registry status codes. Refer to [EPP Status Codes](https://www.icann.org/resources/pages/epp-status-codes-2014-06-16-en) for the full list.", "type": "string", "example": "ok,serverTransferProhibited" }, "registrar-api_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 } } }, "registrar-api_state": { "description": "State.", "type": "string", "example": "TX" }, "registrar-api_supported_tld": { "description": "Indicates whether Cloudflare Registrar currently supports a particular TLD. Refer to [TLD Policies](https://www.cloudflare.com/tld-policies/) for a list of supported TLDs.", "type": "boolean", "example": true }, "registrar-api_telephone": { "description": "User's telephone number.", "type": "string", "example": "+1 123-123-1234", "maxLength": 20, "nullable": true }, "registrar-api_transfer_in": { "description": "Statuses for domain transfers into Cloudflare Registrar.", "properties": { "accept_foa": { "description": "Status of the registrant authorization step.", "type": "string", "example": "needed", "enum": [ "needed", "ok" ] }, "approve_transfer": { "description": "Status of the registry transfer-approval step.", "type": "string", "example": "unknown", "enum": [ "needed", "ok", "pending", "trying", "rejected", "unknown" ] }, "can_cancel_transfer": { "description": "Indicates if cancellation is still possible.", "type": "boolean", "example": true }, "disable_privacy": { "description": "Status of the privacy-guard disabling step at the foreign registrar.", "type": "string", "example": "ok", "enum": [ "needed", "ok", "unknown" ] }, "enter_auth_code": { "description": "Status of the auth-code entry and verification step.", "type": "string", "example": "needed", "enum": [ "needed", "ok", "pending", "trying", "rejected" ] }, "unlock_domain": { "description": "Status of the domain-unlock step at the foreign registrar.", "type": "string", "example": "ok", "enum": [ "needed", "ok", "pending", "trying", "unknown" ] } } }, "registrar-api_updated_at": { "description": "Last updated.", "type": "string", "format": "date-time", "example": "2018-08-28T17:26:26Z" }, "registrar-api_workflow-status-response-single": { "allOf": [ { "$ref": "#/components/schemas/registrar-api_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/registrar-api_workflow_status" } }, "type": "object" } ] }, "registrar-api_workflow_error": { "description": "Provides error details when a workflow reaches the `failed` state. The workflow type (registration, update, etc.) and underlying registry response determine the specific codes and messages. Workflow error codes differ from immediate HTTP error `errors[].code` values in non-2xx responses. Surface `error.message` to the user for context.", "type": "object", "properties": { "code": { "description": "Machine-readable error code identifying the failure reason.", "type": "string", "example": "registry_rejected" }, "message": { "description": "Human-readable explanation of the failure. May include registry-specific details.", "type": "string", "example": "Registry rejected the request." } }, "required": [ "code", "message" ] }, "registrar-api_workflow_links": { "type": "object", "properties": { "resource": { "description": "URL to the domain resource.", "type": "string", "example": "/accounts/{account_id}/registrar/registrations/example.com" }, "self": { "description": "URL to this status resource.", "type": "string", "example": "/accounts/{account_id}/registrar/registrations/example.com/registration-status" } }, "required": [ "self" ] }, "registrar-api_workflow_status": { "description": "Status of an async registration workflow.", "type": "object", "properties": { "completed": { "description": "Indicates whether the workflow reached a terminal state. A `succeeded` or `failed` state returns `true`; `pending`, `in_progress`, `action_required`, and `blocked` return `false`.", "type": "boolean", "example": false }, "context": { "description": "Provides workflow-specific data.\n\nFor domain-centric workflows, `context.domain_name` identifies the\nworkflow subject.\n", "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "error": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/registrar-api_workflow_error" } ], "nullable": true }, "links": { "$ref": "#/components/schemas/registrar-api_workflow_links" }, "state": { "description": "Describes the workflow lifecycle state.\n- `pending`: The workflow awaits processing.\n- `in_progress`: Processing started. Continue polling `links.self`.\n An internal deadline limits the duration of this state.\n- `action_required`: The workflow pauses for user action. See\n `context.action` for details. Stop automated polling until the user\n completes the required action.\n- `blocked`: A third party, such as the domain extension's registry or\n a losing registrar, prevents progress. Continue polling because the\n block may resolve when the third party responds.\n- `succeeded`: Terminal state. The operation completed successfully.\n `completed` equals `true`. For registrations,\n `context.registration` contains the resulting registration resource.\n- `failed`: Terminal state. The operation failed. `completed` equals\n `true`. See `error.code` and `error.message` for the reason. Require\n user review before retrying.\n", "type": "string", "example": "in_progress", "enum": [ "pending", "in_progress", "action_required", "blocked", "succeeded", "failed" ] }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "state", "completed", "created_at", "updated_at", "links" ] }, "registrar-api_zipcode": { "description": "The zipcode or postal code where the user lives.", "type": "string", "example": "12345", "maxLength": 20, "nullable": true }, "reports_AccountIndustryErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/reports_Error" } }, "messages": { "type": "array", "items": { "nullable": true }, "default": [] }, "result": { "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors", "result" ] }, "reports_AccountIndustryPatchResponse": { "type": "object", "properties": { "industry": { "description": "Industry string value", "example": "internet", "anyOf": [ { "description": "Industry: Unknown", "enum": [ "unknown" ], "title": "Unknown", "type": "string" }, { "description": "Industry: Unsupported", "enum": [ "unsupported" ], "title": "Unsupported", "type": "string" }, { "description": "Industry: Accounting", "enum": [ "accounting" ], "title": "Accounting", "type": "string" }, { "description": "Industry: Adult Entertainment", "enum": [ "adult_entertainment" ], "title": "Adult Entertainment", "type": "string" }, { "description": "Industry: Agriculture", "enum": [ "agriculture" ], "title": "Agriculture", "type": "string" }, { "description": "Industry: Airlines, Aviation & Aerospace", "enum": [ "airlines_aviation_aerospace" ], "title": "Airlines Aviation Aerospace", "type": "string" }, { "description": "Industry: Animation & Design", "enum": [ "animation_design" ], "title": "Animation Design", "type": "string" }, { "description": "Industry: Apparel & Fashion", "enum": [ "apparel_fashion" ], "title": "Apparel Fashion", "type": "string" }, { "description": "Industry: Architecture & Planning", "enum": [ "architecture_planning" ], "title": "Architecture Planning", "type": "string" }, { "description": "Industry: Automotive", "enum": [ "automotive" ], "title": "Automotive", "type": "string" }, { "description": "Industry: Banking & Financial Services", "enum": [ "banking_financial_services" ], "title": "Banking Financial Services", "type": "string" }, { "description": "Industry: Broadcast Media", "enum": [ "broadcast_media" ], "title": "Broadcast Media", "type": "string" }, { "description": "Industry: Building Materials & Construction", "enum": [ "building_materials_construction" ], "title": "Building Materials Construction", "type": "string" }, { "description": "Industry: Business Services, Supplies & Equipment", "enum": [ "business_services_supplies_equipment" ], "title": "Business Services Supplies Equipment", "type": "string" }, { "description": "Industry: Computer Hardware", "enum": [ "computer_hardware" ], "title": "Computer Hardware", "type": "string" }, { "description": "Industry: Computer Software", "enum": [ "computer_software" ], "title": "Computer Software", "type": "string" }, { "description": "Industry: Construction & Civil Engineering", "enum": [ "construction_civil_engineering" ], "title": "Construction Civil Engineering", "type": "string" }, { "description": "Industry: Consumer Electronics", "enum": [ "consumer_electronics" ], "title": "Consumer Electronics", "type": "string" }, { "description": "Industry: Consumer Goods", "enum": [ "consumer_goods" ], "title": "Consumer Goods", "type": "string" }, { "description": "Industry: Consumer Services", "enum": [ "consumer_services" ], "title": "Consumer Services", "type": "string" }, { "description": "Industry: Cosmetics", "enum": [ "cosmetics" ], "title": "Cosmetics", "type": "string" }, { "description": "Industry: Cryptocurrency", "enum": [ "cryptocurrency" ], "title": "Cryptocurrency", "type": "string" }, { "description": "Industry: Cyber Security", "enum": [ "cyber_security" ], "title": "Cyber Security", "type": "string" }, { "description": "Industry: Defense & Space", "enum": [ "defense_space" ], "title": "Defense Space", "type": "string" }, { "description": "Industry: E-Learning", "enum": [ "e_learning" ], "title": "E Learning", "type": "string" }, { "description": "Industry: Education & Academia", "enum": [ "education_academia" ], "title": "Education Academia", "type": "string" }, { "description": "Industry: Education Management", "enum": [ "education_management" ], "title": "Education Management", "type": "string" }, { "description": "Industry: Entertainment", "enum": [ "entertainment" ], "title": "Entertainment", "type": "string" }, { "description": "Industry: Environmental Services", "enum": [ "environmental_services" ], "title": "Environmental Services", "type": "string" }, { "description": "Industry: Events Services", "enum": [ "events_services" ], "title": "Events Services", "type": "string" }, { "description": "Industry: Facilities Services", "enum": [ "facilities_services" ], "title": "Facilities Services", "type": "string" }, { "description": "Industry: Fine Art, Luxury Goods & Jewelry", "enum": [ "fine_art_luxury_goods_jewelry" ], "title": "Fine Art Luxury Goods Jewelry", "type": "string" }, { "description": "Industry: Food & Beverage", "enum": [ "food_beverage" ], "title": "Food Beverage", "type": "string" }, { "description": "Industry: Furniture", "enum": [ "furniture" ], "title": "Furniture", "type": "string" }, { "description": "Industry: Gambling & Casinos", "enum": [ "gambling_casinos" ], "title": "Gambling Casinos", "type": "string" }, { "description": "Industry: Gaming", "enum": [ "gaming" ], "title": "Gaming", "type": "string" }, { "description": "Industry: Government", "enum": [ "government" ], "title": "Government", "type": "string" }, { "description": "Industry: Health, Wellness & Fitness", "enum": [ "health_wellness_fitness" ], "title": "Health Wellness Fitness", "type": "string" }, { "description": "Industry: Holding Companies & Conglomerates", "enum": [ "holding_companies_conglomerates" ], "title": "Holding Companies Conglomerates", "type": "string" }, { "description": "Industry: Human Resources, Staffing & Recruiting", "enum": [ "human_resources_staffing_recruiting" ], "title": "Human Resources Staffing Recruiting", "type": "string" }, { "description": "Industry: Information Technology & Services", "enum": [ "information_technology_services" ], "title": "Information Technology Services", "type": "string" }, { "description": "Industry: Insurance", "enum": [ "insurance" ], "title": "Insurance", "type": "string" }, { "description": "Industry: International Public Affairs", "enum": [ "international_public_affairs" ], "title": "International Public Affairs", "type": "string" }, { "description": "Industry: International Trade & Development", "enum": [ "international_trade_development" ], "title": "International Trade Development", "type": "string" }, { "description": "Industry: Internet", "enum": [ "internet" ], "title": "Internet", "type": "string" }, { "description": "Industry: Investment Management", "enum": [ "investment_management" ], "title": "Investment Management", "type": "string" }, { "description": "Industry: Law Firms & Legal Services", "enum": [ "law_firms_legal_services" ], "title": "Law Firms Legal Services", "type": "string" }, { "description": "Industry: Leisure, Travel & Tourism", "enum": [ "leisure_travel_tourism" ], "title": "Leisure Travel Tourism", "type": "string" }, { "description": "Industry: Logistics, Supply Chain, Import & Export", "enum": [ "logistics_supply_chain_import_export" ], "title": "Logistics Supply Chain Import Export", "type": "string" }, { "description": "Industry: Management Consulting", "enum": [ "management_consulting" ], "title": "Management Consulting", "type": "string" }, { "description": "Industry: Manufacturing, Machinery, Technology & Engineering", "enum": [ "manufacturing_machinery_technology_engineering" ], "title": "Manufacturing Machinery Technology Engineering", "type": "string" }, { "description": "Industry: Maritime", "enum": [ "maritime" ], "title": "Maritime", "type": "string" }, { "description": "Industry: Market Research", "enum": [ "market_research" ], "title": "Market Research", "type": "string" }, { "description": "Industry: Marketing & Advertising", "enum": [ "marketing_advertising" ], "title": "Marketing Advertising", "type": "string" }, { "description": "Industry: Media Production & Publishing", "enum": [ "media_production_publishing" ], "title": "Media Production Publishing", "type": "string" }, { "description": "Industry: Medical Devices, Healthcare Software & Services", "enum": [ "medical_devices_healthcare_software_services" ], "title": "Medical Devices Healthcare Software Services", "type": "string" }, { "description": "Industry: Medical Practices, Clinics, Hospitals & Health Care", "enum": [ "medical_practices_clinics_hospitals_health_care" ], "title": "Medical Practices Clinics Hospitals Health Care", "type": "string" }, { "description": "Industry: Military & Law Enforcement", "enum": [ "military_law_enforcement" ], "title": "Military Law Enforcement", "type": "string" }, { "description": "Industry: Mining, Minerals & Metals", "enum": [ "mining_minerals_metals" ], "title": "Mining Minerals Metals", "type": "string" }, { "description": "Industry: Motion Pictures & Film", "enum": [ "motion_pictures_and_film" ], "title": "Motion Pictures And Film", "type": "string" }, { "description": "Industry: Museums & Libraries", "enum": [ "museums_libraries" ], "title": "Museums Libraries", "type": "string" }, { "description": "Industry: Music & Art", "enum": [ "music_art" ], "title": "Music Art", "type": "string" }, { "description": "Industry: Newspapers", "enum": [ "newspapers" ], "title": "Newspapers", "type": "string" }, { "description": "Industry: Nonprofit", "enum": [ "nonprofit" ], "title": "Nonprofit", "type": "string" }, { "description": "Industry: Oil, Energy, Utilities & Waste", "enum": [ "oil_energy_utilities_waste" ], "title": "Oil Energy Utilities Waste", "type": "string" }, { "description": "Industry: Organizations & Local Business", "enum": [ "organizations_local_business" ], "title": "Organizations Local Business", "type": "string" }, { "description": "Industry: Outsourcing & Offshoring", "enum": [ "outsourcing_offshoring" ], "title": "Outsourcing Offshoring", "type": "string" }, { "description": "Industry: Pharmaceuticals, Biotechnology & Alternative Medicine", "enum": [ "pharmaceuticals_biotechnology_alternative_medicine" ], "title": "Pharmaceuticals Biotechnology Alternative Medicine", "type": "string" }, { "description": "Industry: Photographic & Optical Equipment", "enum": [ "photographic_optical_equipment" ], "title": "Photographic Optical Equipment", "type": "string" }, { "description": "Industry: Political Organization", "enum": [ "political_organization" ], "title": "Political Organization", "type": "string" }, { "description": "Industry: Print & Digital Media", "enum": [ "print_digital_media" ], "title": "Print Digital Media", "type": "string" }, { "description": "Industry: Professional Training & Coaching", "enum": [ "professional_training_coaching" ], "title": "Professional Training Coaching", "type": "string" }, { "description": "Industry: Real Estate", "enum": [ "real_estate" ], "title": "Real Estate", "type": "string" }, { "description": "Industry: Religious Institutions", "enum": [ "religious_institutions" ], "title": "Religious Institutions", "type": "string" }, { "description": "Industry: Renewables & Environment", "enum": [ "renewables_environment" ], "title": "Renewables Environment", "type": "string" }, { "description": "Industry: Research & Think Tanks", "enum": [ "research_think_tanks" ], "title": "Research Think Tanks", "type": "string" }, { "description": "Industry: Restaurants", "enum": [ "restaurants" ], "title": "Restaurants", "type": "string" }, { "description": "Industry: Retail", "enum": [ "retail" ], "title": "Retail", "type": "string" }, { "description": "Industry: Security Services & Investigations", "enum": [ "security_services_investigations" ], "title": "Security Services Investigations", "type": "string" }, { "description": "Industry: Social Impact & Community Services", "enum": [ "social_impact_and_community_services" ], "title": "Social Impact And Community Services", "type": "string" }, { "description": "Industry: Sporting Goods", "enum": [ "sporting_goods" ], "title": "Sporting Goods", "type": "string" }, { "description": "Industry: Supermarkets & Groceries", "enum": [ "supermarkets_groceries" ], "title": "Supermarkets Groceries", "type": "string" }, { "description": "Industry: Telecommunications Service Providers & Carriers", "enum": [ "telecommunications_service_providers_and_carriers" ], "title": "Telecommunications Service Providers And Carriers", "type": "string" }, { "description": "Industry: Transportation, Shipping, Packaging & Delivery", "enum": [ "transportation_shipping_packaging_delivery" ], "title": "Transportation Shipping Packaging Delivery", "type": "string" }, { "description": "Industry: Travel, Lodging & Hospitality", "enum": [ "travel_lodging_hospitality" ], "title": "Travel Lodging Hospitality", "type": "string" }, { "description": "Industry: Wholesale", "enum": [ "wholesale" ], "title": "Wholesale", "type": "string" } ] }, "unlock_time": { "description": "Time when the industry can be updated again", "type": "string", "example": "2026-01-01T00:00:00Z", "nullable": true }, "valid_from": { "description": "Start date for this industry association", "type": "string", "example": "2024-01-01T00:00:00Z", "nullable": true }, "version": { "description": "Version number for this association", "type": "integer", "example": 1, "exclusiveMinimum": true, "minimum": 0 } }, "nullable": true, "required": [ "industry", "version", "valid_from", "unlock_time" ] }, "reports_AccountIndustrySingleResponse": { "type": "object", "properties": { "industry": { "description": "Industry string value", "example": "internet", "anyOf": [ { "description": "Industry: Unknown", "enum": [ "unknown" ], "title": "Unknown", "type": "string" }, { "description": "Industry: Unsupported", "enum": [ "unsupported" ], "title": "Unsupported", "type": "string" }, { "description": "Industry: Accounting", "enum": [ "accounting" ], "title": "Accounting", "type": "string" }, { "description": "Industry: Adult Entertainment", "enum": [ "adult_entertainment" ], "title": "Adult Entertainment", "type": "string" }, { "description": "Industry: Agriculture", "enum": [ "agriculture" ], "title": "Agriculture", "type": "string" }, { "description": "Industry: Airlines, Aviation & Aerospace", "enum": [ "airlines_aviation_aerospace" ], "title": "Airlines Aviation Aerospace", "type": "string" }, { "description": "Industry: Animation & Design", "enum": [ "animation_design" ], "title": "Animation Design", "type": "string" }, { "description": "Industry: Apparel & Fashion", "enum": [ "apparel_fashion" ], "title": "Apparel Fashion", "type": "string" }, { "description": "Industry: Architecture & Planning", "enum": [ "architecture_planning" ], "title": "Architecture Planning", "type": "string" }, { "description": "Industry: Automotive", "enum": [ "automotive" ], "title": "Automotive", "type": "string" }, { "description": "Industry: Banking & Financial Services", "enum": [ "banking_financial_services" ], "title": "Banking Financial Services", "type": "string" }, { "description": "Industry: Broadcast Media", "enum": [ "broadcast_media" ], "title": "Broadcast Media", "type": "string" }, { "description": "Industry: Building Materials & Construction", "enum": [ "building_materials_construction" ], "title": "Building Materials Construction", "type": "string" }, { "description": "Industry: Business Services, Supplies & Equipment", "enum": [ "business_services_supplies_equipment" ], "title": "Business Services Supplies Equipment", "type": "string" }, { "description": "Industry: Computer Hardware", "enum": [ "computer_hardware" ], "title": "Computer Hardware", "type": "string" }, { "description": "Industry: Computer Software", "enum": [ "computer_software" ], "title": "Computer Software", "type": "string" }, { "description": "Industry: Construction & Civil Engineering", "enum": [ "construction_civil_engineering" ], "title": "Construction Civil Engineering", "type": "string" }, { "description": "Industry: Consumer Electronics", "enum": [ "consumer_electronics" ], "title": "Consumer Electronics", "type": "string" }, { "description": "Industry: Consumer Goods", "enum": [ "consumer_goods" ], "title": "Consumer Goods", "type": "string" }, { "description": "Industry: Consumer Services", "enum": [ "consumer_services" ], "title": "Consumer Services", "type": "string" }, { "description": "Industry: Cosmetics", "enum": [ "cosmetics" ], "title": "Cosmetics", "type": "string" }, { "description": "Industry: Cryptocurrency", "enum": [ "cryptocurrency" ], "title": "Cryptocurrency", "type": "string" }, { "description": "Industry: Cyber Security", "enum": [ "cyber_security" ], "title": "Cyber Security", "type": "string" }, { "description": "Industry: Defense & Space", "enum": [ "defense_space" ], "title": "Defense Space", "type": "string" }, { "description": "Industry: E-Learning", "enum": [ "e_learning" ], "title": "E Learning", "type": "string" }, { "description": "Industry: Education & Academia", "enum": [ "education_academia" ], "title": "Education Academia", "type": "string" }, { "description": "Industry: Education Management", "enum": [ "education_management" ], "title": "Education Management", "type": "string" }, { "description": "Industry: Entertainment", "enum": [ "entertainment" ], "title": "Entertainment", "type": "string" }, { "description": "Industry: Environmental Services", "enum": [ "environmental_services" ], "title": "Environmental Services", "type": "string" }, { "description": "Industry: Events Services", "enum": [ "events_services" ], "title": "Events Services", "type": "string" }, { "description": "Industry: Facilities Services", "enum": [ "facilities_services" ], "title": "Facilities Services", "type": "string" }, { "description": "Industry: Fine Art, Luxury Goods & Jewelry", "enum": [ "fine_art_luxury_goods_jewelry" ], "title": "Fine Art Luxury Goods Jewelry", "type": "string" }, { "description": "Industry: Food & Beverage", "enum": [ "food_beverage" ], "title": "Food Beverage", "type": "string" }, { "description": "Industry: Furniture", "enum": [ "furniture" ], "title": "Furniture", "type": "string" }, { "description": "Industry: Gambling & Casinos", "enum": [ "gambling_casinos" ], "title": "Gambling Casinos", "type": "string" }, { "description": "Industry: Gaming", "enum": [ "gaming" ], "title": "Gaming", "type": "string" }, { "description": "Industry: Government", "enum": [ "government" ], "title": "Government", "type": "string" }, { "description": "Industry: Health, Wellness & Fitness", "enum": [ "health_wellness_fitness" ], "title": "Health Wellness Fitness", "type": "string" }, { "description": "Industry: Holding Companies & Conglomerates", "enum": [ "holding_companies_conglomerates" ], "title": "Holding Companies Conglomerates", "type": "string" }, { "description": "Industry: Human Resources, Staffing & Recruiting", "enum": [ "human_resources_staffing_recruiting" ], "title": "Human Resources Staffing Recruiting", "type": "string" }, { "description": "Industry: Information Technology & Services", "enum": [ "information_technology_services" ], "title": "Information Technology Services", "type": "string" }, { "description": "Industry: Insurance", "enum": [ "insurance" ], "title": "Insurance", "type": "string" }, { "description": "Industry: International Public Affairs", "enum": [ "international_public_affairs" ], "title": "International Public Affairs", "type": "string" }, { "description": "Industry: International Trade & Development", "enum": [ "international_trade_development" ], "title": "International Trade Development", "type": "string" }, { "description": "Industry: Internet", "enum": [ "internet" ], "title": "Internet", "type": "string" }, { "description": "Industry: Investment Management", "enum": [ "investment_management" ], "title": "Investment Management", "type": "string" }, { "description": "Industry: Law Firms & Legal Services", "enum": [ "law_firms_legal_services" ], "title": "Law Firms Legal Services", "type": "string" }, { "description": "Industry: Leisure, Travel & Tourism", "enum": [ "leisure_travel_tourism" ], "title": "Leisure Travel Tourism", "type": "string" }, { "description": "Industry: Logistics, Supply Chain, Import & Export", "enum": [ "logistics_supply_chain_import_export" ], "title": "Logistics Supply Chain Import Export", "type": "string" }, { "description": "Industry: Management Consulting", "enum": [ "management_consulting" ], "title": "Management Consulting", "type": "string" }, { "description": "Industry: Manufacturing, Machinery, Technology & Engineering", "enum": [ "manufacturing_machinery_technology_engineering" ], "title": "Manufacturing Machinery Technology Engineering", "type": "string" }, { "description": "Industry: Maritime", "enum": [ "maritime" ], "title": "Maritime", "type": "string" }, { "description": "Industry: Market Research", "enum": [ "market_research" ], "title": "Market Research", "type": "string" }, { "description": "Industry: Marketing & Advertising", "enum": [ "marketing_advertising" ], "title": "Marketing Advertising", "type": "string" }, { "description": "Industry: Media Production & Publishing", "enum": [ "media_production_publishing" ], "title": "Media Production Publishing", "type": "string" }, { "description": "Industry: Medical Devices, Healthcare Software & Services", "enum": [ "medical_devices_healthcare_software_services" ], "title": "Medical Devices Healthcare Software Services", "type": "string" }, { "description": "Industry: Medical Practices, Clinics, Hospitals & Health Care", "enum": [ "medical_practices_clinics_hospitals_health_care" ], "title": "Medical Practices Clinics Hospitals Health Care", "type": "string" }, { "description": "Industry: Military & Law Enforcement", "enum": [ "military_law_enforcement" ], "title": "Military Law Enforcement", "type": "string" }, { "description": "Industry: Mining, Minerals & Metals", "enum": [ "mining_minerals_metals" ], "title": "Mining Minerals Metals", "type": "string" }, { "description": "Industry: Motion Pictures & Film", "enum": [ "motion_pictures_and_film" ], "title": "Motion Pictures And Film", "type": "string" }, { "description": "Industry: Museums & Libraries", "enum": [ "museums_libraries" ], "title": "Museums Libraries", "type": "string" }, { "description": "Industry: Music & Art", "enum": [ "music_art" ], "title": "Music Art", "type": "string" }, { "description": "Industry: Newspapers", "enum": [ "newspapers" ], "title": "Newspapers", "type": "string" }, { "description": "Industry: Nonprofit", "enum": [ "nonprofit" ], "title": "Nonprofit", "type": "string" }, { "description": "Industry: Oil, Energy, Utilities & Waste", "enum": [ "oil_energy_utilities_waste" ], "title": "Oil Energy Utilities Waste", "type": "string" }, { "description": "Industry: Organizations & Local Business", "enum": [ "organizations_local_business" ], "title": "Organizations Local Business", "type": "string" }, { "description": "Industry: Outsourcing & Offshoring", "enum": [ "outsourcing_offshoring" ], "title": "Outsourcing Offshoring", "type": "string" }, { "description": "Industry: Pharmaceuticals, Biotechnology & Alternative Medicine", "enum": [ "pharmaceuticals_biotechnology_alternative_medicine" ], "title": "Pharmaceuticals Biotechnology Alternative Medicine", "type": "string" }, { "description": "Industry: Photographic & Optical Equipment", "enum": [ "photographic_optical_equipment" ], "title": "Photographic Optical Equipment", "type": "string" }, { "description": "Industry: Political Organization", "enum": [ "political_organization" ], "title": "Political Organization", "type": "string" }, { "description": "Industry: Print & Digital Media", "enum": [ "print_digital_media" ], "title": "Print Digital Media", "type": "string" }, { "description": "Industry: Professional Training & Coaching", "enum": [ "professional_training_coaching" ], "title": "Professional Training Coaching", "type": "string" }, { "description": "Industry: Real Estate", "enum": [ "real_estate" ], "title": "Real Estate", "type": "string" }, { "description": "Industry: Religious Institutions", "enum": [ "religious_institutions" ], "title": "Religious Institutions", "type": "string" }, { "description": "Industry: Renewables & Environment", "enum": [ "renewables_environment" ], "title": "Renewables Environment", "type": "string" }, { "description": "Industry: Research & Think Tanks", "enum": [ "research_think_tanks" ], "title": "Research Think Tanks", "type": "string" }, { "description": "Industry: Restaurants", "enum": [ "restaurants" ], "title": "Restaurants", "type": "string" }, { "description": "Industry: Retail", "enum": [ "retail" ], "title": "Retail", "type": "string" }, { "description": "Industry: Security Services & Investigations", "enum": [ "security_services_investigations" ], "title": "Security Services Investigations", "type": "string" }, { "description": "Industry: Social Impact & Community Services", "enum": [ "social_impact_and_community_services" ], "title": "Social Impact And Community Services", "type": "string" }, { "description": "Industry: Sporting Goods", "enum": [ "sporting_goods" ], "title": "Sporting Goods", "type": "string" }, { "description": "Industry: Supermarkets & Groceries", "enum": [ "supermarkets_groceries" ], "title": "Supermarkets Groceries", "type": "string" }, { "description": "Industry: Telecommunications Service Providers & Carriers", "enum": [ "telecommunications_service_providers_and_carriers" ], "title": "Telecommunications Service Providers And Carriers", "type": "string" }, { "description": "Industry: Transportation, Shipping, Packaging & Delivery", "enum": [ "transportation_shipping_packaging_delivery" ], "title": "Transportation Shipping Packaging Delivery", "type": "string" }, { "description": "Industry: Travel, Lodging & Hospitality", "enum": [ "travel_lodging_hospitality" ], "title": "Travel Lodging Hospitality", "type": "string" }, { "description": "Industry: Wholesale", "enum": [ "wholesale" ], "title": "Wholesale", "type": "string" } ] }, "unlock_time": { "description": "Time when the industry can be updated again", "type": "string", "example": "2026-01-01T00:00:00Z", "nullable": true } }, "nullable": true, "required": [ "industry", "unlock_time" ] }, "reports_ApplicationSecurityReportV1": { "type": "object", "properties": { "input": { "description": "Input parameters required to generate an Application Security Report V1", "type": "object", "properties": { "time_range": { "description": "Time range specification for reports and queries. Used to define the period of data to include in analysis.", "type": "object", "properties": { "end_time": { "description": "End timestamp for the time range (exclusive). Must be after start_time. Accepts ISO 8601 date strings or Date objects.", "type": "string", "format": "date-time", "example": "2024-01-08T00:00:00Z", "nullable": true }, "start_time": { "description": "Start timestamp for the time range (inclusive). Accepts ISO 8601 date strings or Date objects.", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z", "nullable": true } }, "required": [ "start_time", "end_time" ] } }, "required": [ "time_range" ] }, "output": { "$ref": "#/components/schemas/reports_ApplicationSecurityReportV1Data" } }, "required": [ "input", "output" ] }, "reports_ApplicationSecurityReportV1Data": { "type": "object", "properties": { "account_id": { "description": "Cloudflare account ID this report was generated for", "type": "string", "example": "f1234567890abcdef1234567890abcdef" }, "account_name": { "description": "Human-readable name of the account", "type": "string", "example": "Cloudflare Example" }, "industry": { "description": "The industry of the account.", "example": "internet", "anyOf": [ { "description": "Industry: Unknown", "enum": [ "unknown" ], "title": "Unknown", "type": "string" }, { "description": "Industry: Unsupported", "enum": [ "unsupported" ], "title": "Unsupported", "type": "string" }, { "description": "Industry: Accounting", "enum": [ "accounting" ], "title": "Accounting", "type": "string" }, { "description": "Industry: Adult Entertainment", "enum": [ "adult_entertainment" ], "title": "Adult Entertainment", "type": "string" }, { "description": "Industry: Agriculture", "enum": [ "agriculture" ], "title": "Agriculture", "type": "string" }, { "description": "Industry: Airlines, Aviation & Aerospace", "enum": [ "airlines_aviation_aerospace" ], "title": "Airlines Aviation Aerospace", "type": "string" }, { "description": "Industry: Animation & Design", "enum": [ "animation_design" ], "title": "Animation Design", "type": "string" }, { "description": "Industry: Apparel & Fashion", "enum": [ "apparel_fashion" ], "title": "Apparel Fashion", "type": "string" }, { "description": "Industry: Architecture & Planning", "enum": [ "architecture_planning" ], "title": "Architecture Planning", "type": "string" }, { "description": "Industry: Automotive", "enum": [ "automotive" ], "title": "Automotive", "type": "string" }, { "description": "Industry: Banking & Financial Services", "enum": [ "banking_financial_services" ], "title": "Banking Financial Services", "type": "string" }, { "description": "Industry: Broadcast Media", "enum": [ "broadcast_media" ], "title": "Broadcast Media", "type": "string" }, { "description": "Industry: Building Materials & Construction", "enum": [ "building_materials_construction" ], "title": "Building Materials Construction", "type": "string" }, { "description": "Industry: Business Services, Supplies & Equipment", "enum": [ "business_services_supplies_equipment" ], "title": "Business Services Supplies Equipment", "type": "string" }, { "description": "Industry: Computer Hardware", "enum": [ "computer_hardware" ], "title": "Computer Hardware", "type": "string" }, { "description": "Industry: Computer Software", "enum": [ "computer_software" ], "title": "Computer Software", "type": "string" }, { "description": "Industry: Construction & Civil Engineering", "enum": [ "construction_civil_engineering" ], "title": "Construction Civil Engineering", "type": "string" }, { "description": "Industry: Consumer Electronics", "enum": [ "consumer_electronics" ], "title": "Consumer Electronics", "type": "string" }, { "description": "Industry: Consumer Goods", "enum": [ "consumer_goods" ], "title": "Consumer Goods", "type": "string" }, { "description": "Industry: Consumer Services", "enum": [ "consumer_services" ], "title": "Consumer Services", "type": "string" }, { "description": "Industry: Cosmetics", "enum": [ "cosmetics" ], "title": "Cosmetics", "type": "string" }, { "description": "Industry: Cryptocurrency", "enum": [ "cryptocurrency" ], "title": "Cryptocurrency", "type": "string" }, { "description": "Industry: Cyber Security", "enum": [ "cyber_security" ], "title": "Cyber Security", "type": "string" }, { "description": "Industry: Defense & Space", "enum": [ "defense_space" ], "title": "Defense Space", "type": "string" }, { "description": "Industry: E-Learning", "enum": [ "e_learning" ], "title": "E Learning", "type": "string" }, { "description": "Industry: Education & Academia", "enum": [ "education_academia" ], "title": "Education Academia", "type": "string" }, { "description": "Industry: Education Management", "enum": [ "education_management" ], "title": "Education Management", "type": "string" }, { "description": "Industry: Entertainment", "enum": [ "entertainment" ], "title": "Entertainment", "type": "string" }, { "description": "Industry: Environmental Services", "enum": [ "environmental_services" ], "title": "Environmental Services", "type": "string" }, { "description": "Industry: Events Services", "enum": [ "events_services" ], "title": "Events Services", "type": "string" }, { "description": "Industry: Facilities Services", "enum": [ "facilities_services" ], "title": "Facilities Services", "type": "string" }, { "description": "Industry: Fine Art, Luxury Goods & Jewelry", "enum": [ "fine_art_luxury_goods_jewelry" ], "title": "Fine Art Luxury Goods Jewelry", "type": "string" }, { "description": "Industry: Food & Beverage", "enum": [ "food_beverage" ], "title": "Food Beverage", "type": "string" }, { "description": "Industry: Furniture", "enum": [ "furniture" ], "title": "Furniture", "type": "string" }, { "description": "Industry: Gambling & Casinos", "enum": [ "gambling_casinos" ], "title": "Gambling Casinos", "type": "string" }, { "description": "Industry: Gaming", "enum": [ "gaming" ], "title": "Gaming", "type": "string" }, { "description": "Industry: Government", "enum": [ "government" ], "title": "Government", "type": "string" }, { "description": "Industry: Health, Wellness & Fitness", "enum": [ "health_wellness_fitness" ], "title": "Health Wellness Fitness", "type": "string" }, { "description": "Industry: Holding Companies & Conglomerates", "enum": [ "holding_companies_conglomerates" ], "title": "Holding Companies Conglomerates", "type": "string" }, { "description": "Industry: Human Resources, Staffing & Recruiting", "enum": [ "human_resources_staffing_recruiting" ], "title": "Human Resources Staffing Recruiting", "type": "string" }, { "description": "Industry: Information Technology & Services", "enum": [ "information_technology_services" ], "title": "Information Technology Services", "type": "string" }, { "description": "Industry: Insurance", "enum": [ "insurance" ], "title": "Insurance", "type": "string" }, { "description": "Industry: International Public Affairs", "enum": [ "international_public_affairs" ], "title": "International Public Affairs", "type": "string" }, { "description": "Industry: International Trade & Development", "enum": [ "international_trade_development" ], "title": "International Trade Development", "type": "string" }, { "description": "Industry: Internet", "enum": [ "internet" ], "title": "Internet", "type": "string" }, { "description": "Industry: Investment Management", "enum": [ "investment_management" ], "title": "Investment Management", "type": "string" }, { "description": "Industry: Law Firms & Legal Services", "enum": [ "law_firms_legal_services" ], "title": "Law Firms Legal Services", "type": "string" }, { "description": "Industry: Leisure, Travel & Tourism", "enum": [ "leisure_travel_tourism" ], "title": "Leisure Travel Tourism", "type": "string" }, { "description": "Industry: Logistics, Supply Chain, Import & Export", "enum": [ "logistics_supply_chain_import_export" ], "title": "Logistics Supply Chain Import Export", "type": "string" }, { "description": "Industry: Management Consulting", "enum": [ "management_consulting" ], "title": "Management Consulting", "type": "string" }, { "description": "Industry: Manufacturing, Machinery, Technology & Engineering", "enum": [ "manufacturing_machinery_technology_engineering" ], "title": "Manufacturing Machinery Technology Engineering", "type": "string" }, { "description": "Industry: Maritime", "enum": [ "maritime" ], "title": "Maritime", "type": "string" }, { "description": "Industry: Market Research", "enum": [ "market_research" ], "title": "Market Research", "type": "string" }, { "description": "Industry: Marketing & Advertising", "enum": [ "marketing_advertising" ], "title": "Marketing Advertising", "type": "string" }, { "description": "Industry: Media Production & Publishing", "enum": [ "media_production_publishing" ], "title": "Media Production Publishing", "type": "string" }, { "description": "Industry: Medical Devices, Healthcare Software & Services", "enum": [ "medical_devices_healthcare_software_services" ], "title": "Medical Devices Healthcare Software Services", "type": "string" }, { "description": "Industry: Medical Practices, Clinics, Hospitals & Health Care", "enum": [ "medical_practices_clinics_hospitals_health_care" ], "title": "Medical Practices Clinics Hospitals Health Care", "type": "string" }, { "description": "Industry: Military & Law Enforcement", "enum": [ "military_law_enforcement" ], "title": "Military Law Enforcement", "type": "string" }, { "description": "Industry: Mining, Minerals & Metals", "enum": [ "mining_minerals_metals" ], "title": "Mining Minerals Metals", "type": "string" }, { "description": "Industry: Motion Pictures & Film", "enum": [ "motion_pictures_and_film" ], "title": "Motion Pictures And Film", "type": "string" }, { "description": "Industry: Museums & Libraries", "enum": [ "museums_libraries" ], "title": "Museums Libraries", "type": "string" }, { "description": "Industry: Music & Art", "enum": [ "music_art" ], "title": "Music Art", "type": "string" }, { "description": "Industry: Newspapers", "enum": [ "newspapers" ], "title": "Newspapers", "type": "string" }, { "description": "Industry: Nonprofit", "enum": [ "nonprofit" ], "title": "Nonprofit", "type": "string" }, { "description": "Industry: Oil, Energy, Utilities & Waste", "enum": [ "oil_energy_utilities_waste" ], "title": "Oil Energy Utilities Waste", "type": "string" }, { "description": "Industry: Organizations & Local Business", "enum": [ "organizations_local_business" ], "title": "Organizations Local Business", "type": "string" }, { "description": "Industry: Outsourcing & Offshoring", "enum": [ "outsourcing_offshoring" ], "title": "Outsourcing Offshoring", "type": "string" }, { "description": "Industry: Pharmaceuticals, Biotechnology & Alternative Medicine", "enum": [ "pharmaceuticals_biotechnology_alternative_medicine" ], "title": "Pharmaceuticals Biotechnology Alternative Medicine", "type": "string" }, { "description": "Industry: Photographic & Optical Equipment", "enum": [ "photographic_optical_equipment" ], "title": "Photographic Optical Equipment", "type": "string" }, { "description": "Industry: Political Organization", "enum": [ "political_organization" ], "title": "Political Organization", "type": "string" }, { "description": "Industry: Print & Digital Media", "enum": [ "print_digital_media" ], "title": "Print Digital Media", "type": "string" }, { "description": "Industry: Professional Training & Coaching", "enum": [ "professional_training_coaching" ], "title": "Professional Training Coaching", "type": "string" }, { "description": "Industry: Real Estate", "enum": [ "real_estate" ], "title": "Real Estate", "type": "string" }, { "description": "Industry: Religious Institutions", "enum": [ "religious_institutions" ], "title": "Religious Institutions", "type": "string" }, { "description": "Industry: Renewables & Environment", "enum": [ "renewables_environment" ], "title": "Renewables Environment", "type": "string" }, { "description": "Industry: Research & Think Tanks", "enum": [ "research_think_tanks" ], "title": "Research Think Tanks", "type": "string" }, { "description": "Industry: Restaurants", "enum": [ "restaurants" ], "title": "Restaurants", "type": "string" }, { "description": "Industry: Retail", "enum": [ "retail" ], "title": "Retail", "type": "string" }, { "description": "Industry: Security Services & Investigations", "enum": [ "security_services_investigations" ], "title": "Security Services Investigations", "type": "string" }, { "description": "Industry: Social Impact & Community Services", "enum": [ "social_impact_and_community_services" ], "title": "Social Impact And Community Services", "type": "string" }, { "description": "Industry: Sporting Goods", "enum": [ "sporting_goods" ], "title": "Sporting Goods", "type": "string" }, { "description": "Industry: Supermarkets & Groceries", "enum": [ "supermarkets_groceries" ], "title": "Supermarkets Groceries", "type": "string" }, { "description": "Industry: Telecommunications Service Providers & Carriers", "enum": [ "telecommunications_service_providers_and_carriers" ], "title": "Telecommunications Service Providers And Carriers", "type": "string" }, { "description": "Industry: Transportation, Shipping, Packaging & Delivery", "enum": [ "transportation_shipping_packaging_delivery" ], "title": "Transportation Shipping Packaging Delivery", "type": "string" }, { "description": "Industry: Travel, Lodging & Hospitality", "enum": [ "travel_lodging_hospitality" ], "title": "Travel Lodging Hospitality", "type": "string" }, { "description": "Industry: Wholesale", "enum": [ "wholesale" ], "title": "Wholesale", "type": "string" } ] }, "industry_percentile": { "description": "Percentile ranking of this account's security posture within their industry (0-100). Null when industry is unknown/unsupported or benchmarks are unavailable.", "type": "number", "example": 75.5, "nullable": true }, "time_range": { "description": "Time range specification for reports and queries. Used to define the period of data to include in analysis.", "type": "object", "properties": { "end_time": { "description": "End timestamp for the time range (exclusive). Must be after start_time. Accepts ISO 8601 date strings or Date objects.", "type": "string", "format": "date-time", "example": "2024-01-08T00:00:00Z", "nullable": true }, "start_time": { "description": "Start timestamp for the time range (inclusive). Accepts ISO 8601 date strings or Date objects.", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z", "nullable": true } }, "required": [ "start_time", "end_time" ] }, "top_countries_by_mitigated_requests": { "description": "Countries that generated the most mitigated (blocked/challenged) requests", "type": "array", "items": { "properties": { "count": { "description": "Number of requests from this country.", "type": "integer", "example": 8934, "minimum": 0 }, "country_alpha2": { "description": "The ISO 3166-1 alpha-2 country code.", "type": "string", "example": "US", "maxLength": 2, "minLength": 2 } }, "required": [ "count", "country_alpha2" ], "type": "object" } }, "top_countries_by_served_requests": { "description": "Countries that generated the most legitimate (served) requests", "type": "array", "items": { "properties": { "count": { "description": "Number of requests from this country.", "type": "integer", "example": 8934, "minimum": 0 }, "country_alpha2": { "description": "The ISO 3166-1 alpha-2 country code.", "type": "string", "example": "US", "maxLength": 2, "minLength": 2 } }, "required": [ "count", "country_alpha2" ], "type": "object" } }, "top_hostnames_by_mitigated_requests": { "description": "Hostnames with the highest number of mitigated (blocked/challenged) requests", "type": "array", "items": { "properties": { "count": { "description": "Number of requests for this hostname.", "type": "integer", "example": 15420, "minimum": 0 }, "hostname": { "description": "The hostname that received requests.", "type": "string", "example": "api.example.com" } }, "required": [ "hostname", "count" ], "type": "object" } }, "top_rules_by_mitigated_requests": { "description": "Firewall rules that blocked or challenged the most requests", "type": "array", "items": { "properties": { "count": { "description": "Number of requests that triggered this firewall rule", "type": "integer", "example": 234, "minimum": 0 }, "description": { "description": "Human readable description of what this rule does", "type": "string", "example": "Block known malicious IPs" }, "kind": { "description": "The kind of the firewall rule.", "example": "custom", "anyOf": [ { "description": "The rule kind is unknown.", "enum": [ "unknown" ], "title": "Unknown", "type": "string" }, { "description": "A custom rule created by the user.", "enum": [ "custom" ], "title": "Custom", "type": "string" }, { "description": "A pre-defined rule managed by the system.", "enum": [ "managed" ], "title": "Managed", "type": "string" } ] }, "rule_id": { "description": "Unique identifier of the firewall rule", "type": "string", "example": "6183d67b5b5b4a07b87e7c7a" }, "ruleset_id": { "description": "Unique identifier of the ruleset containing this rule", "type": "string", "example": "efb7b8c949ac4650a09736fc" }, "source": { "description": "The source that triggered the firewall event.", "example": "waf", "anyOf": [ { "description": "Firewall Source: Unknown", "enum": [ "unknown" ], "title": "Unknown", "type": "string" }, { "description": "Firewall Source: ASN", "enum": [ "asn" ], "title": "Asn", "type": "string" }, { "description": "Firewall Source: Country", "enum": [ "country" ], "title": "Country", "type": "string" }, { "description": "Firewall Source: IP", "enum": [ "ip" ], "title": "Ip", "type": "string" }, { "description": "Firewall Source: IP Range", "enum": [ "ip_range" ], "title": "Ip Range", "type": "string" }, { "description": "Firewall Source: Security Level", "enum": [ "security_level" ], "title": "Security Level", "type": "string" }, { "description": "Firewall Source: Zone Lockdown", "enum": [ "zone_lockdown" ], "title": "Zone Lockdown", "type": "string" }, { "description": "Firewall Source: WAF", "enum": [ "waf" ], "title": "Waf", "type": "string" }, { "description": "Firewall Source: Firewall Rules", "enum": [ "firewall_rules" ], "title": "Firewall Rules", "type": "string" }, { "description": "Firewall Source: UA Block", "enum": [ "ua_block" ], "title": "Ua Block", "type": "string" }, { "description": "Firewall Source: Rate Limit", "enum": [ "rate_limit" ], "title": "Rate Limit", "type": "string" }, { "description": "Firewall Source: BIC", "enum": [ "bic" ], "title": "Bic", "type": "string" }, { "description": "Firewall Source: HOT", "enum": [ "hot" ], "title": "Hot", "type": "string" }, { "description": "Firewall Source: L7 DDOS", "enum": [ "l7_ddos" ], "title": "L7 Ddos", "type": "string" }, { "description": "Firewall Source: Validation", "enum": [ "validation" ], "title": "Validation", "type": "string" }, { "description": "Firewall Source: Bot Fight", "enum": [ "bot_fight" ], "title": "Bot Fight", "type": "string" }, { "description": "Firewall Source: API Shield", "enum": [ "api_shield" ], "title": "Api Shield", "type": "string" }, { "description": "Firewall Source: Bot Management", "enum": [ "bot_management" ], "title": "Bot Management", "type": "string" }, { "description": "Firewall Source: DLP", "enum": [ "dlp" ], "title": "Dlp", "type": "string" }, { "description": "Firewall Source: Firewall Managed", "enum": [ "firewall_managed" ], "title": "Firewall Managed", "type": "string" }, { "description": "Firewall Source: Firewall Custom", "enum": [ "firewall_custom" ], "title": "Firewall Custom", "type": "string" }, { "description": "Firewall Source: API Shield Schema Validation", "enum": [ "api_shield_schema_validation" ], "title": "Api Shield Schema Validation", "type": "string" }, { "description": "Firewall Source: API Shield Token Validation", "enum": [ "api_shield_token_validation" ], "title": "Api Shield Token Validation", "type": "string" }, { "description": "Firewall Source: API Shield Sequence Mitigation", "enum": [ "api_shield_sequence_mitigation" ], "title": "Api Shield Sequence Mitigation", "type": "string" } ] } }, "required": [ "count", "rule_id", "ruleset_id", "description", "source", "kind" ], "type": "object" } }, "total_requests": { "description": "Summary statistics for request counts with optional period-over-period comparison", "type": "object", "properties": { "count": { "description": "Total count of requests.", "type": "integer", "example": 1250000, "minimum": 0 }, "percent_change": { "description": "Percentage change from the previous period (positive = increase, negative = decrease).", "type": "number", "example": 15.3 } }, "required": [ "count" ] }, "total_requests_mitigated": { "description": "Summary statistics for request counts with optional period-over-period comparison", "type": "object", "properties": { "count": { "description": "Total count of requests.", "type": "integer", "example": 1250000, "minimum": 0 }, "percent_change": { "description": "Percentage change from the previous period (positive = increase, negative = decrease).", "type": "number", "example": 15.3 } }, "required": [ "count" ] }, "total_requests_served": { "description": "Summary statistics for request counts with optional period-over-period comparison", "type": "object", "properties": { "count": { "description": "Total count of requests.", "type": "integer", "example": 1250000, "minimum": 0 }, "percent_change": { "description": "Percentage change from the previous period (positive = increase, negative = decrease).", "type": "number", "example": 15.3 } }, "required": [ "count" ] }, "total_zones": { "description": "Total number of zones (domains) in this account", "type": "integer", "example": 25, "minimum": 0 }, "total_zones_analyzed": { "description": "Number of zones that were included in this security analysis", "type": "integer", "example": 23, "minimum": 0 } }, "required": [ "account_id", "account_name", "time_range", "total_zones", "total_zones_analyzed", "industry", "industry_percentile", "total_requests", "total_requests_mitigated", "total_requests_served", "top_hostnames_by_mitigated_requests", "top_countries_by_served_requests", "top_countries_by_mitigated_requests", "top_rules_by_mitigated_requests" ] }, "reports_Error": { "type": "object", "properties": { "code": { "type": "number", "example": 10000 }, "message": { "type": "string", "example": "Authentication error" } }, "required": [ "code", "message" ] }, "reports_GetReportResponse": { "type": "object", "properties": { "generated_on": { "description": "When this report was actually completed (only present when report is finished)", "type": "string", "example": "2024-01-15T09:05:23Z", "nullable": true }, "generation_id": { "description": "Unique identifier for this generation attempt (for retry/deduplication)", "type": "string", "format": "uuid", "example": "c3d4e5f6-g7h8-9012-cdef-345678901234" }, "policy_id": { "description": "Reference to the policy that generated this report", "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "policy_version": { "description": "Version of the policy that was used to generate this report (positive integer starting at 1)", "type": "integer", "example": 1, "exclusiveMinimum": true, "minimum": 0 }, "reason": { "description": "Optional reason enum providing additional context about the report status (e.g., cancellation reason, error details)", "example": "invalid_entitlements", "anyOf": [ { "description": "No specific reason provided.", "enum": [ "unspecified" ], "title": "Unspecified", "type": "string" }, { "description": "Report cancelled due to invalid or missing entitlements (e.g., no zones analyzed).", "enum": [ "invalid_entitlements" ], "title": "Invalid Entitlements", "type": "string" }, { "description": "Report cancelled because the policy was disabled.", "enum": [ "policy_disabled" ], "title": "Policy Disabled", "type": "string" } ] }, "report": { "description": "The actual report data and findings", "oneOf": [ { "properties": { "type": { "description": "Type identifier for Application Security Report V1", "type": "string", "enum": [ "application_security_report_v1" ] }, "value": { "$ref": "#/components/schemas/reports_ApplicationSecurityReportV1" } }, "required": [ "type", "value" ], "type": "object" } ] }, "report_id": { "description": "Unique identifier for this specific report instance", "type": "string", "format": "uuid", "example": "b2c3d4e5-f6g7-8901-bcde-f23456789012" }, "report_settings": { "description": "Configuration settings used to generate this report, including report type and parameters (may be missing for older reports)", "discriminator": { "propertyName": "type" }, "oneOf": [ { "description": "Configuration for Application Security Report with time range analysis", "properties": { "type": { "type": "string", "enum": [ "application_security_report_v1" ] }, "value": { "type": "object", "properties": { "time_range": { "description": "Time range that the report covers", "properties": { "end_time": { "description": "End timestamp for the time range (exclusive). Must be after start_time. Accepts ISO 8601 date strings or Date objects.", "type": "string", "format": "date-time", "example": "2024-01-08T00:00:00Z", "nullable": true }, "start_time": { "description": "Start timestamp for the time range (inclusive). Accepts ISO 8601 date strings or Date objects.", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z", "nullable": true } }, "required": [ "start_time", "end_time" ], "type": "object" } }, "required": [ "time_range" ] } }, "required": [ "type", "value" ], "title": "Application Security Report V1 Settings", "type": "object" } ], "title": "Report Settings" }, "report_status": { "description": "The generation status of the report.", "example": "scheduled", "anyOf": [ { "description": "The report status is unspecified.", "enum": [ "unspecified" ], "title": "Unspecified", "type": "string" }, { "description": "The report is scheduled for generation.", "enum": [ "scheduled" ], "title": "Scheduled", "type": "string" }, { "description": "The report is currently being generated.", "enum": [ "generating" ], "title": "Generating", "type": "string" }, { "description": "The report has finished generating.", "enum": [ "finished" ], "title": "Finished", "type": "string" }, { "description": "The report was cancelled and will not be generated.", "enum": [ "cancelled" ], "title": "Cancelled", "type": "string" } ] }, "scheduled_for": { "description": "When this report should actually run (execution timestamp)", "type": "string", "format": "date-time", "example": "2024-01-15T09:00:00Z", "nullable": true }, "scheduled_on": { "description": "When this report was scheduled (creation timestamp)", "type": "string", "format": "date-time", "example": "2024-01-15T08:30:00Z", "nullable": true } }, "nullable": true, "required": [ "report_id", "generation_id", "report_status", "policy_id", "policy_version", "scheduled_on", "scheduled_for", "report" ] }, "reports_Message": { "type": "object", "properties": { "code": { "type": "number", "example": 10000 }, "message": { "type": "string", "example": "This is an example message" } }, "required": [ "code", "message" ] }, "reports_PatchAccountIndustryBody": { "type": "object", "properties": { "industry": { "description": "The industry of the account", "example": "internet", "anyOf": [ { "description": "Industry: Accounting", "enum": [ "accounting" ], "title": "Accounting", "type": "string" }, { "description": "Industry: Adult Entertainment", "enum": [ "adult_entertainment" ], "title": "Adult Entertainment", "type": "string" }, { "description": "Industry: Agriculture", "enum": [ "agriculture" ], "title": "Agriculture", "type": "string" }, { "description": "Industry: Airlines, Aviation & Aerospace", "enum": [ "airlines_aviation_aerospace" ], "title": "Airlines Aviation Aerospace", "type": "string" }, { "description": "Industry: Animation & Design", "enum": [ "animation_design" ], "title": "Animation Design", "type": "string" }, { "description": "Industry: Apparel & Fashion", "enum": [ "apparel_fashion" ], "title": "Apparel Fashion", "type": "string" }, { "description": "Industry: Architecture & Planning", "enum": [ "architecture_planning" ], "title": "Architecture Planning", "type": "string" }, { "description": "Industry: Automotive", "enum": [ "automotive" ], "title": "Automotive", "type": "string" }, { "description": "Industry: Banking & Financial Services", "enum": [ "banking_financial_services" ], "title": "Banking Financial Services", "type": "string" }, { "description": "Industry: Broadcast Media", "enum": [ "broadcast_media" ], "title": "Broadcast Media", "type": "string" }, { "description": "Industry: Building Materials & Construction", "enum": [ "building_materials_construction" ], "title": "Building Materials Construction", "type": "string" }, { "description": "Industry: Business Services, Supplies & Equipment", "enum": [ "business_services_supplies_equipment" ], "title": "Business Services Supplies Equipment", "type": "string" }, { "description": "Industry: Computer Hardware", "enum": [ "computer_hardware" ], "title": "Computer Hardware", "type": "string" }, { "description": "Industry: Computer Software", "enum": [ "computer_software" ], "title": "Computer Software", "type": "string" }, { "description": "Industry: Construction & Civil Engineering", "enum": [ "construction_civil_engineering" ], "title": "Construction Civil Engineering", "type": "string" }, { "description": "Industry: Consumer Electronics", "enum": [ "consumer_electronics" ], "title": "Consumer Electronics", "type": "string" }, { "description": "Industry: Consumer Goods", "enum": [ "consumer_goods" ], "title": "Consumer Goods", "type": "string" }, { "description": "Industry: Consumer Services", "enum": [ "consumer_services" ], "title": "Consumer Services", "type": "string" }, { "description": "Industry: Cosmetics", "enum": [ "cosmetics" ], "title": "Cosmetics", "type": "string" }, { "description": "Industry: Cryptocurrency", "enum": [ "cryptocurrency" ], "title": "Cryptocurrency", "type": "string" }, { "description": "Industry: Cyber Security", "enum": [ "cyber_security" ], "title": "Cyber Security", "type": "string" }, { "description": "Industry: Defense & Space", "enum": [ "defense_space" ], "title": "Defense Space", "type": "string" }, { "description": "Industry: E-Learning", "enum": [ "e_learning" ], "title": "E Learning", "type": "string" }, { "description": "Industry: Education & Academia", "enum": [ "education_academia" ], "title": "Education Academia", "type": "string" }, { "description": "Industry: Education Management", "enum": [ "education_management" ], "title": "Education Management", "type": "string" }, { "description": "Industry: Entertainment", "enum": [ "entertainment" ], "title": "Entertainment", "type": "string" }, { "description": "Industry: Environmental Services", "enum": [ "environmental_services" ], "title": "Environmental Services", "type": "string" }, { "description": "Industry: Events Services", "enum": [ "events_services" ], "title": "Events Services", "type": "string" }, { "description": "Industry: Facilities Services", "enum": [ "facilities_services" ], "title": "Facilities Services", "type": "string" }, { "description": "Industry: Fine Art, Luxury Goods & Jewelry", "enum": [ "fine_art_luxury_goods_jewelry" ], "title": "Fine Art Luxury Goods Jewelry", "type": "string" }, { "description": "Industry: Food & Beverage", "enum": [ "food_beverage" ], "title": "Food Beverage", "type": "string" }, { "description": "Industry: Furniture", "enum": [ "furniture" ], "title": "Furniture", "type": "string" }, { "description": "Industry: Gambling & Casinos", "enum": [ "gambling_casinos" ], "title": "Gambling Casinos", "type": "string" }, { "description": "Industry: Gaming", "enum": [ "gaming" ], "title": "Gaming", "type": "string" }, { "description": "Industry: Government", "enum": [ "government" ], "title": "Government", "type": "string" }, { "description": "Industry: Health, Wellness & Fitness", "enum": [ "health_wellness_fitness" ], "title": "Health Wellness Fitness", "type": "string" }, { "description": "Industry: Holding Companies & Conglomerates", "enum": [ "holding_companies_conglomerates" ], "title": "Holding Companies Conglomerates", "type": "string" }, { "description": "Industry: Human Resources, Staffing & Recruiting", "enum": [ "human_resources_staffing_recruiting" ], "title": "Human Resources Staffing Recruiting", "type": "string" }, { "description": "Industry: Information Technology & Services", "enum": [ "information_technology_services" ], "title": "Information Technology Services", "type": "string" }, { "description": "Industry: Insurance", "enum": [ "insurance" ], "title": "Insurance", "type": "string" }, { "description": "Industry: International Public Affairs", "enum": [ "international_public_affairs" ], "title": "International Public Affairs", "type": "string" }, { "description": "Industry: International Trade & Development", "enum": [ "international_trade_development" ], "title": "International Trade Development", "type": "string" }, { "description": "Industry: Internet", "enum": [ "internet" ], "title": "Internet", "type": "string" }, { "description": "Industry: Investment Management", "enum": [ "investment_management" ], "title": "Investment Management", "type": "string" }, { "description": "Industry: Law Firms & Legal Services", "enum": [ "law_firms_legal_services" ], "title": "Law Firms Legal Services", "type": "string" }, { "description": "Industry: Leisure, Travel & Tourism", "enum": [ "leisure_travel_tourism" ], "title": "Leisure Travel Tourism", "type": "string" }, { "description": "Industry: Logistics, Supply Chain, Import & Export", "enum": [ "logistics_supply_chain_import_export" ], "title": "Logistics Supply Chain Import Export", "type": "string" }, { "description": "Industry: Management Consulting", "enum": [ "management_consulting" ], "title": "Management Consulting", "type": "string" }, { "description": "Industry: Manufacturing, Machinery, Technology & Engineering", "enum": [ "manufacturing_machinery_technology_engineering" ], "title": "Manufacturing Machinery Technology Engineering", "type": "string" }, { "description": "Industry: Maritime", "enum": [ "maritime" ], "title": "Maritime", "type": "string" }, { "description": "Industry: Market Research", "enum": [ "market_research" ], "title": "Market Research", "type": "string" }, { "description": "Industry: Marketing & Advertising", "enum": [ "marketing_advertising" ], "title": "Marketing Advertising", "type": "string" }, { "description": "Industry: Media Production & Publishing", "enum": [ "media_production_publishing" ], "title": "Media Production Publishing", "type": "string" }, { "description": "Industry: Medical Devices, Healthcare Software & Services", "enum": [ "medical_devices_healthcare_software_services" ], "title": "Medical Devices Healthcare Software Services", "type": "string" }, { "description": "Industry: Medical Practices, Clinics, Hospitals & Health Care", "enum": [ "medical_practices_clinics_hospitals_health_care" ], "title": "Medical Practices Clinics Hospitals Health Care", "type": "string" }, { "description": "Industry: Military & Law Enforcement", "enum": [ "military_law_enforcement" ], "title": "Military Law Enforcement", "type": "string" }, { "description": "Industry: Mining, Minerals & Metals", "enum": [ "mining_minerals_metals" ], "title": "Mining Minerals Metals", "type": "string" }, { "description": "Industry: Motion Pictures & Film", "enum": [ "motion_pictures_and_film" ], "title": "Motion Pictures And Film", "type": "string" }, { "description": "Industry: Museums & Libraries", "enum": [ "museums_libraries" ], "title": "Museums Libraries", "type": "string" }, { "description": "Industry: Music & Art", "enum": [ "music_art" ], "title": "Music Art", "type": "string" }, { "description": "Industry: Newspapers", "enum": [ "newspapers" ], "title": "Newspapers", "type": "string" }, { "description": "Industry: Nonprofit", "enum": [ "nonprofit" ], "title": "Nonprofit", "type": "string" }, { "description": "Industry: Oil, Energy, Utilities & Waste", "enum": [ "oil_energy_utilities_waste" ], "title": "Oil Energy Utilities Waste", "type": "string" }, { "description": "Industry: Organizations & Local Business", "enum": [ "organizations_local_business" ], "title": "Organizations Local Business", "type": "string" }, { "description": "Industry: Outsourcing & Offshoring", "enum": [ "outsourcing_offshoring" ], "title": "Outsourcing Offshoring", "type": "string" }, { "description": "Industry: Pharmaceuticals, Biotechnology & Alternative Medicine", "enum": [ "pharmaceuticals_biotechnology_alternative_medicine" ], "title": "Pharmaceuticals Biotechnology Alternative Medicine", "type": "string" }, { "description": "Industry: Photographic & Optical Equipment", "enum": [ "photographic_optical_equipment" ], "title": "Photographic Optical Equipment", "type": "string" }, { "description": "Industry: Political Organization", "enum": [ "political_organization" ], "title": "Political Organization", "type": "string" }, { "description": "Industry: Print & Digital Media", "enum": [ "print_digital_media" ], "title": "Print Digital Media", "type": "string" }, { "description": "Industry: Professional Training & Coaching", "enum": [ "professional_training_coaching" ], "title": "Professional Training Coaching", "type": "string" }, { "description": "Industry: Real Estate", "enum": [ "real_estate" ], "title": "Real Estate", "type": "string" }, { "description": "Industry: Religious Institutions", "enum": [ "religious_institutions" ], "title": "Religious Institutions", "type": "string" }, { "description": "Industry: Renewables & Environment", "enum": [ "renewables_environment" ], "title": "Renewables Environment", "type": "string" }, { "description": "Industry: Research & Think Tanks", "enum": [ "research_think_tanks" ], "title": "Research Think Tanks", "type": "string" }, { "description": "Industry: Restaurants", "enum": [ "restaurants" ], "title": "Restaurants", "type": "string" }, { "description": "Industry: Retail", "enum": [ "retail" ], "title": "Retail", "type": "string" }, { "description": "Industry: Security Services & Investigations", "enum": [ "security_services_investigations" ], "title": "Security Services Investigations", "type": "string" }, { "description": "Industry: Social Impact & Community Services", "enum": [ "social_impact_and_community_services" ], "title": "Social Impact And Community Services", "type": "string" }, { "description": "Industry: Sporting Goods", "enum": [ "sporting_goods" ], "title": "Sporting Goods", "type": "string" }, { "description": "Industry: Supermarkets & Groceries", "enum": [ "supermarkets_groceries" ], "title": "Supermarkets Groceries", "type": "string" }, { "description": "Industry: Telecommunications Service Providers & Carriers", "enum": [ "telecommunications_service_providers_and_carriers" ], "title": "Telecommunications Service Providers And Carriers", "type": "string" }, { "description": "Industry: Transportation, Shipping, Packaging & Delivery", "enum": [ "transportation_shipping_packaging_delivery" ], "title": "Transportation Shipping Packaging Delivery", "type": "string" }, { "description": "Industry: Travel, Lodging & Hospitality", "enum": [ "travel_lodging_hospitality" ], "title": "Travel Lodging Hospitality", "type": "string" }, { "description": "Industry: Wholesale", "enum": [ "wholesale" ], "title": "Wholesale", "type": "string" } ] } }, "required": [ "industry" ] }, "reports_PoliciesListResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/reports_Error" }, "default": [] }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/reports_Message" }, "default": [] }, "result": { "type": "array", "items": { "properties": { "enabled": { "description": "Whether the policy is currently active and will generate reports according to schedule", "type": "boolean", "example": true }, "policy_description": { "description": "Optional detailed description of what the policy does and when it runs", "type": "string", "example": "Generates a comprehensive security report every Monday covering firewall events and threat analysis", "default": "" }, "policy_id": { "description": "Unique identifier for the policy (UUID format)", "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "policy_name": { "description": "Human-readable name for the policy (required, non-empty)", "type": "string", "example": "Weekly Security Report", "minLength": 1 }, "policy_schedule": { "description": "Cron expression for scheduling (format: minute hour day month weekday). Example: '0 9 * * 1' runs every Monday at 9:00 AM", "type": "string", "example": "0 9 * * 1", "pattern": "^(\\*|([0-9]|1[0-9]|2[0-9]|3[0-9]|4[0-9]|5[0-9])|\\*\\/[0-9]+)\\s+(\\*|([0-9]|1[0-9]|2[0-3])|\\*\\/[0-9]+)\\s+(\\*|([1-9]|1[0-9]|2[0-9]|3[0-1])|\\*\\/[0-9]+)\\s+(\\*|([1-9]|1[0-2])|\\*\\/[0-9]+)\\s+(\\*|[0-6]|\\*\\/[0-9]+)$" }, "valid_from": { "description": "Start date when this policy version becomes effective", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z", "nullable": true }, "valid_to": { "description": "End date when this policy version expires (omitted for active policies)", "type": "string", "format": "date-time", "example": "2024-12-31T23:59:59Z", "nullable": true }, "version": { "description": "Version number of the policy (incremented when policy is modified, starts at 1)", "type": "integer", "example": 1, "exclusiveMinimum": true, "minimum": 0 } }, "required": [ "policy_id", "policy_name", "policy_schedule", "enabled", "version", "valid_from" ], "type": "object" }, "nullable": true }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result" ] }, "reports_PolicyErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/reports_Error" } }, "messages": { "type": "array", "items": { "nullable": true }, "default": [] }, "result": { "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "success", "errors", "result" ] }, "reports_PolicySingleResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/reports_Error" }, "default": [] }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/reports_Message" }, "default": [] }, "result": { "type": "object", "nullable": true, "properties": { "enabled": { "description": "Whether the policy is currently active and will generate reports according to schedule", "type": "boolean", "example": true }, "policy_description": { "description": "Optional detailed description of what the policy does and when it runs", "type": "string", "example": "Generates a comprehensive security report every Monday covering firewall events and threat analysis", "default": "" }, "policy_id": { "description": "Unique identifier for the policy (UUID format)", "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "policy_name": { "description": "Human-readable name for the policy (required, non-empty)", "type": "string", "example": "Weekly Security Report", "minLength": 1 }, "policy_schedule": { "description": "Cron expression for scheduling (format: minute hour day month weekday). Example: '0 9 * * 1' runs every Monday at 9:00 AM", "type": "string", "example": "0 9 * * 1", "pattern": "^(\\*|([0-9]|1[0-9]|2[0-9]|3[0-9]|4[0-9]|5[0-9])|\\*\\/[0-9]+)\\s+(\\*|([0-9]|1[0-9]|2[0-3])|\\*\\/[0-9]+)\\s+(\\*|([1-9]|1[0-9]|2[0-9]|3[0-1])|\\*\\/[0-9]+)\\s+(\\*|([1-9]|1[0-2])|\\*\\/[0-9]+)\\s+(\\*|[0-6]|\\*\\/[0-9]+)$" }, "valid_from": { "description": "Start date when this policy version becomes effective", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z", "nullable": true }, "valid_to": { "description": "End date when this policy version expires (omitted for active policies)", "type": "string", "format": "date-time", "example": "2024-12-31T23:59:59Z", "nullable": true }, "version": { "description": "Version number of the policy (incremented when policy is modified, starts at 1)", "type": "integer", "example": 1, "exclusiveMinimum": true, "minimum": 0 } }, "required": [ "policy_id", "policy_name", "policy_schedule", "enabled", "version", "valid_from" ] }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result" ] }, "reports_ReportSingleResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/reports_Error" }, "default": [] }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/reports_Message" }, "default": [] }, "result": { "$ref": "#/components/schemas/reports_GetReportResponse" }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result" ] }, "reports_ReportsListResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/reports_Error" }, "default": [] }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/reports_Message" }, "default": [] }, "result": { "type": "array", "items": { "properties": { "generated_on": { "description": "When this report was actually completed (only present when report is finished)", "type": "string", "example": "2024-01-15T09:05:23Z", "nullable": true }, "generation_id": { "description": "Unique identifier for this generation attempt (for retry/deduplication)", "type": "string", "format": "uuid", "example": "c3d4e5f6-g7h8-9012-cdef-345678901234" }, "policy_id": { "description": "Reference to the policy that generated this report", "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "policy_version": { "description": "Version of the policy that was used to generate this report (positive integer starting at 1)", "type": "integer", "example": 1, "exclusiveMinimum": true, "minimum": 0 }, "reason": { "description": "Optional reason enum providing additional context about the report status (e.g., cancellation reason, error details)", "example": "invalid_entitlements", "anyOf": [ { "description": "No specific reason provided.", "enum": [ "unspecified" ], "title": "Unspecified", "type": "string" }, { "description": "Report cancelled due to invalid or missing entitlements (e.g., no zones analyzed).", "enum": [ "invalid_entitlements" ], "title": "Invalid Entitlements", "type": "string" }, { "description": "Report cancelled because the policy was disabled.", "enum": [ "policy_disabled" ], "title": "Policy Disabled", "type": "string" } ] }, "report_id": { "description": "Unique identifier for this specific report instance", "type": "string", "format": "uuid", "example": "b2c3d4e5-f6g7-8901-bcde-f23456789012" }, "report_settings": { "description": "Configuration settings used to generate this report, including report type and parameters (may be missing for older reports)", "discriminator": { "propertyName": "type" }, "oneOf": [ { "description": "Configuration for Application Security Report with time range analysis", "properties": { "type": { "type": "string", "enum": [ "application_security_report_v1" ] }, "value": { "type": "object", "properties": { "time_range": { "description": "Time range that the report covers", "properties": { "end_time": { "description": "End timestamp for the time range (exclusive). Must be after start_time. Accepts ISO 8601 date strings or Date objects.", "type": "string", "format": "date-time", "example": "2024-01-08T00:00:00Z", "nullable": true }, "start_time": { "description": "Start timestamp for the time range (inclusive). Accepts ISO 8601 date strings or Date objects.", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z", "nullable": true } }, "required": [ "start_time", "end_time" ], "type": "object" } }, "required": [ "time_range" ] } }, "required": [ "type", "value" ], "title": "Application Security Report V1 Settings", "type": "object" } ], "title": "Report Settings" }, "report_status": { "description": "The generation status of the report.", "example": "scheduled", "anyOf": [ { "description": "The report status is unspecified.", "enum": [ "unspecified" ], "title": "Unspecified", "type": "string" }, { "description": "The report is scheduled for generation.", "enum": [ "scheduled" ], "title": "Scheduled", "type": "string" }, { "description": "The report is currently being generated.", "enum": [ "generating" ], "title": "Generating", "type": "string" }, { "description": "The report has finished generating.", "enum": [ "finished" ], "title": "Finished", "type": "string" }, { "description": "The report was cancelled and will not be generated.", "enum": [ "cancelled" ], "title": "Cancelled", "type": "string" } ] }, "scheduled_for": { "description": "When this report should actually run (execution timestamp)", "type": "string", "format": "date-time", "example": "2024-01-15T09:00:00Z", "nullable": true }, "scheduled_on": { "description": "When this report was scheduled (creation timestamp)", "type": "string", "format": "date-time", "example": "2024-01-15T08:30:00Z", "nullable": true } }, "required": [ "report_id", "generation_id", "report_status", "policy_id", "policy_version", "scheduled_on", "scheduled_for" ], "type": "object" }, "nullable": true }, "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success", "result" ] }, "request-tracer_account_identifier": { "$ref": "#/components/schemas/request-tracer_identifier" }, "request-tracer_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/request-tracer_messages" }, "messages": { "$ref": "#/components/schemas/request-tracer_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "request-tracer_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/request-tracer_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/request-tracer_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "request-tracer_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "request-tracer_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "request-tracer_trace": { "type": "array", "items": { "description": "List of steps acting on request/response", "properties": { "action": { "description": "If step type is rule, then action performed by this rule", "type": "string", "example": "execute", "pattern": "^[a-z_]+$", "x-auditable": true }, "action_parameters": { "description": "If step type is rule, then action parameters of this rule as JSON", "type": "object", "example": { "id": "4814384a9e5d4991b9815dcfc25d2f1f" }, "x-auditable": true }, "description": { "description": "If step type is rule or ruleset, the description of this entity", "type": "string", "example": "some rule", "x-auditable": true }, "expression": { "description": "If step type is rule, then expression used to match for this rule", "type": "string", "example": "ip.src ne 1.1.1.1", "x-auditable": true }, "kind": { "description": "If step type is ruleset, then kind of this ruleset", "type": "string", "example": "zone", "x-auditable": true }, "matched": { "description": "Whether tracing step affected tracing request/response", "type": "boolean", "example": true, "x-auditable": true }, "name": { "description": "If step type is ruleset, then name of this ruleset", "type": "string", "example": "some ruleset name", "x-auditable": true }, "step_name": { "description": "Tracing step identifying name", "type": "string", "example": "rule_id01", "x-auditable": true }, "trace": { "$ref": "#/components/schemas/request-tracer_trace" }, "type": { "description": "Tracing step type", "type": "string", "example": "rule", "x-auditable": true } }, "type": "object" } }, "resource-sharing_account_id": { "description": "Account identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "resource-sharing_account_name": { "description": "The display name of an account.", "type": "string", "example": "Account A", "x-auditable": true }, "resource-sharing_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/resource-sharing_api-response-common" }, { "properties": { "result": { "type": "array", "items": {}, "nullable": true }, "result_info": { "$ref": "#/components/schemas/resource-sharing_result_info" } } } ] }, "resource-sharing_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/resource-sharing_v4errors" }, "result": { "anyOf": [ { "type": "object" }, { "items": {}, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true } }, "required": [ "success", "errors" ] }, "resource-sharing_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/resource-sharing_v4errors" } ], "minLength": 1 }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "x-auditable": true } }, "required": [ "success", "errors", "result" ] }, "resource-sharing_create_share_excluded_recipient_request": { "type": "object", "properties": { "account_id": { "description": "The account to exclude from the organization-targeted share.", "allOf": [ { "$ref": "#/components/schemas/resource-sharing_account_id" } ] } }, "required": [ "account_id" ] }, "resource-sharing_create_share_recipient_request": { "description": "Optionally specify `recipient_account_id` to target a specific account, or `organization_id` to target the caller's whole organization. If neither is provided, the caller's organization is used.\nThe legacy field `account_id` is accepted as a synonym for `recipient_account_id` during the deprecation period (see `x-sunset` on that field).\n", "type": "object", "properties": { "account_id": { "description": "Deprecated alias for `recipient_account_id`. Use `recipient_account_id` instead.\nThe body field collided with the URL path parameter of the same name, which prevented SDK generators from distinguishing the source account (in the URL) from the recipient account (in the body). Both names will continue to be accepted until 2027-05-26 (see `x-sunset`).\n", "allOf": [ { "$ref": "#/components/schemas/resource-sharing_account_id" } ], "deprecated": true, "x-stainless-deprecation-message": "This field has been renamed to `recipient_account_id`. Both names are accepted during the deprecation period.", "x-stainless-skip": [ "terraform" ] }, "organization_id": { "$ref": "#/components/schemas/resource-sharing_organization_id" }, "recipient_account_id": { "description": "The account that will receive the share.", "allOf": [ { "$ref": "#/components/schemas/resource-sharing_account_id" } ] } } }, "resource-sharing_create_share_request": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/resource-sharing_share_name" }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/resource-sharing_create_share_recipient_request" } }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/resource-sharing_create_share_resource_request" } } }, "required": [ "name", "resources", "recipients" ] }, "resource-sharing_create_share_resource_request": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/resource-sharing_resource_meta" }, "resource_account_id": { "$ref": "#/components/schemas/resource-sharing_account_id" }, "resource_id": { "$ref": "#/components/schemas/resource-sharing_resource_resource_id" }, "resource_type": { "$ref": "#/components/schemas/resource-sharing_resource_type" } }, "required": [ "resource_id", "resource_type", "resource_account_id", "meta" ] }, "resource-sharing_created": { "description": "When the share was created.", "type": "string", "format": "date-time", "example": "2023-09-21T18:56:32.624632Z", "x-auditable": true }, "resource-sharing_excluded_recipient_id": { "description": "Share Excluded Recipient identifier tag.", "type": "string", "example": "4ae96b85c43850f2c0a7b9101a0eeb18", "maxLength": 32, "x-auditable": true }, "resource-sharing_modified": { "description": "When the share was modified.", "type": "string", "format": "date-time", "example": "2023-09-21T18:56:32.624632Z", "x-auditable": true }, "resource-sharing_organization_id": { "description": "Organization identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "resource-sharing_recipient_association_status": { "description": "The current state of the recipient relative to the share. The\n`desired_association_status` (not exposed in the response) tracks the\ntarget state set by the API; the background reconciliation workflow\ndrives `current_association_status` toward it.\n\n- `associating` — The recipient was recently added; the workflow is\n pushing shared resources into the recipient account.\n- `associated` — Shared resources have been successfully applied to\n the recipient account.\n- `disassociating` — The recipient was removed (via DELETE or PUT\n replacement); the workflow is removing shared resources from the\n recipient account.\n- `disassociated` — Shared resources have been removed from the\n recipient account. The recipient record remains in the database.\n", "type": "string", "enum": [ "associating", "associated", "disassociating", "disassociated" ], "x-auditable": true }, "resource-sharing_recipient_id": { "description": "Share Recipient identifier tag.", "type": "string", "example": "3fd85f74b32742f1bff64a85009dda07", "maxLength": 32, "x-auditable": true }, "resource-sharing_recipient_resource_error": { "description": "Share Recipient error message.", "type": "string", "example": "Recipient is missing necessary entitlement", "x-auditable": true }, "resource-sharing_recipient_resource_error_terminal": { "description": "Whether the error is terminal or will be continually retried.", "type": "boolean", "example": true, "x-auditable": true }, "resource-sharing_resource_id": { "description": "Share Resource identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "resource-sharing_resource_meta": { "description": "Resource Metadata.", "type": "object" }, "resource-sharing_resource_resource_id": { "description": "Share Resource identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "resource-sharing_resource_status": { "description": "Resource Status.", "type": "string", "enum": [ "active", "deleting", "deleted" ], "x-auditable": true }, "resource-sharing_resource_type": { "description": "Resource Type.", "type": "string", "enum": [ "custom-ruleset", "gateway-policy", "gateway-destination-ip", "gateway-block-page-settings", "gateway-extended-email-matching", "idp-federation-grant", "trust-grant" ], "x-auditable": true }, "resource-sharing_resource_version": { "description": "Resource Version.", "type": "integer", "x-auditable": true }, "resource-sharing_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "Total number of pages using the given per page.", "type": "number", "example": 50 } } }, "resource-sharing_share_excluded_recipient_object": { "properties": { "account_id": { "$ref": "#/components/schemas/resource-sharing_account_id" }, "created": { "$ref": "#/components/schemas/resource-sharing_created" }, "id": { "$ref": "#/components/schemas/resource-sharing_excluded_recipient_id" }, "modified": { "$ref": "#/components/schemas/resource-sharing_modified" } }, "required": [ "id", "account_id", "created", "modified" ] }, "resource-sharing_share_excluded_recipient_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/resource-sharing_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/resource-sharing_share_excluded_recipient_object" } } } } ] }, "resource-sharing_share_excluded_recipient_response_single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/resource-sharing_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/resource-sharing_share_excluded_recipient_object" } } } ] }, "resource-sharing_share_id": { "description": "Share identifier tag.", "type": "string", "example": "3fd85f74b32742f1bff64a85009dda07", "maxLength": 32, "x-auditable": true }, "resource-sharing_share_kind": { "type": "string", "enum": [ "sent", "received" ], "x-auditable": true }, "resource-sharing_share_name": { "description": "The name of the share.", "type": "string", "example": "My Shared WAF Managed Rule", "x-auditable": true }, "resource-sharing_share_object": { "properties": { "account_id": { "$ref": "#/components/schemas/resource-sharing_account_id" }, "account_name": { "$ref": "#/components/schemas/resource-sharing_account_name" }, "associated_recipient_count": { "description": "The number of recipients in the 'associated' state. This field is only included when requested via the 'include_recipient_counts' parameter.", "type": "integer", "example": 10 }, "associating_recipient_count": { "description": "The number of recipients in the 'associating' state. This field is only included when requested via the 'include_recipient_counts' parameter.", "type": "integer", "example": 1 }, "created": { "$ref": "#/components/schemas/resource-sharing_created" }, "disassociated_recipient_count": { "description": "The number of recipients in the 'disassociated' state. This field is only included when requested via the 'include_recipient_counts' parameter.", "type": "integer", "example": 0 }, "disassociating_recipient_count": { "description": "The number of recipients in the 'disassociating' state. This field is only included when requested via the 'include_recipient_counts' parameter.", "type": "integer", "example": 0 }, "id": { "$ref": "#/components/schemas/resource-sharing_share_id" }, "kind": { "$ref": "#/components/schemas/resource-sharing_share_kind" }, "modified": { "$ref": "#/components/schemas/resource-sharing_modified" }, "name": { "$ref": "#/components/schemas/resource-sharing_share_name" }, "organization_id": { "$ref": "#/components/schemas/resource-sharing_organization_id" }, "resources": { "description": "A list of resources that are part of the share. This field is only included when requested via the 'include_resources' parameter.", "type": "array", "items": { "$ref": "#/components/schemas/resource-sharing_share_resource_object" } }, "status": { "$ref": "#/components/schemas/resource-sharing_share_status" }, "target_type": { "$ref": "#/components/schemas/resource-sharing_share_target_type" } }, "required": [ "id", "name", "account_id", "account_name", "organization_id", "created", "modified", "status", "target_type" ] }, "resource-sharing_share_recipient_object": { "description": "A recipient of a share. The `association_status` field tracks the\nlifecycle of the shared resources in the recipient account. All\nrecipients are returned by the list endpoint regardless of status;\nfilter client-side if only active recipients are needed.\n", "properties": { "account_id": { "$ref": "#/components/schemas/resource-sharing_account_id" }, "association_status": { "$ref": "#/components/schemas/resource-sharing_recipient_association_status" }, "created": { "$ref": "#/components/schemas/resource-sharing_created" }, "id": { "$ref": "#/components/schemas/resource-sharing_recipient_id" }, "modified": { "$ref": "#/components/schemas/resource-sharing_modified" }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/resource-sharing_share_recipient_resource_object" } } }, "required": [ "id", "account_id", "association_status", "created", "modified" ] }, "resource-sharing_share_recipient_resource_object": { "properties": { "error": { "$ref": "#/components/schemas/resource-sharing_recipient_resource_error" }, "resource_id": { "$ref": "#/components/schemas/resource-sharing_resource_resource_id" }, "resource_version": { "$ref": "#/components/schemas/resource-sharing_resource_version" }, "terminal": { "$ref": "#/components/schemas/resource-sharing_recipient_resource_error_terminal" } }, "required": [ "error", "terminal", "resource_id", "resource_version" ] }, "resource-sharing_share_recipient_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/resource-sharing_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/resource-sharing_share_recipient_object" } } } } ] }, "resource-sharing_share_recipient_response_single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/resource-sharing_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/resource-sharing_share_recipient_object" } } } ] }, "resource-sharing_share_resource_object": { "properties": { "created": { "$ref": "#/components/schemas/resource-sharing_created" }, "id": { "$ref": "#/components/schemas/resource-sharing_resource_id" }, "meta": { "$ref": "#/components/schemas/resource-sharing_resource_meta" }, "modified": { "$ref": "#/components/schemas/resource-sharing_modified" }, "resource_account_id": { "$ref": "#/components/schemas/resource-sharing_account_id" }, "resource_id": { "$ref": "#/components/schemas/resource-sharing_resource_resource_id" }, "resource_type": { "$ref": "#/components/schemas/resource-sharing_resource_type" }, "resource_version": { "$ref": "#/components/schemas/resource-sharing_resource_version" }, "status": { "$ref": "#/components/schemas/resource-sharing_resource_status" } }, "required": [ "id", "resource_id", "resource_type", "resource_account_id", "meta", "status", "created", "modified", "resource_version" ] }, "resource-sharing_share_resource_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/resource-sharing_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/resource-sharing_share_resource_object" } } } } ] }, "resource-sharing_share_resource_response_single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/resource-sharing_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/resource-sharing_share_resource_object" } } } ] }, "resource-sharing_share_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/resource-sharing_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/resource-sharing_share_object" } } } } ] }, "resource-sharing_share_response_single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/resource-sharing_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/resource-sharing_share_object" } } } ] }, "resource-sharing_share_status": { "type": "string", "enum": [ "active", "deleting", "deleted" ], "x-auditable": true }, "resource-sharing_share_target_type": { "type": "string", "enum": [ "account", "organization" ], "x-auditable": true }, "resource-sharing_update_share_excluded_recipients_request": { "type": "array", "items": { "$ref": "#/components/schemas/resource-sharing_create_share_excluded_recipient_request" } }, "resource-sharing_update_share_recipients_request": { "type": "array", "items": { "$ref": "#/components/schemas/resource-sharing_create_share_recipient_request" } }, "resource-sharing_update_share_request": { "description": "Request body for `PUT /accounts/{account_id}/shares/{share_id}`. The\nshare's display `name` and `tags` can be updated via this endpoint. To\nmodify recipients, use the\n`/accounts/{account_id}/shares/{share_id}/recipients` subresource\nendpoints (POST, PUT, DELETE).\n", "type": "object", "properties": { "name": { "$ref": "#/components/schemas/resource-sharing_share_name" } }, "required": [ "name" ] }, "resource-sharing_update_share_resource_request": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/resource-sharing_resource_meta" } }, "required": [ "meta" ] }, "resource-sharing_v4error": { "type": "object", "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "resource-sharing_v4errors": { "type": "array", "items": { "$ref": "#/components/schemas/resource-sharing_v4error" }, "example": [] }, "resource-tagging_access_application_id": { "description": "Access application ID is required only for access_application_policy resources", "type": "string", "format": "uuid", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" }, "resource-tagging_account_id": { "allOf": [ { "$ref": "#/components/schemas/resource-tagging_identifier" } ], "minLength": 32 }, "resource-tagging_account_resource_type": { "description": "Identifies the type of account-level resource.", "type": "string", "example": "worker", "enum": [ "access_application", "access_group", "account", "account_ruleset", "ai_gateway", "alerting_policy", "alerting_webhook", "cloudflared_tunnel", "cws_deployment", "cws_policy", "cws_policy_set", "cws_workload", "d1_database", "durable_object_namespace", "gateway_list", "gateway_rule", "image", "infrastructure_target", "kv_namespace", "load_balancer_monitor", "load_balancer_pool", "pages_project", "queue", "r2_bucket", "resource_share", "stream_live_input", "stream_video", "vectorize_index", "worker", "worker_version" ], "x-auditable": true }, "resource-tagging_account_resource_type_base_enum": { "description": "Enum for base account-level resource types (those with no extra required fields).", "type": "string", "example": "worker", "enum": [ "access_application", "access_group", "account", "account_ruleset", "ai_gateway", "alerting_policy", "alerting_webhook", "cloudflared_tunnel", "cws_deployment", "cws_policy", "cws_policy_set", "cws_workload", "d1_database", "durable_object_namespace", "gateway_list", "gateway_rule", "image", "infrastructure_target", "kv_namespace", "load_balancer_monitor", "load_balancer_pool", "pages_project", "queue", "r2_bucket", "resource_share", "stream_live_input", "stream_video", "vectorize_index", "worker" ], "x-auditable": true }, "resource-tagging_account_resource_type_worker_version_enum": { "description": "Enum for worker_version resource type.", "type": "string", "example": "worker_version", "enum": [ "worker_version" ], "x-auditable": true }, "resource-tagging_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/resource-tagging_messages" }, "messages": { "$ref": "#/components/schemas/resource-tagging_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "resource-tagging_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/resource-tagging_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/resource-tagging_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "resource-tagging_cursor_result_info": { "type": "object", "properties": { "count": { "description": "Indicates the number of results returned in the current page.", "type": "integer", "example": 20 }, "cursor": { "description": "Provides a cursor for the next page of results. Include this value in the next request to continue pagination.", "type": "string", "example": "eyJhY2NvdW50X2lkIjoxMjM0NTY3ODkwfQ", "nullable": true } } }, "resource-tagging_delete_tags_request_account_level": { "description": "Request body schema for deleting tags from account-level resources. Use /zones/{zone_id}/tags for zone-level resources.", "discriminator": { "mapping": { "access_application": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "access_group": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "account": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "account_ruleset": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "ai_gateway": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "alerting_policy": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "alerting_webhook": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "cloudflared_tunnel": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "cws_deployment": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "cws_policy": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "cws_policy_set": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "cws_workload": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "d1_database": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "durable_object_namespace": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "gateway_list": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "gateway_rule": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "image": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "infrastructure_target": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "kv_namespace": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "load_balancer_monitor": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "load_balancer_pool": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "pages_project": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "queue": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "r2_bucket": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "resource_share": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "stream_live_input": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "stream_video": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "vectorize_index": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "worker": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base", "worker_version": "#/components/schemas/resource-tagging_delete_tags_request_account_level_worker_version" }, "propertyName": "resource_type" }, "oneOf": [ { "$ref": "#/components/schemas/resource-tagging_delete_tags_request_account_level_worker_version" }, { "$ref": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base" } ] }, "resource-tagging_delete_tags_request_account_level_base": { "description": "Request body schema for deleting tags from account-level resources.", "type": "object", "properties": { "resource_id": { "$ref": "#/components/schemas/resource-tagging_resource_id" }, "resource_type": { "$ref": "#/components/schemas/resource-tagging_account_resource_type_base_enum" } }, "required": [ "resource_type", "resource_id" ] }, "resource-tagging_delete_tags_request_account_level_worker_version": { "description": "Request body schema for deleting tags from worker_version resources.", "allOf": [ { "$ref": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base" }, { "properties": { "resource_type": { "$ref": "#/components/schemas/resource-tagging_account_resource_type_worker_version_enum" }, "worker_id": { "$ref": "#/components/schemas/resource-tagging_worker_id" } }, "required": [ "worker_id" ], "type": "object" } ] }, "resource-tagging_delete_tags_request_zone_level": { "description": "Request body schema for deleting tags from zone-level resources.", "discriminator": { "mapping": { "access_application_policy": "#/components/schemas/resource-tagging_delete_tags_request_zone_level_access_application_policy", "api_gateway_operation": "#/components/schemas/resource-tagging_delete_tags_request_zone_level_base", "custom_certificate": "#/components/schemas/resource-tagging_delete_tags_request_zone_level_base", "custom_hostname": "#/components/schemas/resource-tagging_delete_tags_request_zone_level_base", "dns_record": "#/components/schemas/resource-tagging_delete_tags_request_zone_level_base", "healthcheck": "#/components/schemas/resource-tagging_delete_tags_request_zone_level_base", "load_balancer": "#/components/schemas/resource-tagging_delete_tags_request_zone_level_base", "managed_client_certificate": "#/components/schemas/resource-tagging_delete_tags_request_zone_level_base", "worker_route": "#/components/schemas/resource-tagging_delete_tags_request_zone_level_base", "zone": "#/components/schemas/resource-tagging_delete_tags_request_zone_level_base", "zone_ruleset": "#/components/schemas/resource-tagging_delete_tags_request_zone_level_base" }, "propertyName": "resource_type" }, "oneOf": [ { "$ref": "#/components/schemas/resource-tagging_delete_tags_request_zone_level_base" }, { "$ref": "#/components/schemas/resource-tagging_delete_tags_request_zone_level_access_application_policy" } ] }, "resource-tagging_delete_tags_request_zone_level_access_application_policy": { "description": "Request body schema for deleting tags from access_application_policy resources.", "allOf": [ { "$ref": "#/components/schemas/resource-tagging_delete_tags_request_zone_level_base" }, { "properties": { "access_application_id": { "$ref": "#/components/schemas/resource-tagging_access_application_id" }, "resource_type": { "$ref": "#/components/schemas/resource-tagging_zone_resource_type_access_application_policy_enum" } }, "required": [ "access_application_id" ], "type": "object" } ] }, "resource-tagging_delete_tags_request_zone_level_base": { "description": "Request body schema for deleting tags from zone-level resources. Zone ID comes from URL path.", "type": "object", "properties": { "resource_id": { "$ref": "#/components/schemas/resource-tagging_resource_id" }, "resource_type": { "$ref": "#/components/schemas/resource-tagging_zone_resource_type_base_enum" } }, "required": [ "resource_type", "resource_id" ] }, "resource-tagging_etag": { "description": "ETag identifier for optimistic concurrency control. Formatted as \"v1:\" where\nthe hash is the base64url-encoded SHA-256 (truncated to 128 bits) of the tags map\ncanonicalized using RFC 8785 (JSON Canonicalization Scheme). Clients should treat\nETags as opaque strings and pass them back via the If-Match header on write operations.\n", "type": "string", "example": "v1:RBNvo1WzZ4oRRq0W9-hkng", "readOnly": true }, "resource-tagging_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "resource-tagging_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "resource-tagging_resource_id": { "description": "Identifies the unique resource.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "x-auditable": true }, "resource-tagging_resource_name": { "description": "Human-readable name of the resource.", "type": "string", "example": "my-worker-script" }, "resource-tagging_resource_type": { "description": "Identifies the type of resource.", "type": "string", "example": "zone", "enum": [ "access_application", "access_application_policy", "access_group", "account", "account_ruleset", "ai_gateway", "alerting_policy", "alerting_webhook", "api_gateway_operation", "cloudflared_tunnel", "custom_certificate", "custom_hostname", "cws_deployment", "cws_policy", "cws_policy_set", "cws_workload", "d1_database", "dns_record", "durable_object_namespace", "gateway_list", "gateway_rule", "healthcheck", "image", "infrastructure_target", "kv_namespace", "load_balancer", "load_balancer_monitor", "load_balancer_pool", "managed_client_certificate", "pages_project", "queue", "r2_bucket", "resource_share", "stream_live_input", "stream_video", "vectorize_index", "worker", "worker_route", "worker_version", "zone", "zone_ruleset" ], "x-auditable": true }, "resource-tagging_set_tags_request_account_level": { "description": "Request body schema for setting tags on account-level resources.", "discriminator": { "mapping": { "access_application": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "access_group": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "account": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "account_ruleset": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "ai_gateway": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "alerting_policy": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "alerting_webhook": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "cloudflared_tunnel": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "cws_deployment": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "cws_policy": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "cws_policy_set": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "cws_workload": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "d1_database": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "durable_object_namespace": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "gateway_list": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "gateway_rule": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "image": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "infrastructure_target": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "kv_namespace": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "load_balancer_monitor": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "load_balancer_pool": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "pages_project": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "queue": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "r2_bucket": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "resource_share": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "stream_live_input": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "stream_video": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "vectorize_index": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "worker": "#/components/schemas/resource-tagging_set_tags_request_account_level_base", "worker_version": "#/components/schemas/resource-tagging_set_tags_request_account_level_worker_version" }, "propertyName": "resource_type" }, "oneOf": [ { "$ref": "#/components/schemas/resource-tagging_set_tags_request_account_level_worker_version" }, { "$ref": "#/components/schemas/resource-tagging_set_tags_request_account_level_base" } ] }, "resource-tagging_set_tags_request_account_level_base": { "description": "Request body schema for setting tags on account-level resources with no extra requirements.", "allOf": [ { "$ref": "#/components/schemas/resource-tagging_delete_tags_request_account_level_base" }, { "properties": { "tags": { "$ref": "#/components/schemas/resource-tagging_tags" } }, "type": "object" } ] }, "resource-tagging_set_tags_request_account_level_worker_version": { "description": "Request body schema for setting tags on worker_version resources.", "allOf": [ { "$ref": "#/components/schemas/resource-tagging_delete_tags_request_account_level_worker_version" }, { "properties": { "tags": { "$ref": "#/components/schemas/resource-tagging_tags" } }, "type": "object" } ] }, "resource-tagging_set_tags_request_zone_level": { "description": "Request body schema for setting tags on zone-level resources.", "discriminator": { "mapping": { "access_application_policy": "#/components/schemas/resource-tagging_set_tags_request_zone_level_access_application_policy", "api_gateway_operation": "#/components/schemas/resource-tagging_set_tags_request_zone_level_base", "custom_certificate": "#/components/schemas/resource-tagging_set_tags_request_zone_level_base", "custom_hostname": "#/components/schemas/resource-tagging_set_tags_request_zone_level_base", "dns_record": "#/components/schemas/resource-tagging_set_tags_request_zone_level_base", "healthcheck": "#/components/schemas/resource-tagging_set_tags_request_zone_level_base", "load_balancer": "#/components/schemas/resource-tagging_set_tags_request_zone_level_base", "managed_client_certificate": "#/components/schemas/resource-tagging_set_tags_request_zone_level_base", "worker_route": "#/components/schemas/resource-tagging_set_tags_request_zone_level_base", "zone": "#/components/schemas/resource-tagging_set_tags_request_zone_level_base", "zone_ruleset": "#/components/schemas/resource-tagging_set_tags_request_zone_level_base" }, "propertyName": "resource_type" }, "oneOf": [ { "$ref": "#/components/schemas/resource-tagging_set_tags_request_zone_level_base" }, { "$ref": "#/components/schemas/resource-tagging_set_tags_request_zone_level_access_application_policy" } ] }, "resource-tagging_set_tags_request_zone_level_access_application_policy": { "description": "Request body schema for setting tags on access_application_policy resources.", "allOf": [ { "$ref": "#/components/schemas/resource-tagging_delete_tags_request_zone_level_access_application_policy" }, { "properties": { "tags": { "$ref": "#/components/schemas/resource-tagging_tags" } }, "type": "object" } ] }, "resource-tagging_set_tags_request_zone_level_base": { "description": "Request body schema for setting tags on zone-level resources with no extra requirements.", "allOf": [ { "$ref": "#/components/schemas/resource-tagging_delete_tags_request_zone_level_base" }, { "properties": { "tags": { "$ref": "#/components/schemas/resource-tagging_tags" } }, "type": "object" } ] }, "resource-tagging_tag_key_summary": { "type": "object", "properties": { "key": { "description": "A tag key.", "type": "string", "example": "environment" }, "values": { "description": "All distinct values for this tag key.", "type": "array", "items": { "type": "string" }, "example": [ "production", "staging" ] } }, "required": [ "key", "values" ] }, "resource-tagging_tag_key_summary_response_collection": { "allOf": [ { "$ref": "#/components/schemas/resource-tagging_api-response-common" }, { "properties": { "result": { "description": "Contains an array of tag keys with their distinct values.", "type": "array", "items": { "$ref": "#/components/schemas/resource-tagging_tag_key_summary" }, "example": [ { "key": "environment", "values": [ "production", "staging" ] }, { "key": "team", "values": [ "engineering", "platform" ] } ] }, "result_info": { "$ref": "#/components/schemas/resource-tagging_cursor_result_info" } }, "type": "object" } ] }, "resource-tagging_tag_keys_response_collection": { "allOf": [ { "$ref": "#/components/schemas/resource-tagging_api-response-common" }, { "properties": { "result": { "description": "Contains an array of distinct tag keys.", "type": "array", "items": { "type": "string" }, "example": [ "environment", "team", "region" ] }, "result_info": { "$ref": "#/components/schemas/resource-tagging_cursor_result_info" } }, "type": "object" } ] }, "resource-tagging_tag_values_response_collection": { "allOf": [ { "$ref": "#/components/schemas/resource-tagging_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "type": "string" }, "example": [ "production", "staging" ] }, "result_info": { "$ref": "#/components/schemas/resource-tagging_cursor_result_info" } }, "type": "object" } ] }, "resource-tagging_tagged_resource_object": { "type": "object", "discriminator": { "mapping": { "access_application": "#/components/schemas/resource-tagging_tagged_resource_object_access_application", "access_application_policy": "#/components/schemas/resource-tagging_tagged_resource_object_access_application_policy", "access_group": "#/components/schemas/resource-tagging_tagged_resource_object_access_group", "account": "#/components/schemas/resource-tagging_tagged_resource_object_account", "account_ruleset": "#/components/schemas/resource-tagging_tagged_resource_object_account_ruleset", "ai_gateway": "#/components/schemas/resource-tagging_tagged_resource_object_ai_gateway", "alerting_policy": "#/components/schemas/resource-tagging_tagged_resource_object_alerting_policy", "alerting_webhook": "#/components/schemas/resource-tagging_tagged_resource_object_alerting_webhook", "api_gateway_operation": "#/components/schemas/resource-tagging_tagged_resource_object_api_gateway_operation", "cloudflared_tunnel": "#/components/schemas/resource-tagging_tagged_resource_object_cloudflared_tunnel", "custom_certificate": "#/components/schemas/resource-tagging_tagged_resource_object_custom_certificate", "custom_hostname": "#/components/schemas/resource-tagging_tagged_resource_object_custom_hostname", "cws_deployment": "#/components/schemas/resource-tagging_tagged_resource_object_cws_deployment", "cws_policy": "#/components/schemas/resource-tagging_tagged_resource_object_cws_policy", "cws_policy_set": "#/components/schemas/resource-tagging_tagged_resource_object_cws_policy_set", "cws_workload": "#/components/schemas/resource-tagging_tagged_resource_object_cws_workload", "d1_database": "#/components/schemas/resource-tagging_tagged_resource_object_d1_database", "dns_record": "#/components/schemas/resource-tagging_tagged_resource_object_dns_record", "durable_object_namespace": "#/components/schemas/resource-tagging_tagged_resource_object_durable_object_namespace", "gateway_list": "#/components/schemas/resource-tagging_tagged_resource_object_gateway_list", "gateway_rule": "#/components/schemas/resource-tagging_tagged_resource_object_gateway_rule", "healthcheck": "#/components/schemas/resource-tagging_tagged_resource_object_healthcheck", "image": "#/components/schemas/resource-tagging_tagged_resource_object_image", "infrastructure_target": "#/components/schemas/resource-tagging_tagged_resource_object_infrastructure_target", "kv_namespace": "#/components/schemas/resource-tagging_tagged_resource_object_kv_namespace", "load_balancer": "#/components/schemas/resource-tagging_tagged_resource_object_load_balancer", "load_balancer_monitor": "#/components/schemas/resource-tagging_tagged_resource_object_load_balancer_monitor", "load_balancer_pool": "#/components/schemas/resource-tagging_tagged_resource_object_load_balancer_pool", "managed_client_certificate": "#/components/schemas/resource-tagging_tagged_resource_object_managed_client_certificate", "pages_project": "#/components/schemas/resource-tagging_tagged_resource_object_pages_project", "queue": "#/components/schemas/resource-tagging_tagged_resource_object_queue", "r2_bucket": "#/components/schemas/resource-tagging_tagged_resource_object_r2_bucket", "resource_share": "#/components/schemas/resource-tagging_tagged_resource_object_resource_share", "stream_live_input": "#/components/schemas/resource-tagging_tagged_resource_object_stream_live_input", "stream_video": "#/components/schemas/resource-tagging_tagged_resource_object_stream_video", "vectorize_index": "#/components/schemas/resource-tagging_tagged_resource_object_vectorize_index", "worker": "#/components/schemas/resource-tagging_tagged_resource_object_worker", "worker_route": "#/components/schemas/resource-tagging_tagged_resource_object_worker_route", "worker_version": "#/components/schemas/resource-tagging_tagged_resource_object_worker_version", "zone": "#/components/schemas/resource-tagging_tagged_resource_object_zone", "zone_ruleset": "#/components/schemas/resource-tagging_tagged_resource_object_zone_ruleset" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_access_application" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_access_application_policy" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_access_group" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_ruleset" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_ai_gateway" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_alerting_policy" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_alerting_webhook" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_api_gateway_operation" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_cloudflared_tunnel" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_custom_certificate" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_custom_hostname" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_cws_deployment" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_cws_policy" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_cws_policy_set" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_cws_workload" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_d1_database" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_dns_record" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_durable_object_namespace" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_gateway_list" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_gateway_rule" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_healthcheck" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_image" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_infrastructure_target" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_kv_namespace" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_load_balancer" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_load_balancer_monitor" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_load_balancer_pool" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_managed_client_certificate" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_pages_project" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_queue" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_r2_bucket" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_resource_share" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_stream_live_input" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_stream_video" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_vectorize_index" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_worker" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_worker_route" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_worker_version" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_zone" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_zone_ruleset" } ] }, "resource-tagging_tagged_resource_object_access_application": { "description": "Response for access_application resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "access_application" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_access_application_policy": { "description": "Response for access_application_policy resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "access_application_policy" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_access_application_policy_base" } ] }, "resource-tagging_tagged_resource_object_access_application_policy_base": { "description": "Base schema for access_application_policy resources (without type discriminator)", "type": "object", "properties": { "access_application_id": { "$ref": "#/components/schemas/resource-tagging_access_application_id" }, "etag": { "$ref": "#/components/schemas/resource-tagging_etag" }, "id": { "$ref": "#/components/schemas/resource-tagging_resource_id" }, "name": { "$ref": "#/components/schemas/resource-tagging_resource_name" }, "tags": { "$ref": "#/components/schemas/resource-tagging_tags" }, "tags_updated_at": { "$ref": "#/components/schemas/resource-tagging_tags_updated_at" }, "zone_id": { "$ref": "#/components/schemas/resource-tagging_zone_id" } }, "required": [ "id", "tags", "name", "etag", "zone_id", "access_application_id" ] }, "resource-tagging_tagged_resource_object_access_group": { "description": "Response for access_group resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "access_group" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_account": { "description": "Response for account resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "account" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_account_level_base": { "description": "Base schema for account-level resources (without type discriminator)", "type": "object", "properties": { "etag": { "$ref": "#/components/schemas/resource-tagging_etag" }, "id": { "$ref": "#/components/schemas/resource-tagging_resource_id" }, "name": { "$ref": "#/components/schemas/resource-tagging_resource_name" }, "tags": { "$ref": "#/components/schemas/resource-tagging_tags" }, "tags_updated_at": { "$ref": "#/components/schemas/resource-tagging_tags_updated_at" } }, "required": [ "id", "tags", "name", "etag" ] }, "resource-tagging_tagged_resource_object_account_ruleset": { "description": "Response for account_ruleset resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "account_ruleset" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_ai_gateway": { "description": "Response for ai_gateway resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "ai_gateway" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_alerting_policy": { "description": "Response for alerting_policy resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "alerting_policy" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_alerting_webhook": { "description": "Response for alerting_webhook resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "alerting_webhook" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_api_gateway_operation": { "description": "Response for api_gateway_operation resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "api_gateway_operation" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_zone_level_base" } ] }, "resource-tagging_tagged_resource_object_cloudflared_tunnel": { "description": "Response for cloudflared_tunnel resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "cloudflared_tunnel" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_custom_certificate": { "description": "Response for custom_certificate resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "custom_certificate" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_zone_level_base" } ] }, "resource-tagging_tagged_resource_object_custom_hostname": { "description": "Response for custom_hostname resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "custom_hostname" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_zone_level_base" } ] }, "resource-tagging_tagged_resource_object_cws_deployment": { "description": "Response for cws_deployment resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "cws_deployment" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_cws_policy": { "description": "Response for cws_policy resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "cws_policy" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_cws_policy_set": { "description": "Response for cws_policy_set resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "cws_policy_set" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_cws_workload": { "description": "Response for cws_workload resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "cws_workload" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_d1_database": { "description": "Response for d1_database resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "d1_database" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_dns_record": { "description": "Response for dns_record resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "dns_record" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_zone_level_base" } ] }, "resource-tagging_tagged_resource_object_durable_object_namespace": { "description": "Response for durable_object_namespace resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "durable_object_namespace" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_gateway_list": { "description": "Response for gateway_list resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "gateway_list" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_gateway_rule": { "description": "Response for gateway_rule resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "gateway_rule" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_healthcheck": { "description": "Response for healthcheck resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "healthcheck" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_zone_level_base" } ] }, "resource-tagging_tagged_resource_object_image": { "description": "Response for image resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "image" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_infrastructure_target": { "description": "Response for infrastructure_target resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "infrastructure_target" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_kv_namespace": { "description": "Response for kv_namespace resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "kv_namespace" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_load_balancer": { "description": "Response for load_balancer resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "load_balancer" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_zone_level_base" } ] }, "resource-tagging_tagged_resource_object_load_balancer_monitor": { "description": "Response for load_balancer_monitor resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "load_balancer_monitor" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_load_balancer_pool": { "description": "Response for load_balancer_pool resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "load_balancer_pool" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_managed_client_certificate": { "description": "Response for managed_client_certificate resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "managed_client_certificate" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_zone_level_base" } ] }, "resource-tagging_tagged_resource_object_pages_project": { "description": "Response for pages_project resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "pages_project" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_queue": { "description": "Response for queue resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "queue" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_r2_bucket": { "description": "Response for r2_bucket resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "r2_bucket" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_resource_share": { "description": "Response for resource_share resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "resource_share" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_stream_live_input": { "description": "Response for stream_live_input resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "stream_live_input" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_stream_video": { "description": "Response for stream_video resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "stream_video" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_vectorize_index": { "description": "Response for vectorize_index resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "vectorize_index" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_worker": { "description": "Response for worker resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "worker" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_account_level_base" } ] }, "resource-tagging_tagged_resource_object_worker_route": { "description": "Response for worker_route resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "worker_route" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_zone_level_base" } ] }, "resource-tagging_tagged_resource_object_worker_version": { "description": "Response for worker_version resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "worker_version" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_worker_version_base" } ] }, "resource-tagging_tagged_resource_object_worker_version_base": { "description": "Base schema for worker_version resources (without type discriminator)", "type": "object", "properties": { "etag": { "$ref": "#/components/schemas/resource-tagging_etag" }, "id": { "$ref": "#/components/schemas/resource-tagging_resource_id" }, "name": { "$ref": "#/components/schemas/resource-tagging_resource_name" }, "tags": { "$ref": "#/components/schemas/resource-tagging_tags" }, "tags_updated_at": { "$ref": "#/components/schemas/resource-tagging_tags_updated_at" }, "worker_id": { "$ref": "#/components/schemas/resource-tagging_worker_id" } }, "required": [ "id", "tags", "name", "etag", "worker_id" ] }, "resource-tagging_tagged_resource_object_zone": { "description": "Response for zone resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "zone" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_zone_level_base" } ] }, "resource-tagging_tagged_resource_object_zone_level_base": { "description": "Base schema for zone-level resources (without type discriminator)", "type": "object", "properties": { "etag": { "$ref": "#/components/schemas/resource-tagging_etag" }, "id": { "$ref": "#/components/schemas/resource-tagging_resource_id" }, "name": { "$ref": "#/components/schemas/resource-tagging_resource_name" }, "tags": { "$ref": "#/components/schemas/resource-tagging_tags" }, "tags_updated_at": { "$ref": "#/components/schemas/resource-tagging_tags_updated_at" }, "zone_id": { "$ref": "#/components/schemas/resource-tagging_zone_id" } }, "required": [ "id", "tags", "name", "etag", "zone_id" ] }, "resource-tagging_tagged_resource_object_zone_ruleset": { "description": "Response for zone_ruleset resources", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "zone_ruleset" ] } }, "required": [ "type" ], "type": "object" }, { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object_zone_level_base" } ] }, "resource-tagging_tagged_resource_response_collection": { "allOf": [ { "$ref": "#/components/schemas/resource-tagging_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object" } }, "result_info": { "$ref": "#/components/schemas/resource-tagging_cursor_result_info" } }, "type": "object" } ] }, "resource-tagging_tagged_resource_response_single": { "allOf": [ { "$ref": "#/components/schemas/resource-tagging_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/resource-tagging_tagged_resource_object" } }, "type": "object" } ] }, "resource-tagging_tags": { "description": "Contains key-value pairs of tags. Keys may contain at most 256 characters. Values may contain at most 1024 characters and may be empty for key-only tags.", "type": "object", "example": { "environment": "production", "team": "engineering" }, "additionalProperties": { "maxLength": 1024, "type": "string" }, "x-auditable": true }, "resource-tagging_tags_updated_at": { "description": "Monotonic version of the resource's tags: the timestamp assigned when the\ntags were last written. Returned by read endpoints, by 2PC prepare (the\nversion that will be assigned on commit, unless a concurrent write lands\nfirst, in which case a newer version is assigned), and by 2PC commit (the\nauthoritative committed version). Omitted for untagged resources and\ndelete commits: a deleted resource has no current version, and deletions\nare ordered by event order rather than by version.\n", "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z", "readOnly": true }, "resource-tagging_worker_id": { "description": "Worker ID is required only for worker_version resources", "type": "string", "example": "3f72a691-44b3-4c11-8642-c18a88ddaa5e" }, "resource-tagging_zone_id": { "description": "Zone ID is required only for zone-level resources", "type": "string", "allOf": [ { "$ref": "#/components/schemas/resource-tagging_identifier" } ], "minLength": 32 }, "resource-tagging_zone_resource_type": { "description": "Identifies the type of zone-level resource.", "type": "string", "example": "zone", "enum": [ "access_application_policy", "api_gateway_operation", "custom_certificate", "custom_hostname", "dns_record", "healthcheck", "load_balancer", "managed_client_certificate", "worker_route", "zone", "zone_ruleset" ], "x-auditable": true }, "resource-tagging_zone_resource_type_access_application_policy_enum": { "description": "Enum for access_application_policy resource type.", "type": "string", "example": "access_application_policy", "enum": [ "access_application_policy" ], "x-auditable": true }, "resource-tagging_zone_resource_type_base_enum": { "description": "Enum for base zone-level resource types (those with no extra required fields).", "type": "string", "example": "zone", "enum": [ "api_gateway_operation", "custom_certificate", "custom_hostname", "dns_record", "healthcheck", "load_balancer", "managed_client_certificate", "worker_route", "zone", "zone_ruleset" ], "x-auditable": true }, "rlanalytics_api-response-common-failure": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/rlanalytics_messages" }, "minItems": 1 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/rlanalytics_messages" } }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages" ] }, "rlanalytics_messages": { "type": "object", "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "rlanalytics_rate_limit_analytics": { "description": "Rate limiting analytics for a zone.", "type": "object", "properties": { "labels": { "description": "Mapping from rule ID to human-readable description of the rule.", "type": "object", "example": { "123e4567-e89b-12d3-a456-426655440000": "block login brute force on /login", "66698345-bc87-d312-a456-937482934748": "rate limit whole site" }, "additionalProperties": { "type": "string" } }, "since": { "description": "Start of the queried time period formatted as RFC 3339.", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "time_delta": { "description": "Length (in seconds) of the time segments dividing the entire time period.", "type": "integer", "example": 3600, "enum": [ 60, 3600, 86400, 2592000 ] }, "timeseries": { "description": "Time series with analytics data for each time segment.", "type": "array", "items": { "$ref": "#/components/schemas/rlanalytics_rate_limit_analytics_timeseries_point" } }, "until": { "description": "Exclusive end of the queried time period formatted as RFC 3339.", "type": "string", "format": "date-time", "example": "2024-01-02T00:00:00Z" }, "zone_id": { "description": "Numeric ID of the zone.", "type": "integer", "format": "int64", "example": 123 } }, "required": [ "since", "until", "time_delta", "labels", "timeseries" ] }, "rlanalytics_rate_limit_analytics_action_counters": { "description": "Rate limiting action counts broken down by action type.", "type": "object", "properties": { "all": { "description": "Count of rule actions of any type triggered.", "type": "integer", "format": "int64", "example": 700 }, "allow": { "description": "Count of allow rule actions triggered.", "type": "integer", "format": "int64", "example": 500 }, "ban": { "description": "Count of ban rule actions triggered.", "type": "integer", "format": "int64", "example": 50 }, "error": { "description": "Count of error rule actions triggered.", "type": "integer", "format": "int64", "example": 50 }, "simulate": { "description": "Count of simulate rule actions triggered.", "type": "integer", "format": "int64", "example": 100 } } }, "rlanalytics_rate_limit_analytics_colo_entry": { "description": "Action counters for a single colo.", "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/rlanalytics_rate_limit_analytics_action_counters" } }, "required": [ "actions" ] }, "rlanalytics_rate_limit_analytics_rule_rollup": { "description": "Action totals and per-colo action counts for a particular rule.", "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/rlanalytics_rate_limit_analytics_action_counters" }, "colos": { "description": "Maps each colo name to its action counters.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/rlanalytics_rate_limit_analytics_colo_entry" } }, "versions": { "description": "Number of active versions of the rate limit rule.", "type": "integer", "example": 1 } }, "required": [ "versions", "actions", "colos" ] }, "rlanalytics_rate_limit_analytics_timeseries_point": { "description": "Analytics data for a single time segment.", "type": "object", "properties": { "rules": { "description": "Contains rule-level analytics for this time segment.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/rlanalytics_rate_limit_analytics_rule_rollup" } }, "since": { "description": "Start of the time segment formatted as RFC 3339.", "type": "string", "format": "date-time" }, "until": { "description": "Exclusive end of the time segment formatted as RFC 3339.", "type": "string", "format": "date-time" } }, "required": [ "since", "until", "rules" ] }, "rulesets_AccountId": { "description": "The unique ID of the account.", "type": "string", "example": "abf9b32d38c5f572afde3336ec0ce302", "pattern": "^[0-9a-f]{32}$", "title": "Account ID" }, "rulesets_BlockRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "block" ] }, "action_parameters": { "type": "object", "properties": { "response": { "description": "The response to show when the block is applied.", "type": "object", "properties": { "content": { "description": "The content to return.", "example": "{\n \"success\": false,\n \"error\": \"you have been blocked\"\n}", "minLength": 1, "title": "Content", "type": "string" }, "content_type": { "description": "The type of the content to return.", "type": "string", "example": "application/json", "minLength": 1, "title": "Content Type" }, "status_code": { "description": "The status code to return.", "type": "integer", "maximum": 499, "minimum": 400, "title": "Status Code" } }, "required": [ "status_code", "content", "content_type" ], "title": "Response" } } }, "description": { "type": "string", "example": "Block the request." } }, "title": "Block Rule", "type": "object" } ] }, "rulesets_ChallengeRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "challenge" ] }, "description": { "type": "string", "example": "Issue an Interactive Challenge if the visitor has not solved an Interactive Challenge prior to the request." } }, "title": "Challenge Rule", "type": "object" } ] }, "rulesets_CompressResponseRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "compress_response" ] }, "action_parameters": { "type": "object", "properties": { "algorithms": { "description": "Custom order for compression algorithms.", "type": "array", "items": { "description": "Compression algorithm to enable.", "properties": { "name": { "description": "Name of the compression algorithm to enable.", "type": "string", "example": "none", "enum": [ "none", "auto", "default", "gzip", "brotli", "zstd" ], "title": "Algorithm Name" } }, "title": "Algorithm", "type": "object" }, "minItems": 1, "title": "Algorithms", "uniqueItems": true } }, "required": [ "algorithms" ] }, "description": { "type": "string", "example": "Modify the compression algorithm used in the response." } }, "title": "Response Compression Rule", "type": "object" } ] }, "rulesets_Cursor": { "description": "The cursor to use for the next page.", "type": "string", "example": "dGhpc2lzYW5leGFtcGxlCg", "minLength": 1, "title": "Cursor" }, "rulesets_DDoSDynamicRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "ddos_dynamic" ] }, "description": { "type": "string", "example": "Perform a specific action according to a set of internal guidelines defined by Cloudflare." } }, "title": "DDoS Dynamic Rule", "type": "object" } ] }, "rulesets_Errors": { "description": "A list of error messages.", "type": "array", "items": { "$ref": "#/components/schemas/rulesets_Message" }, "title": "Errors", "uniqueItems": true }, "rulesets_ExecuteCategoryOverrides": { "description": "A list of category-level overrides. This option has the second-highest precedence after rule-level overrides.", "type": "array", "items": { "description": "A category-level override.", "minProperties": 2, "properties": { "action": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RuleAction" }, { "description": "The action to override rules in the category with.", "example": "log", "type": "string" } ] }, "category": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RuleCategory" }, { "description": "The name of the category to override.", "type": "string" } ] }, "enabled": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RuleEnabled" }, { "description": "Whether to enable execution of rules in the category.", "type": "boolean" } ] }, "sensitivity_level": { "allOf": [ { "$ref": "#/components/schemas/rulesets_ExecuteSensitivityLevel" }, { "description": "The sensitivity level to use for rules in the category. This option is only applicable for DDoS phases.", "type": "string" } ] } }, "required": [ "category" ], "title": "Category Override", "type": "object" }, "minItems": 1, "title": "Category Overrides", "uniqueItems": true }, "rulesets_ExecuteMatchedData": { "description": "The configuration to use for matched data logging.", "type": "object", "properties": { "public_key": { "description": "The public key to encrypt matched data logs with.", "type": "string", "example": "iGqBmyIUxuWt1rvxoAharN9FUXneUBxA/Y19PyyrEG0=", "minLength": 1, "title": "Public Key" } }, "required": [ "public_key" ], "title": "Matched Data" }, "rulesets_ExecuteOverrides": { "description": "A set of overrides to apply to the target ruleset.", "type": "object", "properties": { "action": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RuleAction" }, { "description": "An action to override all rules with. This option has lower precedence than rule and category overrides.", "example": "log", "type": "string" } ] }, "categories": { "$ref": "#/components/schemas/rulesets_ExecuteCategoryOverrides" }, "enabled": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RuleEnabled" }, { "description": "Whether to enable execution of all rules. This option has lower precedence than rule and category overrides.", "type": "boolean" } ] }, "rules": { "$ref": "#/components/schemas/rulesets_ExecuteRuleOverrides" }, "sensitivity_level": { "allOf": [ { "$ref": "#/components/schemas/rulesets_ExecuteSensitivityLevel" }, { "description": "A sensitivity level to set for all rules. This option has lower precedence than rule and category overrides and is only applicable for DDoS phases.", "type": "string" } ] } }, "minProperties": 1, "title": "Overrides" }, "rulesets_ExecuteRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "execute" ] }, "action_parameters": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RulesetId" }, { "description": "The ID of the ruleset to execute.", "example": "4814384a9e5d4991b9815dcfc25d2f1f", "type": "string" } ] }, "matched_data": { "$ref": "#/components/schemas/rulesets_ExecuteMatchedData" }, "overrides": { "$ref": "#/components/schemas/rulesets_ExecuteOverrides" } }, "required": [ "id" ] }, "description": { "type": "string", "example": "Execute another ruleset." } }, "title": "Execute Rule", "type": "object" } ] }, "rulesets_ExecuteRuleOverrides": { "description": "A list of rule-level overrides. This option has the highest precedence.", "type": "array", "items": { "description": "A rule-level override.", "minProperties": 2, "properties": { "action": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RuleAction" }, { "description": "The action to override the rule with.", "example": "log", "type": "string" } ] }, "enabled": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RuleEnabled" }, { "description": "Whether to enable execution of the rule.", "type": "boolean" } ] }, "id": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RuleId" }, { "description": "The ID of the rule to override.", "example": "8ac8bc2a661e475d940980f9317f28e1", "type": "string" } ] }, "score_threshold": { "description": "The score threshold to use for the rule.", "type": "integer", "title": "Score Threshold" }, "sensitivity_level": { "allOf": [ { "$ref": "#/components/schemas/rulesets_ExecuteSensitivityLevel" }, { "description": "The sensitivity level to use for the rule. This option is only applicable for DDoS phases.", "type": "string" } ] } }, "required": [ "id" ], "title": "Rule Override", "type": "object" }, "minItems": 1, "title": "Rule Overrides", "uniqueItems": true }, "rulesets_ExecuteSensitivityLevel": { "type": "string", "example": "default", "enum": [ "default", "medium", "low", "eoff" ], "title": "Sensitivity Level" }, "rulesets_ForceConnectionCloseRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "force_connection_close" ] }, "description": { "type": "string", "example": "Close ongoing HTTP connections. This action does not block a request, but it forces the client to reconnect. For HTTP/2 and HTTP/3 connections, the connection will be closed even if it breaks other requests running on the same connection." } }, "title": "Force Connection Close Rule", "type": "object" } ] }, "rulesets_JsChallengeRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "js_challenge" ] }, "description": { "type": "string", "example": "Issue a non-interactive JavaScript Challenge if the visitor has not solved an Interactive Challenge, Managed Challenge, or JavaScript Challenge prior to the request." } }, "title": "JavaScript Challenge Rule", "type": "object" } ] }, "rulesets_LogCustomFieldCookieFields": { "description": "The cookie fields to log.", "type": "array", "items": { "description": "The cookie field to log.", "properties": { "name": { "description": "The name of the cookie.", "type": "string", "example": "myCookie", "minLength": 1, "title": "Cookie Name" } }, "required": [ "name" ], "title": "Cookie Field", "type": "object" }, "minItems": 1, "title": "Cookie Fields" }, "rulesets_LogCustomFieldRawResponseFields": { "description": "The raw response fields to log.", "type": "array", "items": { "description": "The raw response field to log.", "properties": { "name": { "description": "The name of the response header.", "type": "string", "example": "my-response-header", "minLength": 1, "title": "Header Name" }, "preserve_duplicates": { "description": "Whether to log duplicate values of the same header.", "type": "boolean", "example": true, "default": false, "title": "Preserve Duplicates" } }, "required": [ "name" ], "title": "Raw Response Field", "type": "object" }, "minItems": 1, "title": "Raw Response Fields" }, "rulesets_LogCustomFieldRequestFields": { "description": "The raw request fields to log.", "type": "array", "items": { "description": "The raw request field to log.", "properties": { "name": { "description": "The name of the header.", "type": "string", "example": "my-request-header", "minLength": 1, "title": "Header Name" } }, "required": [ "name" ], "title": "Raw Request Field", "type": "object" }, "minItems": 1, "title": "Raw Request Fields" }, "rulesets_LogCustomFieldResponseFields": { "description": "The transformed response fields to log.", "type": "array", "items": { "description": "The transformed response field to log.", "properties": { "name": { "description": "The name of the response header.", "type": "string", "example": "my-response-header", "minLength": 1, "title": "Header Name" }, "preserve_duplicates": { "description": "Whether to log duplicate values of the same header.", "type": "boolean", "example": true, "default": false, "title": "Preserve Duplicates" } }, "required": [ "name" ], "title": "Transformed Response Field", "type": "object" }, "minItems": 1, "title": "Transformed Response Fields" }, "rulesets_LogCustomFieldRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "log_custom_field" ] }, "action_parameters": { "type": "object", "minProperties": 1, "properties": { "cookie_fields": { "$ref": "#/components/schemas/rulesets_LogCustomFieldCookieFields" }, "raw_response_fields": { "$ref": "#/components/schemas/rulesets_LogCustomFieldRawResponseFields" }, "request_fields": { "$ref": "#/components/schemas/rulesets_LogCustomFieldRequestFields" }, "response_fields": { "$ref": "#/components/schemas/rulesets_LogCustomFieldResponseFields" }, "transformed_request_fields": { "$ref": "#/components/schemas/rulesets_LogCustomFieldTransformedRequestFields" } } }, "description": { "type": "string", "example": "Log additional custom fields." } }, "title": "Log Custom Field Rule", "type": "object" } ] }, "rulesets_LogCustomFieldTransformedRequestFields": { "description": "The transformed request fields to log.", "type": "array", "items": { "description": "The transformed request field to log.", "properties": { "name": { "description": "The name of the header.", "type": "string", "example": "my-request-header", "minLength": 1, "title": "Header Name" } }, "required": [ "name" ], "title": "Transformed Request Field", "type": "object" }, "minItems": 1, "title": "Transformed Request Fields" }, "rulesets_LogRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "log" ] }, "description": { "type": "string", "example": "Log the request." } }, "title": "Log Rule", "type": "object" } ] }, "rulesets_ManagedChallengeRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "managed_challenge" ] }, "description": { "type": "string", "example": "Issue a Managed Challenge if the visitor has not solved a Managed Challenge or Interactive Challenge prior to the request." } }, "title": "Managed Challenge Rule", "type": "object" } ] }, "rulesets_ManagedTransform": { "description": "A Managed Transform object.", "type": "object", "properties": { "conflicts_with": { "description": "The Managed Transforms that this Managed Transform conflicts with.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/rulesets_ManagedTransformId" }, { "example": "add_true_client_ip_headers", "type": "string" } ] }, "minItems": 1, "readOnly": true, "title": "Conflicts With", "uniqueItems": true, "x-stainless-skip": [ "terraform" ] }, "enabled": { "description": "Whether the Managed Transform is enabled.", "type": "boolean", "example": true, "title": "Enabled" }, "has_conflict": { "description": "Whether the Managed Transform conflicts with the currently-enabled Managed Transforms.", "type": "boolean", "example": false, "readOnly": true, "title": "Has Conflict", "x-stainless-skip": [ "terraform" ] }, "id": { "$ref": "#/components/schemas/rulesets_ManagedTransformId" } }, "required": [ "id", "enabled", "has_conflict" ], "title": "Managed Transform" }, "rulesets_ManagedTransformId": { "description": "The human-readable identifier of the Managed Transform.", "type": "string", "minLength": 1, "title": "Transform ID" }, "rulesets_ManagedTransforms": { "description": "A Managed Transforms object.", "type": "object", "properties": { "managed_request_headers": { "description": "The list of Managed Request Transforms.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/rulesets_ManagedTransform" }, { "properties": { "id": { "type": "string", "example": "add_bot_protection_headers" } }, "type": "object" } ] }, "title": "Managed Request Transforms", "uniqueItems": true }, "managed_response_headers": { "description": "The list of Managed Response Transforms.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/rulesets_ManagedTransform" }, { "properties": { "id": { "type": "string", "example": "add_security_headers" } }, "type": "object" } ] }, "title": "Managed Response Transforms", "uniqueItems": true } }, "required": [ "managed_request_headers", "managed_response_headers" ], "title": "Managed Transforms" }, "rulesets_ManagedTransformsPatch": { "description": "A Managed Transforms patch object. Both fields are optional; only the sections provided will be updated.", "type": "object", "properties": { "managed_request_headers": { "description": "The list of Managed Request Transforms.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/rulesets_ManagedTransform" }, { "properties": { "id": { "type": "string", "example": "add_bot_protection_headers" } }, "type": "object" } ] }, "title": "Managed Request Transforms", "uniqueItems": true }, "managed_response_headers": { "description": "The list of Managed Response Transforms.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/rulesets_ManagedTransform" }, { "properties": { "id": { "type": "string", "example": "add_security_headers" } }, "type": "object" } ] }, "title": "Managed Response Transforms", "uniqueItems": true } }, "title": "Managed Transforms Patch" }, "rulesets_Message": { "description": "A message.", "type": "object", "properties": { "code": { "description": "A unique code for this message.", "type": "integer", "example": 10000, "title": "Code" }, "message": { "description": "A text description of this message.", "type": "string", "example": "something bad happened", "minLength": 1, "title": "Description" }, "source": { "description": "The source of this message.", "type": "object", "properties": { "pointer": { "description": "A JSON pointer to the field that is the source of the message.", "type": "string", "example": "/rules/0/action", "minLength": 1, "title": "Pointer" } }, "required": [ "pointer" ], "title": "Source" } }, "required": [ "message" ], "title": "Message" }, "rulesets_Messages": { "description": "A list of warning messages.", "type": "array", "items": { "$ref": "#/components/schemas/rulesets_Message" }, "title": "Messages", "uniqueItems": true }, "rulesets_PerPage": { "description": "The number of rulesets to return per page.", "type": "integer", "example": 3, "maximum": 50, "minimum": 1, "title": "Per Page" }, "rulesets_RedirectFromList": { "description": "A redirect based on a bulk list lookup.", "type": "object", "properties": { "key": { "description": "An expression that evaluates to the list lookup key.", "type": "string", "example": "http.request.full_uri", "minLength": 1, "title": "Lookup Key" }, "name": { "description": "The name of the list to match against.", "type": "string", "example": "my_list", "pattern": "^[a-zA-Z0-9_]+$", "title": "List Name" } }, "required": [ "name", "key" ], "title": "Bulk Redirect" }, "rulesets_RedirectFromValue": { "description": "A redirect based on the request properties.", "type": "object", "properties": { "preserve_query_string": { "description": "Whether to keep the query string of the original request.", "type": "boolean", "example": true, "default": false, "title": "Preserve Query String" }, "status_code": { "description": "The status code to use for the redirect.", "type": "integer", "example": 302, "enum": [ 301, 302, 303, 307, 308 ], "title": "Status Code" }, "target_url": { "description": "A URL to redirect the request to.", "type": "object", "maxProperties": 1, "minProperties": 1, "properties": { "expression": { "description": "An expression that evaluates to a URL to redirect the request to.", "type": "string", "example": "concat(\"https://example.com\", http.request.uri.path)", "minLength": 1, "title": "Redirect Expression" }, "value": { "description": "A URL to redirect the request to.", "type": "string", "example": "https://example.com", "minLength": 1, "title": "Redirect Value" } }, "title": "Target URL" } }, "required": [ "target_url" ], "title": "Single Redirect" }, "rulesets_RedirectRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "redirect" ] }, "action_parameters": { "type": "object", "maxProperties": 1, "minProperties": 1, "properties": { "from_list": { "$ref": "#/components/schemas/rulesets_RedirectFromList" }, "from_value": { "$ref": "#/components/schemas/rulesets_RedirectFromValue" } } }, "description": { "type": "string", "example": "Redirect the request." } }, "title": "Redirect Rule", "type": "object" } ] }, "rulesets_RequestRule": { "discriminator": { "mapping": { "block": "#/components/schemas/rulesets_BlockRule", "challenge": "#/components/schemas/rulesets_ChallengeRule", "compress_response": "#/components/schemas/rulesets_CompressResponseRule", "ddos_dynamic": "#/components/schemas/rulesets_DDoSDynamicRule", "execute": "#/components/schemas/rulesets_ExecuteRule", "force_connection_close": "#/components/schemas/rulesets_ForceConnectionCloseRule", "js_challenge": "#/components/schemas/rulesets_JsChallengeRule", "log": "#/components/schemas/rulesets_LogRule", "log_custom_field": "#/components/schemas/rulesets_LogCustomFieldRule", "managed_challenge": "#/components/schemas/rulesets_ManagedChallengeRule", "redirect": "#/components/schemas/rulesets_RedirectRule", "rewrite": "#/components/schemas/rulesets_RewriteRule", "route": "#/components/schemas/rulesets_RouteRule", "score": "#/components/schemas/rulesets_ScoreRule", "serve_error": "#/components/schemas/rulesets_ServeErrorRule", "set_cache_control": "#/components/schemas/rulesets_SetCacheControlRule", "set_cache_settings": "#/components/schemas/rulesets_SetCacheSettingsRule", "set_cache_tags": "#/components/schemas/rulesets_SetCacheTagsRule", "set_config": "#/components/schemas/rulesets_SetConfigRule", "skip": "#/components/schemas/rulesets_SkipRule", "transform_response_html": "#/components/schemas/rulesets_TransformResponseHTMLRule" }, "propertyName": "action" }, "oneOf": [ { "$ref": "#/components/schemas/rulesets_BlockRule" }, { "$ref": "#/components/schemas/rulesets_ChallengeRule" }, { "$ref": "#/components/schemas/rulesets_CompressResponseRule" }, { "$ref": "#/components/schemas/rulesets_DDoSDynamicRule" }, { "$ref": "#/components/schemas/rulesets_ExecuteRule" }, { "$ref": "#/components/schemas/rulesets_ForceConnectionCloseRule" }, { "$ref": "#/components/schemas/rulesets_JsChallengeRule" }, { "$ref": "#/components/schemas/rulesets_LogRule" }, { "$ref": "#/components/schemas/rulesets_LogCustomFieldRule" }, { "$ref": "#/components/schemas/rulesets_ManagedChallengeRule" }, { "$ref": "#/components/schemas/rulesets_RedirectRule" }, { "$ref": "#/components/schemas/rulesets_RewriteRule" }, { "$ref": "#/components/schemas/rulesets_RouteRule" }, { "$ref": "#/components/schemas/rulesets_ScoreRule" }, { "$ref": "#/components/schemas/rulesets_ServeErrorRule" }, { "$ref": "#/components/schemas/rulesets_SetCacheControlRule" }, { "$ref": "#/components/schemas/rulesets_SetCacheSettingsRule" }, { "$ref": "#/components/schemas/rulesets_SetCacheTagsRule" }, { "$ref": "#/components/schemas/rulesets_SetConfigRule" }, { "$ref": "#/components/schemas/rulesets_SkipRule" }, { "$ref": "#/components/schemas/rulesets_TransformResponseHTMLRule" } ] }, "rulesets_RequestRules": { "description": "The list of rules in the ruleset.", "type": "array", "items": { "$ref": "#/components/schemas/rulesets_RequestRule" }, "default": [], "title": "Rules" }, "rulesets_Response": { "description": "A response object.", "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/rulesets_Errors" }, "messages": { "$ref": "#/components/schemas/rulesets_Messages" }, "result": { "description": "A result.", "oneOf": [ { "nullable": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "title": "Result" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "title": "Success" } }, "required": [ "result", "success", "errors", "messages" ], "title": "Response" }, "rulesets_ResponseRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RequestRule" }, { "properties": { "action": { "type": "string" }, "enabled": { "type": "boolean" }, "expression": { "type": "string" }, "id": { "type": "string" }, "ref": { "type": "string" } }, "required": [ "id", "expression", "action", "ref", "enabled" ], "type": "object" } ] }, "rulesets_ResponseRules": { "description": "The list of rules in the ruleset.", "type": "array", "items": { "$ref": "#/components/schemas/rulesets_ResponseRule" }, "title": "Rules" }, "rulesets_ResultInfo": { "description": "Information to navigate the results.", "type": "object", "properties": { "cursors": { "description": "The set of cursors.", "type": "object", "properties": { "after": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Cursor" }, { "title": "After Cursor", "type": "string" } ] } }, "required": [ "after" ], "title": "Cursors" } }, "title": "Result Info" }, "rulesets_RewriteHeaderExpression": { "description": "An expression that evaluates to a value for the header.", "type": "string", "example": "ip.src", "minLength": 1, "title": "Header Expression" }, "rulesets_RewriteHeaderOperation": { "description": "The operation to perform on the header.", "type": "string", "title": "Operation" }, "rulesets_RewriteHeaderValue": { "description": "A static value for the header.", "type": "string", "example": "my-header-value", "minLength": 1, "title": "Header Value" }, "rulesets_RewriteHeaders": { "description": "A map of headers to rewrite.", "type": "object", "example": { "client-http-version": { "expression": "http.request.version", "operation": "set" } }, "additionalProperties": { "oneOf": [ { "description": "A header with a static value to add.", "properties": { "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RewriteHeaderOperation" }, { "enum": [ "add" ], "type": "string" } ] }, "value": { "$ref": "#/components/schemas/rulesets_RewriteHeaderValue" } }, "required": [ "operation", "value" ], "title": "Add Static Header", "type": "object" }, { "description": "A header with a dynamic value to add.", "properties": { "expression": { "$ref": "#/components/schemas/rulesets_RewriteHeaderExpression" }, "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RewriteHeaderOperation" }, { "enum": [ "add" ], "type": "string" } ] } }, "required": [ "operation", "expression" ], "title": "Add Dynamic Header", "type": "object" }, { "description": "A header with a static value to set.", "properties": { "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RewriteHeaderOperation" }, { "enum": [ "set" ], "type": "string" } ] }, "value": { "$ref": "#/components/schemas/rulesets_RewriteHeaderValue" } }, "required": [ "operation", "value" ], "title": "Set Static Header", "type": "object" }, { "description": "A header with a dynamic value to set.", "properties": { "expression": { "$ref": "#/components/schemas/rulesets_RewriteHeaderExpression" }, "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RewriteHeaderOperation" }, { "enum": [ "set" ], "type": "string" } ] } }, "required": [ "operation", "expression" ], "title": "Set Dynamic Header", "type": "object" }, { "description": "A header to remove.", "properties": { "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RewriteHeaderOperation" }, { "enum": [ "remove" ], "type": "string" } ] } }, "required": [ "operation" ], "title": "Remove Header", "type": "object" } ] }, "minProperties": 1, "title": "Headers" }, "rulesets_RewriteRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "rewrite" ] }, "action_parameters": { "type": "object", "minProperties": 1, "properties": { "headers": { "$ref": "#/components/schemas/rulesets_RewriteHeaders" }, "uri": { "$ref": "#/components/schemas/rulesets_RewriteUri" } } }, "description": { "type": "string", "example": "Rewrite properties of the request or response." } }, "title": "Rewrite Rule", "type": "object" } ] }, "rulesets_RewriteUri": { "allOf": [ { "anyOf": [ { "description": "A URI path rewrite.", "properties": { "path": { "$ref": "#/components/schemas/rulesets_RewriteUriPath" } }, "required": [ "path" ], "title": "URI Path", "type": "object" }, { "description": "A URI query rewrite.", "properties": { "query": { "$ref": "#/components/schemas/rulesets_RewriteUriQuery" } }, "required": [ "query" ], "title": "URI Query", "type": "object" } ] }, { "properties": { "origin": { "description": "Whether to propagate the rewritten URI to origin.", "type": "boolean", "example": false, "readOnly": true, "title": "Origin" } }, "type": "object" } ] }, "rulesets_RewriteUriPath": { "description": "A URI path rewrite.", "type": "object", "properties": { "expression": { "description": "An expression that evaluates to a value to rewrite the URI path to.", "type": "string", "example": "regex_replace(http.request.uri.path, \"/foo$\", \"/bar\")", "minLength": 1, "title": "Path Expression" }, "value": { "description": "A value to rewrite the URI path to.", "type": "string", "example": "/foo", "minLength": 1, "title": "Path Value" } }, "maxProperties": 1, "minProperties": 1, "title": "URI Path" }, "rulesets_RewriteUriQuery": { "description": "A URI query rewrite.", "type": "object", "properties": { "expression": { "description": "An expression that evaluates to a value to rewrite the URI query to.", "type": "string", "example": "regex_replace(http.request.uri.query, \"foo=bar\", \"\")", "minLength": 1, "title": "Query Expression" }, "value": { "description": "A value to rewrite the URI query to.", "type": "string", "example": "foo=bar", "title": "Query Value" } }, "maxProperties": 1, "minProperties": 1, "title": "URI Query" }, "rulesets_RouteHostHeader": { "description": "A value to rewrite the HTTP host header to.", "type": "string", "example": "static.example.com", "minLength": 1, "title": "Host Header" }, "rulesets_RouteOrigin": { "description": "An origin to route to.", "type": "object", "properties": { "host": { "description": "A resolved host to route to.", "type": "string", "example": "static.example.com", "minLength": 1, "title": "Host" }, "port": { "description": "A destination port to route to.", "type": "integer", "example": 80, "maximum": 65535, "minimum": 1, "title": "Port" } }, "minProperties": 1, "title": "Origin" }, "rulesets_RouteRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "route" ] }, "action_parameters": { "type": "object", "minProperties": 1, "properties": { "host_header": { "$ref": "#/components/schemas/rulesets_RouteHostHeader" }, "origin": { "$ref": "#/components/schemas/rulesets_RouteOrigin" }, "sni": { "$ref": "#/components/schemas/rulesets_RouteSNI" } } }, "description": { "type": "string", "example": "Select an origin server to route the request to." } }, "title": "Route Rule", "type": "object" } ] }, "rulesets_RouteSNI": { "description": "A Server Name Indication (SNI) override.", "type": "object", "properties": { "value": { "description": "A value to override the SNI to.", "type": "string", "example": "static.example.com", "minLength": 1, "title": "Value" } }, "required": [ "value" ], "title": "Server Name Indication" }, "rulesets_Rule": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/rulesets_RuleAction" }, "action_parameters": { "description": "The parameters configuring the rule's action.", "type": "object", "default": {}, "title": "Action Parameters" }, "categories": { "$ref": "#/components/schemas/rulesets_RuleCategories" }, "description": { "description": "An informative description of the rule.", "type": "string", "default": "", "title": "Description" }, "enabled": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RuleEnabled" }, { "default": true, "type": "boolean" } ] }, "exposed_credential_check": { "$ref": "#/components/schemas/rulesets_RuleExposedCredentialCheck" }, "expression": { "description": "The expression defining which traffic will match the rule.", "type": "string", "example": "ip.src eq 1.1.1.1", "minLength": 1, "title": "Expression" }, "id": { "$ref": "#/components/schemas/rulesets_RuleId" }, "last_updated": { "description": "The timestamp of when the rule was last modified.", "type": "string", "format": "date-time", "example": "2000-01-01T00:00:00Z", "readOnly": true, "title": "Last Updated", "x-stainless-skip": [ "terraform" ] }, "logging": { "$ref": "#/components/schemas/rulesets_RuleLogging" }, "ratelimit": { "$ref": "#/components/schemas/rulesets_RuleRatelimit" }, "ref": { "description": "The reference of the rule (the rule's ID by default).", "type": "string", "example": "my_ref", "minLength": 1, "title": "Ref" }, "version": { "description": "The version of the rule.", "type": "string", "example": "1", "pattern": "^[0-9]+$", "readOnly": true, "title": "Version", "x-stainless-skip": [ "terraform" ] } }, "required": [ "version", "last_updated" ], "title": "Rule" }, "rulesets_RuleAction": { "description": "The action to perform when the rule matches.", "type": "string", "pattern": "^[a-z_]+$", "title": "Action" }, "rulesets_RuleCategories": { "description": "The categories of the rule.", "type": "array", "items": { "$ref": "#/components/schemas/rulesets_RuleCategory" }, "minItems": 1, "readOnly": true, "title": "Categories", "uniqueItems": true }, "rulesets_RuleCategory": { "description": "The category of a rule.", "type": "string", "example": "directory-traversal", "minLength": 1, "title": "Category" }, "rulesets_RuleEnabled": { "description": "Whether the rule should be executed.", "type": "boolean", "example": true, "title": "Enabled" }, "rulesets_RuleExposedCredentialCheck": { "description": "Configuration for exposed credential checking.", "type": "object", "properties": { "password_expression": { "description": "An expression that selects the password used in the credentials check.", "type": "string", "example": "url_decode(http.request.body.form[\\\"password\\\"][0])", "minLength": 1, "title": "Password Expression" }, "username_expression": { "description": "An expression that selects the user ID used in the credentials check.", "type": "string", "example": "url_decode(http.request.body.form[\\\"username\\\"][0])", "minLength": 1, "title": "Username Expression" } }, "required": [ "username_expression", "password_expression" ], "title": "Exposed Credential Check" }, "rulesets_RuleId": { "description": "The unique ID of the rule.", "type": "string", "example": "3a03d665bac047339bb530ecb439a90d", "pattern": "^[0-9a-f]{32}$", "title": "Rule ID" }, "rulesets_RuleLogging": { "description": "An object configuring the rule's logging behavior.", "type": "object", "properties": { "enabled": { "description": "Whether to generate a log when the rule matches.", "type": "boolean", "example": true, "title": "Enabled" } }, "required": [ "enabled" ], "title": "Logging" }, "rulesets_RulePosition": { "description": "An object configuring where the rule will be placed.", "type": "object", "title": "Position" }, "rulesets_RuleRatelimit": { "description": "An object configuring the rule's rate limit behavior.", "type": "object", "properties": { "characteristics": { "description": "Characteristics of the request on which the rate limit counter will be incremented.", "type": "array", "items": { "description": "The characteristic of the request.", "example": "cf.colo.id", "minLength": 1, "title": "Characteristic", "type": "string" }, "minItems": 1, "title": "Characteristics", "uniqueItems": true }, "counting_expression": { "description": "An expression that defines when the rate limit counter should be incremented. It defaults to the same as the rule's expression.", "type": "string", "example": "http.request.body.raw eq \"abcd\"", "minLength": 1, "title": "Counting Expression" }, "mitigation_timeout": { "description": "Period of time in seconds after which the action will be disabled following its first execution.", "type": "integer", "example": 600, "title": "Mitigation Timeout" }, "period": { "description": "Period in seconds over which the counter is being incremented.", "type": "integer", "example": 60, "minimum": 0, "title": "Period" }, "requests_per_period": { "description": "The threshold of requests per period after which the action will be executed for the first time.", "type": "integer", "example": 1000, "minimum": 1, "title": "Requests per Period" }, "requests_to_origin": { "description": "Whether counting is only performed when an origin is reached.", "type": "boolean", "example": true, "default": false, "title": "Requests to Origin" }, "score_per_period": { "description": "The score threshold per period for which the action will be executed the first time.", "type": "integer", "example": 400, "title": "Score per Period" }, "score_response_header_name": { "description": "A response header name provided by the origin, which contains the score to increment rate limit counter with.", "type": "string", "example": "my-score", "minLength": 1, "title": "Score Response Header Name" } }, "required": [ "characteristics", "period" ], "title": "Rate Limit" }, "rulesets_Ruleset": { "description": "A ruleset object.", "type": "object", "properties": { "description": { "description": "An informative description of the ruleset.", "type": "string", "example": "A description for my ruleset.", "default": "", "title": "Description" }, "id": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RulesetId" }, { "readOnly": true, "type": "string" } ] }, "last_updated": { "description": "The timestamp of when the ruleset was last modified.", "type": "string", "format": "date-time", "example": "2000-01-01T00:00:00Z", "readOnly": true, "title": "Last Updated" }, "name": { "description": "The human-readable name of the ruleset.", "type": "string", "example": "My ruleset", "minLength": 1, "title": "Name" }, "version": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RulesetVersion" }, { "readOnly": true, "type": "string" } ] } }, "required": [ "id", "version", "last_updated" ], "title": "Ruleset" }, "rulesets_RulesetId": { "description": "The unique ID of the ruleset.", "type": "string", "example": "2f2feab2026849078ba485f918791bdc", "pattern": "^[0-9a-f]{32}$", "title": "Ruleset ID" }, "rulesets_RulesetKind": { "description": "The kind of the ruleset.", "type": "string", "example": "root", "enum": [ "managed", "custom", "root", "zone" ], "title": "Kind" }, "rulesets_RulesetPhase": { "description": "The phase of the ruleset.", "type": "string", "example": "http_request_firewall_custom", "enum": [ "ddos_l4", "ddos_l7", "http_config_settings", "http_custom_errors", "http_log_custom_fields", "http_ratelimit", "http_request_cache_settings", "http_request_dynamic_redirect", "http_request_firewall_custom", "http_request_firewall_managed", "http_request_late_transform", "http_request_origin", "http_request_redirect", "http_request_sanitize", "http_request_sbfm", "http_request_transform", "http_response_cache_settings", "http_response_compression", "http_response_firewall_managed", "http_response_headers_transform", "magic_transit", "magic_transit_ids_managed", "magic_transit_managed", "magic_transit_ratelimit" ], "title": "Phase" }, "rulesets_RulesetVersion": { "description": "The version of the ruleset.", "type": "string", "example": "1", "pattern": "^[0-9]+$", "title": "Version" }, "rulesets_ScoreIncrement": { "description": "A delta to change the score by, which can be either positive or negative.", "type": "integer", "example": 3, "title": "Increment" }, "rulesets_ScoreRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "score" ] }, "action_parameters": { "type": "object", "properties": { "increment": { "$ref": "#/components/schemas/rulesets_ScoreIncrement" } }, "required": [ "increment" ] }, "description": { "type": "string", "example": "Increment the cumulative score." } }, "title": "Score Rule", "type": "object" } ] }, "rulesets_ServeErrorAssetName": { "description": "The name of a custom asset to serve as the error response.", "type": "string", "example": "500_errors", "minLength": 1, "title": "Asset Name" }, "rulesets_ServeErrorContent": { "description": "The response content.", "type": "string", "example": "{\n \"error\": \"1xxx error occurred\"\n}", "minLength": 1, "title": "Content" }, "rulesets_ServeErrorContentType": { "description": "The content type header to set with the error response.", "type": "string", "example": "application/json", "enum": [ "application/json", "text/html", "text/plain", "text/xml" ], "title": "Content Type" }, "rulesets_ServeErrorRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "serve_error" ] }, "action_parameters": { "allOf": [ { "properties": { "content_type": { "$ref": "#/components/schemas/rulesets_ServeErrorContentType" }, "status_code": { "$ref": "#/components/schemas/rulesets_ServeErrorStatusCode" } }, "required": [ "content_type" ], "type": "object" }, { "oneOf": [ { "properties": { "content": { "$ref": "#/components/schemas/rulesets_ServeErrorContent" } }, "required": [ "content" ], "title": "Action Parameters (Content)", "type": "object" }, { "properties": { "asset_name": { "$ref": "#/components/schemas/rulesets_ServeErrorAssetName" } }, "required": [ "asset_name" ], "title": "Action Parameters (Asset)", "type": "object" } ] } ] }, "description": { "type": "string", "example": "Customize the serving of errors." } }, "title": "Serve Error Rule", "type": "object" } ] }, "rulesets_ServeErrorStatusCode": { "description": "The status code to use for the error.", "type": "integer", "example": 500, "maximum": 999, "minimum": 400, "title": "Status Code" }, "rulesets_SetCacheControlCloudflareOnly": { "description": "Whether the directive should only be applied to the Cloudflare CDN cache.", "type": "boolean", "example": false, "default": false, "title": "Cloudflare Only" }, "rulesets_SetCacheControlDirective": { "description": "A cache-control directive configuration.", "oneOf": [ { "description": "Set the directive.", "properties": { "cloudflare_only": { "$ref": "#/components/schemas/rulesets_SetCacheControlCloudflareOnly" }, "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_SetCacheControlOperation" }, { "enum": [ "set" ], "type": "string" } ] } }, "required": [ "operation" ], "title": "Set Directive", "type": "object" }, { "description": "Remove the directive.", "properties": { "cloudflare_only": { "$ref": "#/components/schemas/rulesets_SetCacheControlCloudflareOnly" }, "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_SetCacheControlOperation" }, { "enum": [ "remove" ], "type": "string" } ] } }, "required": [ "operation" ], "title": "Remove Directive", "type": "object" } ], "title": "Cache Control Directive" }, "rulesets_SetCacheControlDirectiveWithQualifiers": { "description": "A cache-control directive configuration that accepts optional qualifiers (header names).", "oneOf": [ { "description": "Set the directive with optional qualifiers.", "properties": { "cloudflare_only": { "$ref": "#/components/schemas/rulesets_SetCacheControlCloudflareOnly" }, "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_SetCacheControlOperation" }, { "enum": [ "set" ], "type": "string" } ] }, "qualifiers": { "description": "Optional list of header names to qualify the directive (e.g., for \"private\" or \"no-cache\" directives).", "type": "array", "items": { "description": "A header name to qualify the directive.", "example": "X-Custom-Header", "minLength": 1, "title": "Qualifier", "type": "string" }, "title": "Qualifiers", "uniqueItems": true } }, "required": [ "operation" ], "title": "Set Directive", "type": "object" }, { "description": "Remove the directive.", "properties": { "cloudflare_only": { "$ref": "#/components/schemas/rulesets_SetCacheControlCloudflareOnly" }, "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_SetCacheControlOperation" }, { "enum": [ "remove" ], "type": "string" } ] } }, "required": [ "operation" ], "title": "Remove Directive", "type": "object" } ], "title": "Cache Control Directive With Optional Qualifiers" }, "rulesets_SetCacheControlDirectiveWithValue": { "description": "A cache-control directive configuration that accepts a duration value in seconds.", "oneOf": [ { "description": "Set the directive with a duration value in seconds.", "properties": { "cloudflare_only": { "$ref": "#/components/schemas/rulesets_SetCacheControlCloudflareOnly" }, "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_SetCacheControlOperation" }, { "enum": [ "set" ], "type": "string" } ] }, "value": { "description": "The duration value in seconds for the directive.", "type": "integer", "example": 3600, "minimum": 0, "title": "Value" } }, "required": [ "operation", "value" ], "title": "Set Directive", "type": "object" }, { "description": "Remove the directive.", "properties": { "cloudflare_only": { "$ref": "#/components/schemas/rulesets_SetCacheControlCloudflareOnly" }, "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_SetCacheControlOperation" }, { "enum": [ "remove" ], "type": "string" } ] } }, "required": [ "operation" ], "title": "Remove Directive", "type": "object" } ], "title": "Cache Control Directive With Duration Seconds Value" }, "rulesets_SetCacheControlOperation": { "description": "The operation to perform on the cache-control directive.", "type": "string", "example": "set", "enum": [ "set", "remove" ], "title": "Operation" }, "rulesets_SetCacheControlRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "set_cache_control" ] }, "action_parameters": { "type": "object", "minProperties": 1, "properties": { "immutable": { "$ref": "#/components/schemas/rulesets_SetCacheControlDirective" }, "max-age": { "$ref": "#/components/schemas/rulesets_SetCacheControlDirectiveWithValue" }, "must-revalidate": { "$ref": "#/components/schemas/rulesets_SetCacheControlDirective" }, "must-understand": { "$ref": "#/components/schemas/rulesets_SetCacheControlDirective" }, "no-cache": { "$ref": "#/components/schemas/rulesets_SetCacheControlDirectiveWithQualifiers" }, "no-store": { "$ref": "#/components/schemas/rulesets_SetCacheControlDirective" }, "no-transform": { "$ref": "#/components/schemas/rulesets_SetCacheControlDirective" }, "private": { "$ref": "#/components/schemas/rulesets_SetCacheControlDirectiveWithQualifiers" }, "proxy-revalidate": { "$ref": "#/components/schemas/rulesets_SetCacheControlDirective" }, "public": { "$ref": "#/components/schemas/rulesets_SetCacheControlDirective" }, "s-maxage": { "$ref": "#/components/schemas/rulesets_SetCacheControlDirectiveWithValue" }, "stale-if-error": { "$ref": "#/components/schemas/rulesets_SetCacheControlDirectiveWithValue" }, "stale-while-revalidate": { "$ref": "#/components/schemas/rulesets_SetCacheControlDirectiveWithValue" } } }, "description": { "type": "string", "example": "Modify the cache-control header directives in an Origin response." } }, "title": "Set Cache Control Rule", "type": "object" } ] }, "rulesets_SetCacheSettingsAdditionalCacheablePorts": { "description": "A list of additional ports that caching should be enabled on.", "type": "array", "items": { "description": "A port to enable caching on.", "example": 8080, "maximum": 65535, "minimum": 1, "title": "Additional Cacheable Port", "type": "integer" }, "minItems": 1, "title": "Additional Cacheable Ports (Enterprise-Only)", "uniqueItems": true }, "rulesets_SetCacheSettingsBrowserTTL": { "description": "How long client browsers should cache the response. Cloudflare cache purge will not purge content cached on client browsers, so high browser TTLs may lead to stale content.", "type": "object", "properties": { "default": { "description": "The browser TTL (in seconds) if you choose the \"override_origin\" mode.", "type": "integer", "example": 60, "minimum": 0, "title": "Default TTL" }, "mode": { "description": "The browser TTL mode.", "type": "string", "example": "override_origin", "enum": [ "respect_origin", "bypass_by_default", "override_origin", "bypass" ], "title": "TTL Mode" } }, "required": [ "mode" ], "title": "Browser TTL" }, "rulesets_SetCacheSettingsCache": { "description": "Whether the request's response from the origin is eligible for caching. Caching itself will still depend on the cache control header and your other caching configurations.", "type": "boolean", "example": true, "title": "Cache" }, "rulesets_SetCacheSettingsCacheKey": { "description": "Which components of the request are included in or excluded from the cache key Cloudflare uses to store the response in cache.", "type": "object", "properties": { "cache_by_device_type": { "description": "Whether to separate cached content based on the visitor's device type.", "type": "boolean", "example": true, "title": "Cache by Device Type" }, "cache_deception_armor": { "description": "Whether to protect from web cache deception attacks, while allowing static assets to be cached.", "type": "boolean", "example": true, "title": "Cache Deception Armor" }, "custom_key": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsCustomCacheKey" }, "ignore_query_strings_order": { "description": "Whether to treat requests with the same query parameters the same, regardless of the order those query parameters are in.", "type": "boolean", "example": true, "title": "Ignore Query Strings Order" } }, "title": "Cache Key" }, "rulesets_SetCacheSettingsCacheReserve": { "description": "Settings to determine whether the request's response from origin is eligible for Cache Reserve (requires a Cache Reserve add-on plan).", "type": "object", "properties": { "eligible": { "description": "Whether Cache Reserve is enabled. If this is true and a request meets eligibility criteria, Cloudflare will write the resource to Cache Reserve.", "type": "boolean", "example": true, "title": "Eligible" }, "minimum_file_size": { "description": "The minimum file size eligible for storage in Cache Reserve.", "type": "integer", "example": 1024, "minimum": 0, "title": "Minimum File Size" } }, "required": [ "eligible" ], "title": "Cache Reserve" }, "rulesets_SetCacheSettingsCustomCacheKey": { "description": "Which components of the request are included or excluded from the cache key.", "type": "object", "properties": { "cookie": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsCustomCacheKeyCookie" }, "header": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsCustomCacheKeyHeader" }, "host": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsCustomCacheKeyHost" }, "query_string": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsCustomCacheKeyQueryString" }, "user": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsCustomCacheKeyUser" } }, "title": "Custom Cache Key" }, "rulesets_SetCacheSettingsCustomCacheKeyCookie": { "description": "Which cookies to include in the cache key.", "type": "object", "properties": { "check_presence": { "description": "A list of cookies to check for the presence of. The presence of these cookies is included in the cache key.", "type": "array", "items": { "description": "The name of the cookie to check for the presence of.", "example": "myCookie", "minLength": 1, "title": "Cookie Name", "type": "string" }, "minItems": 1, "title": "Check Presence", "uniqueItems": true }, "include": { "description": "A list of cookies to include in the cache key.", "type": "array", "items": { "description": "The name of the cookie to include.", "example": "myCookie", "minLength": 1, "title": "Cookie Name", "type": "string" }, "minItems": 1, "title": "Include", "uniqueItems": true } }, "title": "Cookies" }, "rulesets_SetCacheSettingsCustomCacheKeyHeader": { "description": "Which headers to include in the cache key.", "type": "object", "properties": { "check_presence": { "description": "A list of headers to check for the presence of. The presence of these headers is included in the cache key.", "type": "array", "items": { "description": "The name of the header to check for the presence of.", "example": "my-header", "minLength": 1, "title": "Header", "type": "string" }, "minItems": 1, "title": "Check Presence", "uniqueItems": true }, "contains": { "description": "A mapping of header names to a list of values. If a header is present in the request and contains any of the values provided, its value is included in the cache key.", "type": "object", "example": { "my-header": [ "my-header-value-1", "my-header-value-2" ] }, "additionalProperties": { "description": "A list of values to match the header against.", "items": { "description": "The header value to match against.", "example": "my-header-value", "minLength": 1, "title": "Header Value", "type": "string" }, "minItems": 1, "title": "Header Values", "type": "array", "uniqueItems": true }, "minProperties": 1, "title": "Contains" }, "exclude_origin": { "description": "Whether to exclude the origin header in the cache key.", "type": "boolean", "example": true, "title": "Exclude Origin" }, "include": { "description": "A list of headers to include in the cache key.", "type": "array", "items": { "description": "The name of the header to include.", "example": "my-header", "minLength": 1, "title": "Header", "type": "string" }, "minItems": 1, "title": "Include", "uniqueItems": true } }, "title": "Headers" }, "rulesets_SetCacheSettingsCustomCacheKeyHost": { "description": "How to use the host in the cache key.", "type": "object", "properties": { "resolved": { "description": "Whether to use the resolved host in the cache key.", "type": "boolean", "example": true, "title": "Use Resolved Host" } }, "title": "Host" }, "rulesets_SetCacheSettingsCustomCacheKeyQueryString": { "description": "Which query string parameters to include in or exclude from the cache key.", "type": "object", "properties": { "exclude": { "description": "Which query string parameters to exclude from the cache key.", "type": "object", "maxProperties": 1, "minProperties": 1, "properties": { "all": { "description": "Whether to exclude all query string parameters from the cache key.", "type": "boolean", "enum": [ true ], "title": "Exclude All" }, "list": { "description": "A list of query string parameters to exclude from the cache key.", "type": "array", "items": { "description": "The name of the query string parameter to exclude.", "example": "foo", "minLength": 1, "title": "Parameter Name", "type": "string" }, "minItems": 1, "title": "Exclude List", "uniqueItems": true } }, "title": "Exclude" }, "include": { "description": "Which query string parameters to include in the cache key.", "type": "object", "maxProperties": 1, "minProperties": 1, "properties": { "all": { "description": "Whether to include all query string parameters in the cache key.", "type": "boolean", "enum": [ true ], "title": "Include All" }, "list": { "description": "A list of query string parameters to include in the cache key.", "type": "array", "items": { "description": "The name of the query string parameter to include.", "example": "foo", "minLength": 1, "title": "Parameter Name", "type": "string" }, "minItems": 1, "title": "Include List", "uniqueItems": true } }, "title": "Include" } }, "maxProperties": 1, "title": "Query String Parameters" }, "rulesets_SetCacheSettingsCustomCacheKeyUser": { "description": "How to use characteristics of the request user agent in the cache key.", "type": "object", "properties": { "device_type": { "description": "Whether to use the user agent's device type in the cache key.", "type": "boolean", "example": true, "title": "Device Type" }, "geo": { "description": "Whether to use the user agents's country in the cache key.", "type": "boolean", "example": true, "title": "Country" }, "lang": { "description": "Whether to use the user agent's language in the cache key.", "type": "boolean", "example": true, "title": "Language" } }, "title": "User" }, "rulesets_SetCacheSettingsEdgeTTL": { "description": "How long the Cloudflare edge network should cache the response.", "type": "object", "properties": { "default": { "description": "The edge TTL (in seconds) if you choose the \"override_origin\" mode.", "type": "integer", "example": 60, "minimum": 0, "title": "Default TTL" }, "mode": { "description": "The edge TTL mode.", "type": "string", "example": "override_origin", "enum": [ "respect_origin", "bypass_by_default", "override_origin" ], "title": "TTL Mode" }, "status_code_ttl": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsStatusCodeTTL" } }, "required": [ "mode" ], "title": "Edge TTL" }, "rulesets_SetCacheSettingsOriginCacheControl": { "description": "Whether Cloudflare will aim to strictly adhere to RFC 7234.", "type": "boolean", "example": true, "title": "Origin Cache Control (Enterprise-Only)" }, "rulesets_SetCacheSettingsOriginErrorPagePassthru": { "description": "Whether to generate Cloudflare error pages for issues from the origin server.", "type": "boolean", "example": true, "title": "Origin Error Page Passthrough" }, "rulesets_SetCacheSettingsOriginRangeRequests": { "description": "Controls whether Cloudflare fetches a large asset from the origin as a series of range requests instead of one whole-body request.", "type": "object", "properties": { "mode": { "description": "Whether to use range requests. `default` is the behaviour the zone gets without this rule.", "type": "string", "example": "on", "enum": [ "on", "off", "default" ], "title": "Mode" } }, "required": [ "mode" ], "title": "Origin Range Requests" }, "rulesets_SetCacheSettingsReadTimeout": { "description": "A timeout value between two successive read operations to use for your origin server. Historically, the timeout value between two read options from Cloudflare to an origin server is 100 seconds. If you are attempting to reduce HTTP 524 errors because of timeouts from an origin server, try increasing this timeout value.", "type": "integer", "example": 900, "maximum": 6000, "minimum": 100, "title": "Read Timeout (Enterprise-Only)" }, "rulesets_SetCacheSettingsRespectStrongEtags": { "description": "Whether Cloudflare should respect strong ETag (entity tag) headers. If false, Cloudflare converts strong ETag headers to weak ETag headers.", "type": "boolean", "example": true, "title": "Respect Strong ETags" }, "rulesets_SetCacheSettingsRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "set_cache_settings" ] }, "action_parameters": { "type": "object", "minProperties": 1, "properties": { "additional_cacheable_ports": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsAdditionalCacheablePorts" }, "browser_ttl": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsBrowserTTL" }, "cache": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsCache" }, "cache_key": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsCacheKey" }, "cache_reserve": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsCacheReserve" }, "edge_ttl": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsEdgeTTL" }, "origin_cache_control": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsOriginCacheControl" }, "origin_error_page_passthru": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsOriginErrorPagePassthru" }, "origin_range_requests": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsOriginRangeRequests" }, "read_timeout": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsReadTimeout" }, "respect_strong_etags": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsRespectStrongEtags" }, "serve_stale": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsServeStale" }, "shared_dictionary": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsSharedDictionary" }, "strip_etags": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsStripETags" }, "strip_last_modified": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsStripLastModified" }, "strip_set_cookie": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsStripSetCookie" }, "vary": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsVary" } } }, "description": { "type": "string", "example": "Configure settings for how the response is cached." } }, "title": "Set Cache Settings Rule", "type": "object" } ] }, "rulesets_SetCacheSettingsServeStale": { "description": "When to serve stale content from cache.", "type": "object", "properties": { "disable_stale_while_updating": { "description": "Whether Cloudflare should disable serving stale content while getting the latest content from the origin.", "type": "boolean", "example": true, "title": "Disable Stale While Updating" } }, "title": "Serve Stale" }, "rulesets_SetCacheSettingsSharedDictionary": { "description": "Configuration for shared dictionary compression. When set, Cloudflare injects Use-As-Dictionary headers on matching cacheable responses.", "type": "object", "properties": { "match_pattern": { "description": "URL pattern for the Use-As-Dictionary match field. This pattern specifies which URLs can use this response as a dictionary.", "type": "string", "example": "/static/js/*.js", "maxLength": 1024, "minLength": 1, "title": "Match Pattern" } }, "required": [ "match_pattern" ], "title": "Shared Dictionary" }, "rulesets_SetCacheSettingsStatusCodeTTL": { "description": "A list of TTLs to apply to specific status codes or status code ranges.", "type": "array", "items": { "maxProperties": 2, "minProperties": 2, "properties": { "status_code": { "description": "A single status code to apply the TTL to.", "type": "integer", "example": 200, "maximum": 999, "minimum": 100, "title": "Status Code" }, "status_code_range": { "description": "A range of status codes to apply the TTL to.", "type": "object", "minProperties": 1, "properties": { "from": { "description": "The lower bound of the range.", "type": "integer", "example": 200, "maximum": 999, "minimum": 100, "title": "From" }, "to": { "description": "The upper bound of the range.", "type": "integer", "example": 299, "maximum": 999, "minimum": 100, "title": "To" } }, "title": "Status Code Range" }, "value": { "description": "The time to cache the response for (in seconds). A value of 0 is equivalent to setting the cache control header with the value \"no-cache\". A value of -1 is equivalent to setting the cache control header with the value of \"no-store\".", "type": "integer", "example": 0, "title": "TTL Value" } }, "required": [ "value" ], "type": "object" }, "minItems": 1, "title": "Status Code TTLs", "uniqueItems": true }, "rulesets_SetCacheSettingsStripETags": { "description": "Whether to strip ETag headers from the origin response before caching.", "type": "boolean", "example": true, "title": "Strip ETags" }, "rulesets_SetCacheSettingsStripLastModified": { "description": "Whether to strip Last-Modified headers from the origin response before caching.", "type": "boolean", "example": true, "title": "Strip Last-Modified" }, "rulesets_SetCacheSettingsStripSetCookie": { "description": "Whether to strip Set-Cookie headers from the origin response before caching.", "type": "boolean", "example": true, "title": "Strip Set-Cookie" }, "rulesets_SetCacheSettingsVary": { "description": "Controls how cached responses vary based on request headers. `default` is required by the API and applies to any Vary response header that does not have a per-header override.", "type": "object", "properties": { "default": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsVaryDefault" }, "headers": { "description": "A mapping of lowercase request header names to their vary configuration.", "type": "object", "example": { "accept": { "action": "normalize", "media_types": [ "image/webp", "image/png" ] } }, "additionalProperties": { "$ref": "#/components/schemas/rulesets_SetCacheSettingsVaryHeader" }, "maxProperties": 50, "title": "Headers" } }, "minProperties": 1, "title": "Vary" }, "rulesets_SetCacheSettingsVaryDefault": { "description": "Controls how response Vary headers without a per-header override contribute to the cache key.", "type": "object", "properties": { "action": { "description": "How the header value is treated when building the cache key.", "type": "string", "example": "normalize", "enum": [ "bypass", "passthrough", "normalize" ], "title": "Action" } }, "required": [ "action" ], "title": "Vary Default" }, "rulesets_SetCacheSettingsVaryHeader": { "description": "Controls how a single request header contributes to the cache key.", "type": "object", "properties": { "action": { "description": "How the header value is treated when building the cache key.", "type": "string", "example": "normalize", "enum": [ "bypass", "passthrough", "normalize" ], "title": "Action" }, "languages": { "description": "The set of languages to normalize against. Only valid for the `accept-language` header.", "type": "array", "items": { "description": "A language tag to normalize against. Must be printable ASCII.", "example": "en", "maxLength": 64, "minLength": 1, "pattern": "^[ -~]+$", "title": "Language", "type": "string" }, "maxItems": 20, "title": "Languages" }, "media_types": { "description": "The set of media types to normalize against. Only valid for the `accept` header.", "type": "array", "items": { "description": "A media type to normalize against. Must be printable ASCII.", "example": "image/webp", "maxLength": 255, "minLength": 1, "pattern": "^[ -~]+$", "title": "Media Type", "type": "string" }, "maxItems": 10, "title": "Media Types" } }, "required": [ "action" ], "title": "Vary Header" }, "rulesets_SetCacheTagsExpression": { "description": "An expression that evaluates to an array of cache tag values.", "type": "string", "example": "http.request.uri.path.extension", "minLength": 1, "title": "Expression" }, "rulesets_SetCacheTagsOperation": { "description": "The operation to perform on the cache tags.", "type": "string", "example": "add", "enum": [ "add", "remove", "set" ], "title": "Operation" }, "rulesets_SetCacheTagsRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "set_cache_tags" ] }, "action_parameters": { "oneOf": [ { "description": "Add cache tags using a list of values.", "properties": { "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_SetCacheTagsOperation" }, { "enum": [ "add" ], "type": "string" } ] }, "values": { "$ref": "#/components/schemas/rulesets_SetCacheTagsValues" } }, "required": [ "operation", "values" ], "title": "Add Cache Tags (Values)", "type": "object" }, { "description": "Add cache tags using an expression.", "properties": { "expression": { "$ref": "#/components/schemas/rulesets_SetCacheTagsExpression" }, "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_SetCacheTagsOperation" }, { "enum": [ "add" ], "type": "string" } ] } }, "required": [ "operation", "expression" ], "title": "Add Cache Tags (Expression)", "type": "object" }, { "description": "Remove cache tags using a list of values.", "properties": { "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_SetCacheTagsOperation" }, { "enum": [ "remove" ], "type": "string" } ] }, "values": { "$ref": "#/components/schemas/rulesets_SetCacheTagsValues" } }, "required": [ "operation", "values" ], "title": "Remove Cache Tags (Values)", "type": "object" }, { "description": "Remove cache tags using an expression.", "properties": { "expression": { "$ref": "#/components/schemas/rulesets_SetCacheTagsExpression" }, "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_SetCacheTagsOperation" }, { "enum": [ "remove" ], "type": "string" } ] } }, "required": [ "operation", "expression" ], "title": "Remove Cache Tags (Expression)", "type": "object" }, { "description": "Set cache tags using a list of values.", "properties": { "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_SetCacheTagsOperation" }, { "enum": [ "set" ], "type": "string" } ] }, "values": { "$ref": "#/components/schemas/rulesets_SetCacheTagsValues" } }, "required": [ "operation", "values" ], "title": "Set Cache Tags (Values)", "type": "object" }, { "description": "Set cache tags using an expression.", "properties": { "expression": { "$ref": "#/components/schemas/rulesets_SetCacheTagsExpression" }, "operation": { "allOf": [ { "$ref": "#/components/schemas/rulesets_SetCacheTagsOperation" }, { "enum": [ "set" ], "type": "string" } ] } }, "required": [ "operation", "expression" ], "title": "Set Cache Tags (Expression)", "type": "object" } ] }, "description": { "type": "string", "example": "Modify the cache tags associated with the response." } }, "title": "Set Cache Tags Rule", "type": "object" } ] }, "rulesets_SetCacheTagsValues": { "description": "A list of cache tag values.", "type": "array", "items": { "description": "A cache tag value.", "example": "my-cache-tag", "minLength": 1, "title": "Cache Tag", "type": "string" }, "maxItems": 100, "minItems": 1, "title": "Values" }, "rulesets_SetConfigAutominify": { "description": "Which file extensions to minify automatically.", "type": "object", "properties": { "css": { "description": "Whether to minify CSS files.", "type": "boolean", "example": true, "default": false, "title": "CSS" }, "html": { "description": "Whether to minify HTML files.", "type": "boolean", "example": true, "default": false, "title": "HTML" }, "js": { "description": "Whether to minify JavaScript files.", "type": "boolean", "example": true, "default": false, "title": "JavaScript" } }, "title": "Auto-Minify" }, "rulesets_SetConfigRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "set_config" ] }, "action_parameters": { "type": "object", "minProperties": 1, "properties": { "automatic_https_rewrites": { "description": "Whether to enable Automatic HTTPS Rewrites.", "type": "boolean", "example": true, "title": "Automatic HTTPS Rewrites" }, "autominify": { "$ref": "#/components/schemas/rulesets_SetConfigAutominify" }, "bic": { "description": "Whether to enable Browser Integrity Check (BIC).", "type": "boolean", "example": true, "title": "Browser Integrity Check" }, "content_converter": { "description": "Whether to enable content conversion (e.g., HTML to Markdown).", "type": "boolean", "example": true, "title": "Content Converter" }, "disable_apps": { "description": "Whether to disable Cloudflare Apps.", "type": "boolean", "enum": [ true ], "deprecated": true, "title": "Disable Apps", "x-stainless-deprecation-message": "Cloudflare Apps are deprected." }, "disable_pay_per_crawl": { "description": "Whether to disable Pay Per Crawl.", "type": "boolean", "enum": [ true ], "title": "Disable Pay Per Crawl" }, "disable_rum": { "description": "Whether to disable Real User Monitoring (RUM).", "type": "boolean", "enum": [ true ], "title": "Disable RUM" }, "disable_zaraz": { "description": "Whether to disable Zaraz.", "type": "boolean", "enum": [ true ], "title": "Disable Zaraz" }, "email_obfuscation": { "description": "Whether to enable Email Obfuscation.", "type": "boolean", "example": true, "title": "Email Obfuscation" }, "fonts": { "description": "Whether to enable Cloudflare Fonts.", "type": "boolean", "example": true, "title": "Cloudflare Fonts" }, "hotlink_protection": { "description": "Whether to enable Hotlink Protection.", "type": "boolean", "example": true, "title": "Hotlink Protection" }, "mirage": { "description": "Whether to enable Mirage.", "type": "boolean", "example": true, "deprecated": true, "title": "Mirage", "x-stainless-deprecation-message": "Mirage is deprecated. More information at https://developers.cloudflare.com/speed/optimization/images/mirage/." }, "opportunistic_encryption": { "description": "Whether to enable Opportunistic Encryption.", "type": "boolean", "example": true, "title": "Opportunistic Encryption" }, "polish": { "description": "The Polish level to configure.", "type": "string", "example": "off", "enum": [ "off", "lossless", "lossy", "webp" ], "title": "Polish" }, "redirects_for_ai_training": { "description": "Whether to redirect verified AI training crawlers to canonical URLs found in the HTML response.", "type": "boolean", "example": true, "title": "Redirects for AI Training" }, "request_body_buffering": { "description": "The request body buffering mode.", "type": "string", "example": "standard", "enum": [ "none", "standard", "full" ], "title": "Request body buffering" }, "response_body_buffering": { "description": "The response body buffering mode.", "type": "string", "example": "standard", "enum": [ "none", "standard" ], "title": "Response body buffering" }, "rocket_loader": { "description": "Whether to enable Rocket Loader.", "type": "boolean", "example": true, "title": "Rocket Loader" }, "security_level": { "description": "The Security Level to configure.", "type": "string", "example": "off", "enum": [ "off", "essentially_off", "low", "medium", "high", "under_attack" ], "title": "Security Level" }, "server_side_excludes": { "description": "Whether to enable Server-Side Excludes.", "type": "boolean", "example": true, "title": "Server-Side Excludes" }, "ssl": { "description": "The SSL level to configure.", "type": "string", "example": "off", "enum": [ "off", "flexible", "full", "strict", "origin_pull" ], "title": "SSL" }, "sxg": { "description": "Whether to enable Signed Exchanges (SXG).", "type": "boolean", "example": true, "deprecated": true, "title": "Signed Exchanges", "x-stainless-deprecation-message": "Signed Exchanges (SXG) is deprecated." } } }, "description": { "type": "string", "example": "Configure settings for the request and response." } }, "title": "Set Configuration Rule", "type": "object" } ] }, "rulesets_SkipPhase": { "description": "A phase to skip the execution of. This option is only compatible with the products option.", "type": "string", "enum": [ "current" ], "title": "Phase" }, "rulesets_SkipPhases": { "description": "A list of phases to skip the execution of. This option is incompatible with the rulesets option.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RulesetPhase" }, { "description": "The phase to skip the execution of.", "type": "string" } ] }, "minItems": 1, "title": "Phases", "uniqueItems": true }, "rulesets_SkipProducts": { "description": "A list of legacy security products to skip the execution of.", "type": "array", "items": { "description": "The name of a legacy security product to skip the execution of.", "enum": [ "bic", "hot", "rateLimit", "securityLevel", "uaBlock", "waf", "zoneLockdown" ], "example": "bic", "title": "Product", "type": "string" }, "minItems": 1, "title": "Products", "uniqueItems": true }, "rulesets_SkipRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "skip" ] }, "action_parameters": { "type": "object", "minProperties": 1, "properties": { "phase": { "$ref": "#/components/schemas/rulesets_SkipPhase" }, "phases": { "$ref": "#/components/schemas/rulesets_SkipPhases" }, "products": { "$ref": "#/components/schemas/rulesets_SkipProducts" }, "rules": { "$ref": "#/components/schemas/rulesets_SkipRules" }, "ruleset": { "$ref": "#/components/schemas/rulesets_SkipRuleset" }, "rulesets": { "$ref": "#/components/schemas/rulesets_SkipRulesets" } } }, "description": { "type": "string", "example": "Skip executing rulesets, rules, phases, and other products." } }, "title": "Skip Rule", "type": "object" } ] }, "rulesets_SkipRules": { "description": "A mapping of ruleset IDs to a list of rule IDs in that ruleset to skip the execution of. This option is incompatible with the ruleset option.", "type": "object", "example": { "4814384a9e5d4991b9815dcfc25d2f1f": [ "8ac8bc2a661e475d940980f9317f28e1" ] }, "additionalProperties": { "description": "A list of rule IDs in the ruleset to skip the execution of.", "items": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RuleId" }, { "description": "The ID of a rule in the ruleset to skip the execution of.", "example": "8ac8bc2a661e475d940980f9317f28e1", "title": "Rule", "type": "string" } ] }, "minItems": 1, "title": "Rules", "type": "array", "uniqueItems": true }, "minProperties": 1, "title": "Rules" }, "rulesets_SkipRuleset": { "description": "A ruleset to skip the execution of. This option is incompatible with the rulesets option.", "type": "string", "enum": [ "current" ], "title": "Ruleset" }, "rulesets_SkipRulesets": { "description": "A list of ruleset IDs to skip the execution of. This option is incompatible with the ruleset and phases options.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RulesetId" }, { "description": "The ID of a ruleset to skip the execution of.", "example": "4814384a9e5d4991b9815dcfc25d2f1f", "title": "Ruleset", "type": "string" } ] }, "minItems": 1, "title": "Rulesets", "uniqueItems": true }, "rulesets_TransformResponseHTMLRule": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Rule" }, { "properties": { "action": { "type": "string", "enum": [ "transform_response_html" ] }, "action_parameters": { "type": "object", "properties": { "link_maze": { "description": "Enables the link maze transformation on the response.", "type": "object", "title": "Link Maze" } }, "required": [ "link_maze" ] }, "description": { "type": "string", "example": "Apply a HTML transformation to the response." } }, "title": "Transform Response HTML Rule", "type": "object" } ] }, "rulesets_UrlNormalization": { "description": "A URL Normalization object.", "type": "object", "properties": { "scope": { "description": "The scope of the URL normalization.", "type": "string", "example": "incoming", "enum": [ "incoming", "both", "none" ], "title": "Scope" }, "type": { "description": "The type of URL normalization performed by Cloudflare.", "type": "string", "example": "cloudflare", "enum": [ "cloudflare", "rfc3986" ], "title": "Type" } }, "required": [ "type", "scope" ], "title": "URL Normalization" }, "rulesets_ZoneId": { "description": "The unique ID of the zone.", "type": "string", "example": "9f1839b6152d298aca64c4e906b6d074", "pattern": "^[0-9a-f]{32}$", "title": "Zone ID" }, "rum_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/rum_messages" }, "messages": { "$ref": "#/components/schemas/rum_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages" ] }, "rum_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/rum_messages-2" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/rum_messages-2" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "rum_auto_install": { "description": "If enabled, the JavaScript snippet is automatically injected for orange-clouded sites.", "type": "boolean", "example": true, "x-auditable": true }, "rum_create-rule-request": { "type": "object", "properties": { "host": { "type": "string", "example": "example.com" }, "inclusive": { "description": "Whether the rule includes or excludes traffic from being measured.", "type": "boolean", "example": true }, "is_paused": { "description": "Whether the rule is paused or not.", "type": "boolean", "example": false }, "paths": { "type": "array", "items": { "type": "string" }, "example": [ "*" ] } } }, "rum_create-site-request": { "type": "object", "properties": { "auto_install": { "$ref": "#/components/schemas/rum_auto_install" }, "host": { "$ref": "#/components/schemas/rum_host" }, "zone_tag": { "$ref": "#/components/schemas/rum_zone_tag" } } }, "rum_created": { "$ref": "#/components/schemas/rum_timestamp" }, "rum_editable": { "type": "boolean", "example": true }, "rum_empty-response": { "allOf": [ { "$ref": "#/components/schemas/rum_api-response-common" }, { "properties": { "result": { "description": "Empty result object.", "type": "object" } }, "type": "object" } ] }, "rum_enabled": { "description": "Enables or disables RUM. This option can be used only when auto_install is set to true.", "type": "boolean", "example": true, "x-auditable": true }, "rum_host": { "description": "The hostname to use for gray-clouded sites.", "type": "string", "example": "example.com", "x-auditable": true }, "rum_id": { "type": "string", "example": "rum", "x-auditable": true }, "rum_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "rum_is_host_regex": { "description": "Whether to match the hostname using a regular expression.", "type": "boolean", "example": false, "x-auditable": true }, "rum_lite": { "description": "If enabled, the JavaScript snippet will not be injected for visitors from the EU.", "type": "boolean", "x-auditable": true }, "rum_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "rum_messages-2": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "rum_modify-rules-request": { "type": "object", "properties": { "delete_rules": { "description": "A list of rule identifiers to delete.", "type": "array", "items": { "$ref": "#/components/schemas/rum_rule_identifier" } }, "rules": { "description": "A list of rules to create or update.", "type": "array", "items": { "properties": { "host": { "type": "string", "example": "example.com" }, "id": { "$ref": "#/components/schemas/rum_rule_identifier" }, "inclusive": { "type": "boolean", "example": true }, "is_paused": { "type": "boolean", "example": false }, "paths": { "type": "array", "items": { "type": "string" }, "example": [ "*" ] } }, "type": "object" } } } }, "rum_order_by": { "description": "The property used to sort the list of results.", "type": "string", "example": "host", "enum": [ "host", "created" ] }, "rum_page": { "description": "Current page within the paginated list of results.", "type": "number", "example": 1 }, "rum_per_page": { "description": "Number of items to return per page of results.", "type": "number", "example": 10 }, "rum_result_info": { "type": "object", "properties": { "count": { "description": "The total number of items on the current page.", "type": "integer", "example": 10 }, "page": { "description": "Current page within the paginated list of results.", "type": "integer", "example": 1 }, "per_page": { "description": "The maximum number of items to return per page of results.", "type": "integer", "example": 10 }, "total_count": { "description": "The total number of items.", "type": "integer", "example": 25 }, "total_pages": { "description": "The total number of pages.", "type": "integer", "example": 3, "nullable": true } } }, "rum_rule": { "type": "object", "properties": { "created": { "$ref": "#/components/schemas/rum_timestamp" }, "host": { "description": "The hostname the rule will be applied to.", "type": "string", "example": "example.com", "x-auditable": true }, "id": { "$ref": "#/components/schemas/rum_rule_identifier" }, "inclusive": { "description": "Whether the rule includes or excludes traffic from being measured.", "type": "boolean", "example": true, "x-auditable": true }, "is_paused": { "description": "Whether the rule is paused or not.", "type": "boolean", "example": false, "x-auditable": true }, "paths": { "description": "The paths the rule will be applied to.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "*" ] }, "priority": { "type": "number", "example": 1000, "x-auditable": true } } }, "rum_rule-id-response-single": { "allOf": [ { "$ref": "#/components/schemas/rum_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/rum_rule_identifier" } } } }, "type": "object" } ] }, "rum_rule-response-single": { "allOf": [ { "$ref": "#/components/schemas/rum_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/rum_rule" } }, "type": "object" } ] }, "rum_rule_identifier": { "description": "The Web Analytics rule identifier.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "x-auditable": true }, "rum_rules": { "description": "A list of rules.", "type": "array", "items": { "$ref": "#/components/schemas/rum_rule" } }, "rum_rules-response-collection": { "allOf": [ { "$ref": "#/components/schemas/rum_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "rules": { "$ref": "#/components/schemas/rum_rules" }, "ruleset": { "$ref": "#/components/schemas/rum_ruleset" } } } }, "type": "object" } ] }, "rum_ruleset": { "type": "object", "properties": { "enabled": { "description": "Whether the ruleset is enabled.", "type": "boolean", "example": true }, "id": { "$ref": "#/components/schemas/rum_ruleset_identifier" }, "zone_name": { "type": "string", "example": "example.com" }, "zone_tag": { "$ref": "#/components/schemas/rum_zone_tag" } } }, "rum_ruleset_identifier": { "description": "The Web Analytics ruleset identifier.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "x-auditable": true }, "rum_rum-site-response-single": { "allOf": [ { "$ref": "#/components/schemas/rum_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/rum_rum_site" } }, "type": "object" } ] }, "rum_rum_site": { "type": "object", "properties": { "editable": { "$ref": "#/components/schemas/rum_editable" }, "id": { "$ref": "#/components/schemas/rum_id" }, "value": { "$ref": "#/components/schemas/rum_value" } } }, "rum_site": { "type": "object", "properties": { "auto_install": { "$ref": "#/components/schemas/rum_auto_install" }, "created": { "$ref": "#/components/schemas/rum_timestamp" }, "rules": { "$ref": "#/components/schemas/rum_rules" }, "ruleset": { "$ref": "#/components/schemas/rum_ruleset" }, "site_tag": { "$ref": "#/components/schemas/rum_site_tag" }, "site_token": { "$ref": "#/components/schemas/rum_site_token" }, "snippet": { "$ref": "#/components/schemas/rum_snippet" } } }, "rum_site-response-single": { "allOf": [ { "$ref": "#/components/schemas/rum_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/rum_site" } }, "type": "object" } ] }, "rum_site-tag-list-response": { "allOf": [ { "$ref": "#/components/schemas/rum_api-response-common" }, { "properties": { "result": { "description": "List of Web Analytics site tag identifiers.", "type": "array", "items": { "$ref": "#/components/schemas/rum_site_tag" } } }, "type": "object" } ] }, "rum_site-tag-response-single": { "allOf": [ { "$ref": "#/components/schemas/rum_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "site_tag": { "$ref": "#/components/schemas/rum_site_tag" } } } }, "type": "object" } ] }, "rum_site_tag": { "description": "The Web Analytics site identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "x-auditable": true }, "rum_site_token": { "description": "The Web Analytics site token.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "x-auditable": true }, "rum_sites-response-collection": { "allOf": [ { "$ref": "#/components/schemas/rum_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/rum_site" } }, "result_info": { "$ref": "#/components/schemas/rum_result_info" } }, "type": "object" } ] }, "rum_snippet": { "description": "Encoded JavaScript snippet.", "type": "string", "example": "", "x-auditable": true }, "rum_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true, "x-auditable": true }, "rum_toggle-rum-request": { "type": "object", "properties": { "value": { "description": "Value can either be On or Off.", "type": "string", "example": "on" } } }, "rum_update-site-request": { "type": "object", "properties": { "auto_install": { "$ref": "#/components/schemas/rum_auto_install" }, "enabled": { "$ref": "#/components/schemas/rum_enabled" }, "host": { "$ref": "#/components/schemas/rum_host" }, "lite": { "$ref": "#/components/schemas/rum_lite" }, "zone_tag": { "$ref": "#/components/schemas/rum_zone_tag" } } }, "rum_value": { "description": "Current state of RUM. Returns On, Off, or Manual.", "type": "string", "example": "on", "x-auditable": true }, "rum_zone-tag-list-response": { "allOf": [ { "$ref": "#/components/schemas/rum_api-response-common" }, { "properties": { "result": { "description": "List of zone tag identifiers associated with Web Analytics sites.", "type": "array", "items": { "$ref": "#/components/schemas/rum_zone_tag" } } }, "type": "object" } ] }, "rum_zone_tag": { "description": "The zone identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "x-auditable": true }, "secondary-dns_account_identifier": { "type": "string", "example": "01a7362d577a6c3019a474fd6f485823", "readOnly": true, "x-auditable": true }, "secondary-dns_acl": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/secondary-dns_identifier-3" }, "ip_range": { "$ref": "#/components/schemas/secondary-dns_ip_range" }, "name": { "$ref": "#/components/schemas/secondary-dns_name-4" } }, "required": [ "id", "name", "ip_range" ] }, "secondary-dns_algo": { "description": "TSIG algorithm.", "type": "string", "example": "hmac-sha512.", "x-auditable": true }, "secondary-dns_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "secondary-dns_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/secondary-dns_messages" }, "messages": { "$ref": "#/components/schemas/secondary-dns_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "secondary-dns_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/secondary-dns_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/secondary-dns_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "secondary-dns_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-common" } ] }, "secondary-dns_auto_refresh_seconds": { "description": "How often should a secondary zone auto refresh regardless of DNS NOTIFY.\nNot applicable for primary zones.", "type": "number", "example": 86400, "default": 86400, "minimum": 300, "x-auditable": true }, "secondary-dns_disable_transfer_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/secondary-dns_disable_transfer_result" } }, "type": "object" } ] }, "secondary-dns_disable_transfer_result": { "description": "The zone transfer status of a primary zone.", "type": "string", "example": "Disabled", "x-auditable": true }, "secondary-dns_dns-secondary-secondary-zone": { "type": "object", "properties": { "auto_refresh_seconds": { "$ref": "#/components/schemas/secondary-dns_auto_refresh_seconds" }, "id": { "$ref": "#/components/schemas/secondary-dns_identifier" }, "name": { "$ref": "#/components/schemas/secondary-dns_name" }, "peers": { "$ref": "#/components/schemas/secondary-dns_peers" } }, "required": [ "id", "name", "peers", "auto_refresh_seconds" ] }, "secondary-dns_enable_transfer_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/secondary-dns_enable_transfer_result" } }, "type": "object" } ] }, "secondary-dns_enable_transfer_result": { "description": "The zone transfer status of a primary zone.", "type": "string", "example": "Enabled", "x-auditable": true }, "secondary-dns_force_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/secondary-dns_force_result" } }, "type": "object" } ] }, "secondary-dns_force_response-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/secondary-dns_force_result-2" } }, "type": "object" } ] }, "secondary-dns_force_result": { "description": "When force_axfr query parameter is set to true, the response is a simple string.", "type": "string", "example": "OK", "x-auditable": true }, "secondary-dns_force_result-2": { "description": "When force_notify query parameter is set to true, the response is a simple string.", "type": "string", "example": "OK", "x-auditable": true }, "secondary-dns_id_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/secondary-dns_identifier" } } } }, "type": "object" } ] }, "secondary-dns_id_response-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/secondary-dns_identifier-2" } } } }, "type": "object" } ] }, "secondary-dns_id_response-3": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/secondary-dns_identifier-3" } } } }, "type": "object" } ] }, "secondary-dns_identifier": { "type": "string", "example": "269d8f4853475ca241c4e730be286b20", "readOnly": true, "x-auditable": true }, "secondary-dns_identifier-2": { "type": "string", "example": "69cd1e104af3e6ed3cb344f263fd0d5a", "readOnly": true, "x-auditable": true }, "secondary-dns_identifier-3": { "type": "string", "example": "23ff594956f20c2a721606e94745a8aa", "readOnly": true, "x-auditable": true }, "secondary-dns_ip": { "description": "IPv4/IPv6 address of primary or secondary nameserver, depending on what zone this peer is linked to. For primary zones this IP defines the IP of the secondary nameserver Cloudflare will NOTIFY upon zone changes. For secondary zones this IP defines the IP of the primary nameserver Cloudflare will send AXFR/IXFR requests to.", "type": "string", "example": "192.0.2.53", "x-auditable": true }, "secondary-dns_ip_range": { "description": "Allowed IPv4/IPv6 address range of primary or secondary nameservers. This will be applied for the entire account. The IP range is used to allow additional NOTIFY IPs for secondary zones and IPs Cloudflare allows AXFR/IXFR requests from for primary zones. CIDRs are limited to a maximum of /24 for IPv4 and /64 for IPv6 respectively.", "type": "string", "example": "192.0.2.53/28", "x-auditable": true }, "secondary-dns_ixfr_enable": { "description": "Enable IXFR transfer protocol, default is AXFR. Only applicable to secondary zones.", "type": "boolean", "example": false, "x-auditable": true }, "secondary-dns_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "secondary-dns_name": { "description": "Zone name.", "type": "string", "example": "www.example.com.", "x-auditable": true }, "secondary-dns_name-2": { "description": "TSIG key name.", "type": "string", "example": "tsig.customer.cf.", "x-auditable": true }, "secondary-dns_name-3": { "description": "The name of the peer.", "type": "string", "example": "my-peer-1", "x-auditable": true }, "secondary-dns_name-4": { "description": "The name of the acl.", "type": "string", "example": "my-acl-1", "x-auditable": true }, "secondary-dns_peer": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/secondary-dns_identifier-3" }, "ip": { "$ref": "#/components/schemas/secondary-dns_ip" }, "ixfr_enable": { "$ref": "#/components/schemas/secondary-dns_ixfr_enable" }, "name": { "$ref": "#/components/schemas/secondary-dns_name-3" }, "port": { "$ref": "#/components/schemas/secondary-dns_port" }, "tsig_id": { "$ref": "#/components/schemas/secondary-dns_tsig_id" } }, "required": [ "id", "name" ] }, "secondary-dns_peers": { "description": "A list of peer tags.", "type": "array", "items": { "$ref": "#/components/schemas/secondary-dns_identifier" }, "example": [ "23ff594956f20c2a721606e94745a8aa", "00920f38ce07c2e2f4df50b1f61d4194" ], "x-stainless-collection-type": "set" }, "secondary-dns_port": { "description": "DNS port of primary or secondary nameserver, depending on what zone this peer is linked to.", "type": "number", "example": 53, "x-auditable": true }, "secondary-dns_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/secondary-dns_tsig" } } }, "type": "object" } ] }, "secondary-dns_response_collection-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/secondary-dns_peer" } } }, "type": "object" } ] }, "secondary-dns_response_collection-3": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/secondary-dns_acl" } } }, "type": "object" } ] }, "secondary-dns_secret": { "description": "TSIG secret.", "type": "string", "example": "caf79a7804b04337c9c66ccd7bef9190a1e1679b5dd03d8aa10f7ad45e1a9dab92b417896c15d4d007c7c14194538d2a5d0feffdecc5a7f0e1c570cfa700837c", "x-sensitive": true }, "secondary-dns_single_request_outgoing": { "properties": { "id": { "$ref": "#/components/schemas/secondary-dns_identifier" }, "name": { "$ref": "#/components/schemas/secondary-dns_name" }, "peers": { "$ref": "#/components/schemas/secondary-dns_peers" } }, "required": [ "id", "name", "peers" ] }, "secondary-dns_single_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/secondary-dns_tsig" } }, "type": "object" } ] }, "secondary-dns_single_response-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/secondary-dns_peer" } }, "type": "object" } ] }, "secondary-dns_single_response-3": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/secondary-dns_acl" } }, "type": "object" } ] }, "secondary-dns_single_response_incoming": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "auto_refresh_seconds": { "$ref": "#/components/schemas/secondary-dns_auto_refresh_seconds" }, "checked_time": { "$ref": "#/components/schemas/secondary-dns_time" }, "created_time": { "$ref": "#/components/schemas/secondary-dns_time" }, "id": { "$ref": "#/components/schemas/secondary-dns_identifier" }, "modified_time": { "$ref": "#/components/schemas/secondary-dns_time" }, "name": { "$ref": "#/components/schemas/secondary-dns_name" }, "peers": { "$ref": "#/components/schemas/secondary-dns_peers" }, "soa_serial": { "$ref": "#/components/schemas/secondary-dns_soa_serial" } } } }, "type": "object" } ] }, "secondary-dns_single_response_outgoing": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secondary-dns_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "checked_time": { "$ref": "#/components/schemas/secondary-dns_time" }, "created_time": { "$ref": "#/components/schemas/secondary-dns_time" }, "id": { "$ref": "#/components/schemas/secondary-dns_identifier" }, "last_transferred_time": { "$ref": "#/components/schemas/secondary-dns_time" }, "name": { "$ref": "#/components/schemas/secondary-dns_name" }, "peers": { "$ref": "#/components/schemas/secondary-dns_peers" }, "soa_serial": { "$ref": "#/components/schemas/secondary-dns_soa_serial" } } } }, "type": "object" } ] }, "secondary-dns_soa_serial": { "description": "The serial number of the SOA for the given zone.", "type": "number", "example": 2019102400, "x-auditable": true }, "secondary-dns_time": { "description": "The time for a specific event.", "type": "string", "example": "2019-10-24T17:09:42.883908+01:00", "x-auditable": true }, "secondary-dns_tsig": { "type": "object", "properties": { "algo": { "$ref": "#/components/schemas/secondary-dns_algo" }, "id": { "$ref": "#/components/schemas/secondary-dns_identifier-2" }, "name": { "$ref": "#/components/schemas/secondary-dns_name-2" }, "secret": { "$ref": "#/components/schemas/secondary-dns_secret" } }, "required": [ "id", "name", "secret", "algo" ] }, "secondary-dns_tsig_id": { "description": "TSIG authentication will be used for zone transfer if configured.", "type": "string", "example": "69cd1e104af3e6ed3cb344f263fd0d5a", "x-auditable": true }, "secrets-store_SecretStatus": { "type": "string", "enum": [ "pending", "active", "deleted" ], "x-auditable": true }, "secrets-store_account_identifier": { "description": "Account Identifier.", "type": "string", "example": "985e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "secrets-store_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secrets-store_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "secrets-store_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/secrets-store_messages" }, "messages": { "$ref": "#/components/schemas/secrets-store_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "secrets-store_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/secrets-store_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/secrets-store_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "secrets-store_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/secrets-store_api-response-common" } ] }, "secrets-store_comment": { "description": "Freeform text describing the secret.", "type": "string", "example": "info about my secret", "x-auditable": true }, "secrets-store_createSecretObject": { "properties": { "comment": { "$ref": "#/components/schemas/secrets-store_comment" }, "name": { "$ref": "#/components/schemas/secrets-store_secret_name" }, "scopes": { "$ref": "#/components/schemas/secrets-store_scopes" }, "value": { "$ref": "#/components/schemas/secrets-store_value" } }, "required": [ "name", "value", "scopes" ] }, "secrets-store_createStoreObject": { "properties": { "name": { "$ref": "#/components/schemas/secrets-store_store_name" } }, "required": [ "name" ] }, "secrets-store_created": { "description": "When the secret was created.", "type": "string", "format": "date-time", "example": "2023-09-21T18:56:32.624632Z", "readOnly": true, "x-auditable": true }, "secrets-store_deleteSecretsRequest": { "description": "Request body for bulk deleting secrets.", "type": "object", "properties": { "ids": { "description": "List of secret identifier tags to delete.", "type": "array", "items": { "$ref": "#/components/schemas/secrets-store_identifier" }, "example": [ "3fd85f74b32742f1bff64a85009dda07" ] } }, "required": [ "ids" ] }, "secrets-store_delete_response": { "allOf": [ { "$ref": "#/components/schemas/secrets-store_api-response-single" }, { "properties": { "result": { "description": "Result is null for delete operations.", "type": "object", "nullable": true } }, "type": "object" } ] }, "secrets-store_duplicateSecretObject": { "properties": { "comment": { "$ref": "#/components/schemas/secrets-store_comment" }, "name": { "$ref": "#/components/schemas/secrets-store_secret_name" }, "scopes": { "$ref": "#/components/schemas/secrets-store_scopes" } }, "required": [ "name", "scopes" ] }, "secrets-store_identifier": { "description": "Secret identifier tag.", "type": "string", "example": "3fd85f74b32742f1bff64a85009dda07", "maxLength": 32, "readOnly": true, "x-auditable": true }, "secrets-store_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "secrets-store_modified": { "description": "When the secret was modified.", "type": "string", "format": "date-time", "example": "2023-09-21T18:56:32.624632Z", "readOnly": true, "x-auditable": true }, "secrets-store_patchSecretObject": { "properties": { "comment": { "$ref": "#/components/schemas/secrets-store_comment" }, "scopes": { "$ref": "#/components/schemas/secrets-store_scopes" }, "value": { "$ref": "#/components/schemas/secrets-store_value" } } }, "secrets-store_quota": { "description": "The number of secrets the account is entitled to use.", "type": "number", "example": 10, "x-auditable": true }, "secrets-store_quota_response": { "allOf": [ { "$ref": "#/components/schemas/secrets-store_api-response-collection" }, { "properties": { "result": { "$ref": "#/components/schemas/secrets-store_secretsUsageObject" } } } ] }, "secrets-store_scopes": { "description": "The list of services that can use this secret.", "type": "array", "items": { "enum": [ "workers", "ai_gateway", "dex", "access", "containers", "websearch" ], "type": "string" }, "example": [ "workers", "ai_gateway", "dex", "access", "websearch" ] }, "secrets-store_secretObject": { "properties": { "comment": { "$ref": "#/components/schemas/secrets-store_comment" }, "created": { "$ref": "#/components/schemas/secrets-store_created" }, "id": { "$ref": "#/components/schemas/secrets-store_identifier" }, "modified": { "$ref": "#/components/schemas/secrets-store_modified" }, "name": { "$ref": "#/components/schemas/secrets-store_secret_name" }, "scopes": { "$ref": "#/components/schemas/secrets-store_scopes" }, "status": { "$ref": "#/components/schemas/secrets-store_SecretStatus" }, "store_id": { "$ref": "#/components/schemas/secrets-store_store_identifier" } }, "required": [ "id", "name", "store_id", "created", "modified", "status" ] }, "secrets-store_secret_name": { "description": "The name of the secret.", "type": "string", "example": "MY_API_KEY" }, "secrets-store_secret_response": { "allOf": [ { "$ref": "#/components/schemas/secrets-store_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/secrets-store_secretObject" } } } ] }, "secrets-store_secretsUsageObject": { "properties": { "secrets": { "$ref": "#/components/schemas/secrets-store_usageQuotaObject" } }, "required": [ "secrets" ] }, "secrets-store_secrets_response_collection": { "allOf": [ { "$ref": "#/components/schemas/secrets-store_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/secrets-store_secretObject" } } } } ] }, "secrets-store_storeObject": { "properties": { "account_id": { "$ref": "#/components/schemas/secrets-store_account_identifier" }, "created": { "$ref": "#/components/schemas/secrets-store_created" }, "id": { "$ref": "#/components/schemas/secrets-store_store_identifier" }, "modified": { "$ref": "#/components/schemas/secrets-store_modified" }, "name": { "$ref": "#/components/schemas/secrets-store_store_name" } }, "required": [ "id", "name", "created", "modified" ] }, "secrets-store_store_identifier": { "description": "Store Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "secrets-store_store_name": { "description": "The name of the store.", "type": "string", "example": "service_x_keys" }, "secrets-store_store_response": { "allOf": [ { "$ref": "#/components/schemas/secrets-store_api-response-collection" }, { "properties": { "result": { "$ref": "#/components/schemas/secrets-store_storeObject" } }, "type": "object" } ] }, "secrets-store_stores_response_collection": { "allOf": [ { "$ref": "#/components/schemas/secrets-store_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/secrets-store_storeObject" } } }, "type": "object" } ] }, "secrets-store_usage": { "description": "The number of secrets the account is currently using.", "type": "number", "example": 10, "x-auditable": true }, "secrets-store_usageQuotaObject": { "properties": { "quota": { "$ref": "#/components/schemas/secrets-store_quota" }, "usage": { "$ref": "#/components/schemas/secrets-store_usage" } }, "required": [ "usage", "quota" ] }, "secrets-store_value": { "description": "The value of the secret. Maximum 64 KiB (65,536 bytes). Note that this is 'write only' - the API never returns this value; it exists only to create or modify secrets.", "type": "string", "example": "api-token-secret-123", "maxLength": 65536, "writeOnly": true, "x-sensitive": true }, "security-center_ExternalApiResponseCommon": { "$ref": "#/components/schemas/security-center_api-response-common" }, "security-center_ExternalApiResponseCommonFailure": { "$ref": "#/components/schemas/security-center_api-response-common-failure" }, "security-center_ExternalApiResponseSingle": { "$ref": "#/components/schemas/security-center_api-response-single" }, "security-center_accountId": { "$ref": "#/components/schemas/security-center_identifier" }, "security-center_accountStateResponse": { "type": "object", "properties": { "recent_dormant_reactivation": { "description": "Whether the account was recently reactivated from a dormant state (used to show the reactivation banner).", "type": "boolean", "example": false }, "scans_enabled": { "description": "Whether on-demand and scheduled scans are enabled for the account.", "type": "boolean", "example": true } }, "required": [ "scans_enabled", "recent_dormant_reactivation" ] }, "security-center_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/security-center_messages" }, "messages": { "$ref": "#/components/schemas/security-center_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "security-center_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/security-center_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/security-center_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "security-center_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/security-center_api-response-common" } ] }, "security-center_auditLog": { "type": "object", "properties": { "changed_at": { "description": "The timestamp when the change occurred.", "type": "string", "format": "date-time", "x-auditable": true }, "changed_by": { "description": "The actor that made the change. 'system' for automated changes, or a user identifier.", "type": "string", "example": "system", "x-auditable": true }, "current_value": { "description": "The value of the field after the change. Null if the field was cleared.", "type": "string", "nullable": true, "x-auditable": true }, "field_changed": { "description": "The field that was changed.", "type": "string", "enum": [ "status", "user_classification" ], "x-auditable": true }, "id": { "description": "UUIDv7 identifier for the audit log entry, time-ordered.", "type": "string", "format": "uuid", "example": "019b0000-0000-7000-8000-000000000001", "x-auditable": true }, "issue_id": { "description": "The ID of the insight this audit log entry relates to.", "type": "string", "x-auditable": true }, "previous_value": { "description": "The value of the field before the change. Null if the field was not previously set.", "type": "string", "nullable": true, "x-auditable": true }, "rationale": { "description": "Optional rationale provided for the change.", "type": "string", "nullable": true, "x-auditable": true }, "zone_id": { "description": "The zone ID associated with the insight. Only present for zone-level insights.", "type": "integer", "format": "int64", "x-auditable": true } } }, "security-center_auditLogResponse": { "allOf": [ { "$ref": "#/components/schemas/security-center_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/security-center_auditLog" } }, "result_info": { "type": "object", "properties": { "count": { "description": "The number of items in the current result set.", "type": "integer", "example": 25 }, "cursor": { "description": "Opaque cursor for the next page of results. Absent when there are no more results.", "type": "string" }, "per_page": { "description": "The requested number of items per page.", "type": "integer", "example": 25 } } } }, "type": "object" } ] }, "security-center_count": { "description": "Indicates the total number of results.", "type": "integer", "example": 1, "x-auditable": true }, "security-center_dismissed": { "type": "boolean", "example": false, "x-auditable": true }, "security-center_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "security-center_issue": { "type": "object", "properties": { "dismissed": { "type": "boolean", "example": false, "x-auditable": true }, "has_extended_context": { "description": "Indicates whether the insight has a large payload that requires fetching via the context endpoint.", "type": "boolean", "example": false, "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "issue_class": { "$ref": "#/components/schemas/security-center_issueClass" }, "issue_type": { "$ref": "#/components/schemas/security-center_issueType" }, "payload": { "type": "object", "properties": { "detection_method": { "description": "Describes the method used to detect insight.", "type": "string", "example": "We detected security rules referencing multiple IP addresses directly in the rules.", "x-auditable": true }, "zone_tag": { "type": "string", "x-auditable": true } } }, "resolve_link": { "type": "string", "x-auditable": true }, "resolve_text": { "type": "string", "x-auditable": true }, "severity": { "type": "string", "enum": [ "Low", "Moderate", "Critical" ], "x-auditable": true }, "since": { "type": "string", "format": "date-time", "x-auditable": true }, "status": { "description": "The current status of the insight.", "type": "string", "example": "active", "enum": [ "active", "resolved" ], "x-auditable": true }, "subject": { "$ref": "#/components/schemas/security-center_subject" }, "timestamp": { "type": "string", "format": "date-time", "x-auditable": true }, "user_classification": { "$ref": "#/components/schemas/security-center_userClassification" } } }, "security-center_issueClass": { "type": "string", "example": "always_use_https_not_enabled", "x-auditable": true }, "security-center_issueClasses": { "type": "array", "items": { "$ref": "#/components/schemas/security-center_issueClass" }, "example": [ "a_record_dangling", "always_use_https_not_enabled" ] }, "security-center_issueType": { "type": "string", "enum": [ "compliance_violation", "email_security", "exposed_infrastructure", "insecure_configuration", "weak_authentication", "configuration_suggestion" ], "x-auditable": true }, "security-center_issueTypes": { "type": "array", "items": { "$ref": "#/components/schemas/security-center_issueType" }, "example": [ "compliance_violation", "email_security" ] }, "security-center_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "security-center_newScanRequest": { "description": "Request body for starting an on-demand scan. Specify issue_type or issue_class to scope the scan, or provide an empty object to scan all issue types.", "oneOf": [ { "properties": { "issue_type": { "$ref": "#/components/schemas/security-center_issueType" } }, "required": [ "issue_type" ], "type": "object" }, { "properties": { "issue_class": { "$ref": "#/components/schemas/security-center_issueClass" } }, "required": [ "issue_class" ], "type": "object" }, { "additionalProperties": false, "type": "object" } ] }, "security-center_newScanResponse": { "type": "object", "properties": { "scan_id": { "description": "An opaque identifier for the initiated scan.", "type": "string", "example": "d5e94e48-504f-4a7f-a8c4-e0dc2e05e5f2", "x-auditable": true } } }, "security-center_page": { "description": "Specifies the current page within paginated list of results.", "type": "integer", "example": 1 }, "security-center_partnerInsightCountResponse": { "allOf": [ { "$ref": "#/components/schemas/security-center_api-response-common" }, { "properties": { "result": { "anyOf": [ { "additionalProperties": false, "properties": { "count": { "type": "integer", "example": 1, "x-auditable": true } }, "required": [ "count" ], "type": "object" } ] } }, "type": "object" } ] }, "security-center_perPage": { "description": "Sets the number of results per page of results.", "type": "integer", "example": 25, "maximum": 1000, "minimum": 1 }, "security-center_products": { "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "access", "dns" ] }, "security-center_scanQuota": { "description": "Quota information for on-demand scans. Scans are rate limited per account per 24-hour rolling window.", "type": "object", "properties": { "available": { "description": "The number of on-demand scans remaining in the current 24-hour window.", "type": "integer", "example": 2 }, "used": { "description": "The number of on-demand scans initiated in the current 24-hour window.", "type": "integer", "example": 3 } }, "required": [ "used", "available" ] }, "security-center_scanStatusResponse": { "type": "object", "properties": { "scan_id": { "description": "An opaque identifier for the scan.", "type": "string", "example": "d5e94e48-504f-4a7f-a8c4-e0dc2e05e5f2" }, "started_at": { "description": "The time at which the scan was started, in RFC 3339 format.", "type": "string", "format": "date-time", "example": "2026-04-13T23:59:59Z" }, "status": { "description": "The current status of the scan.", "type": "string", "enum": [ "in_progress", "completed" ] } }, "required": [ "scan_id", "started_at", "status" ] }, "security-center_scansListResponse": { "type": "object", "properties": { "quota": { "$ref": "#/components/schemas/security-center_scanQuota" }, "scans": { "description": "List of on-demand scans.", "type": "array", "items": { "$ref": "#/components/schemas/security-center_scanStatusResponse" } } }, "required": [ "scans", "quota" ] }, "security-center_securityTxt": { "type": "object", "properties": { "acknowledgments": { "type": "array", "items": { "format": "uri", "type": "string", "x-auditable": true }, "example": [ "https://example.com/hall-of-fame.html" ] }, "canonical": { "type": "array", "items": { "format": "uri", "type": "string", "x-auditable": true }, "example": [ "https://www.example.com/.well-known/security.txt" ] }, "contact": { "type": "array", "items": { "format": "uri", "type": "string", "x-auditable": true }, "example": [ "mailto:security@example.com", "tel:+1-201-555-0123", "https://example.com/security-contact.html" ] }, "enabled": { "type": "boolean", "example": true, "x-auditable": true }, "encryption": { "type": "array", "items": { "format": "uri", "type": "string" }, "example": [ "https://example.com/pgp-key.txt", "dns:5d2d37ab76d47d36._openpgpkey.example.com?type=OPENPGPKEY", "openpgp4fpr:5f2de5521c63a801ab59ccb603d49de44b29100f" ] }, "expires": { "type": "string", "format": "date-time", "x-auditable": true }, "hiring": { "type": "array", "items": { "format": "uri", "type": "string", "x-auditable": true }, "example": [ "https://example.com/jobs.html" ] }, "policy": { "type": "array", "items": { "format": "uri", "type": "string", "x-auditable": true }, "example": [ "https://example.com/disclosure-policy.html" ] }, "preferred_languages": { "type": "string", "example": "en, es, fr", "x-auditable": true } } }, "security-center_severityQueryParam": { "type": "array", "items": { "enum": [ "low", "moderate", "critical" ], "type": "string", "x-auditable": true }, "example": [ "low", "moderate" ] }, "security-center_sources": { "type": "array", "items": { "enum": [ "cloudflare", "riskrecon" ], "type": "string", "x-auditable": true }, "example": [ "cloudflare" ] }, "security-center_subject": { "type": "string", "example": "example.com", "x-auditable": true }, "security-center_subjects": { "type": "array", "items": { "$ref": "#/components/schemas/security-center_subject" } }, "security-center_updateAccountStateRequest": { "type": "object", "properties": { "scans_enabled": { "description": "Enable or disable scans for the account.", "type": "boolean", "x-auditable": true } }, "required": [ "scans_enabled" ] }, "security-center_userClassification": { "description": "User-defined classification for the insight. Can be 'false_positive', 'accept_risk', 'other', or null.", "type": "string", "example": "false_positive", "enum": [ "false_positive", "accept_risk", "other", null ], "nullable": true, "x-auditable": true }, "security-center_userClassificationUpdate": { "type": "object", "properties": { "classification": { "$ref": "#/components/schemas/security-center_userClassification" }, "rationale": { "description": "Rationale for the classification change. Required when classification is 'accept_risk' or 'other'.", "type": "string", "x-auditable": true } } }, "security-center_valueCountsResponse": { "allOf": [ { "$ref": "#/components/schemas/security-center_api-response-common" }, { "properties": { "result": { "anyOf": [ { "items": { "properties": { "count": { "type": "integer", "example": 1, "x-auditable": true }, "value": { "type": "string", "x-auditable": true } }, "type": "object" }, "type": "array" } ] } }, "type": "object" } ] }, "security-center_zoneId": { "$ref": "#/components/schemas/security-center_identifier" }, "smartshield_address": { "description": "The hostname or IP address of the origin server to run health checks on.", "type": "string", "example": "www.example.com", "x-auditable": true }, "smartshield_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/smartshield_api-response-common" }, { "properties": { "result": { "type": "array", "items": {}, "nullable": true }, "result_info": { "$ref": "#/components/schemas/smartshield_result_info" } } } ] }, "smartshield_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/smartshield_messages" }, "messages": { "$ref": "#/components/schemas/smartshield_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": {}, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "smartshield_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/smartshield_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/smartshield_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "smartshield_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/smartshield_api-response-common" }, { "properties": { "result": { "oneOf": [ { "type": "object" }, { "type": "string" } ] } }, "type": "object" } ] }, "smartshield_base": { "type": "object", "properties": { "id": { "description": "Identifier of the zone setting.", "type": "string", "x-auditable": true }, "modified_on": { "description": "Last time this setting was modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "nullable": true, "readOnly": true, "x-auditable": true } }, "required": [ "id" ] }, "smartshield_cache_reserve_clear": { "description": "You can use Cache Reserve Clear to clear your Cache Reserve, but you must first disable Cache Reserve. In most cases, this will be accomplished within 24 hours. You cannot re-enable Cache Reserve while this process is ongoing. Keep in mind that you cannot undo or cancel this operation.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/smartshield_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "cache_reserve_clear", "enum": [ "cache_reserve_clear" ], "x-auditable": true } }, "type": "object" } ], "title": "Cache Reserve Clear" }, "smartshield_cache_reserve_clear_end_ts": { "description": "The time that the latest Cache Reserve Clear operation completed.", "type": "string", "format": "date-time", "example": "2023-10-02T12:00:00.12345Z", "x-auditable": true }, "smartshield_cache_reserve_clear_response_value": { "type": "object", "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/smartshield_cache_reserve_clear" }, { "properties": { "end_ts": { "$ref": "#/components/schemas/smartshield_cache_reserve_clear_end_ts" }, "start_ts": { "$ref": "#/components/schemas/smartshield_cache_reserve_clear_start_ts" }, "state": { "$ref": "#/components/schemas/smartshield_cache_reserve_clear_state" } }, "required": [ "state", "start_ts" ], "type": "object" } ] } } }, "smartshield_cache_reserve_clear_start_ts": { "description": "The time that the latest Cache Reserve Clear operation started.", "type": "string", "format": "date-time", "example": "2023-10-02T10:00:00.12345Z", "x-auditable": true }, "smartshield_cache_reserve_clear_state": { "description": "The current state of the Cache Reserve Clear operation.", "type": "string", "example": "In-progress", "enum": [ "In-progress", "Completed" ], "x-auditable": true }, "smartshield_check_regions": { "description": "A list of regions from which to run health checks. Null means Cloudflare will pick a default region.", "type": "array", "items": { "description": "WNAM: Western North America, ENAM: Eastern North America, WEU: Western Europe, EEU: Eastern Europe, NSAM: Northern South America, SSAM: Southern South America, OC: Oceania, ME: Middle East, NAF: North Africa, SAF: South Africa, IN: India, SEAS: South East Asia, NEAS: North East Asia, ALL_REGIONS: all regions (BUSINESS and ENTERPRISE customers only).", "enum": [ "WNAM", "ENAM", "WEU", "EEU", "NSAM", "SSAM", "OC", "ME", "NAF", "SAF", "IN", "SEAS", "NEAS", "ALL_REGIONS" ], "type": "string" }, "example": [ "WEU", "ENAM" ], "nullable": true, "x-auditable": true }, "smartshield_consecutive_fails": { "description": "The number of consecutive fails required from a health check before changing the health to unhealthy.", "type": "integer", "default": 1, "x-auditable": true }, "smartshield_consecutive_successes": { "description": "The number of consecutive successes required from a health check before changing the health to healthy.", "type": "integer", "default": 1, "x-auditable": true }, "smartshield_description": { "description": "A human-readable description of the health check.", "type": "string", "example": "Health check for www.example.com", "x-auditable": true }, "smartshield_failure_reason": { "description": "The current failure reason if status is unhealthy.", "type": "string", "example": "", "readOnly": true, "x-auditable": true }, "smartshield_healthchecks": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/smartshield_address" }, "check_regions": { "$ref": "#/components/schemas/smartshield_check_regions" }, "consecutive_fails": { "$ref": "#/components/schemas/smartshield_consecutive_fails" }, "consecutive_successes": { "$ref": "#/components/schemas/smartshield_consecutive_successes" }, "created_on": { "$ref": "#/components/schemas/smartshield_timestamp" }, "description": { "$ref": "#/components/schemas/smartshield_description" }, "failure_reason": { "$ref": "#/components/schemas/smartshield_failure_reason" }, "http_config": { "$ref": "#/components/schemas/smartshield_http_config" }, "id": { "$ref": "#/components/schemas/smartshield_identifier" }, "interval": { "$ref": "#/components/schemas/smartshield_interval" }, "modified_on": { "$ref": "#/components/schemas/smartshield_timestamp" }, "name": { "$ref": "#/components/schemas/smartshield_name" }, "retries": { "$ref": "#/components/schemas/smartshield_retries" }, "status": { "$ref": "#/components/schemas/smartshield_status" }, "suspended": { "$ref": "#/components/schemas/smartshield_suspended" }, "tcp_config": { "$ref": "#/components/schemas/smartshield_tcp_config" }, "timeout": { "$ref": "#/components/schemas/smartshield_timeout" }, "type": { "$ref": "#/components/schemas/smartshield_type" } } }, "smartshield_http_config": { "description": "Parameters specific to an HTTP or HTTPS health check.", "type": "object", "properties": { "allow_insecure": { "description": "Do not validate the certificate when the health check uses HTTPS.", "type": "boolean", "default": false, "x-auditable": true }, "expected_body": { "description": "A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy.", "type": "string", "example": "success", "x-auditable": true }, "expected_codes": { "description": "The expected HTTP response codes (e.g. \"200\") or code ranges (e.g. \"2xx\" for all codes starting with 2) of the health check.", "type": "array", "items": { "type": "string" }, "example": [ "2xx", "302" ], "default": "200", "nullable": true, "x-auditable": true }, "follow_redirects": { "description": "Follow redirects if the origin returns a 3xx status code.", "type": "boolean", "default": false, "x-auditable": true }, "header": { "description": "The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden.", "type": "object", "example": { "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] }, "additionalProperties": { "items": { "type": "string", "x-auditable": true }, "type": "array" }, "nullable": true }, "method": { "description": "The HTTP method to use for the health check.", "type": "string", "default": "GET", "enum": [ "GET", "HEAD" ], "x-auditable": true }, "path": { "description": "The endpoint path to health check against.", "type": "string", "example": "/health", "default": "/", "x-auditable": true }, "port": { "description": "Port number to connect to for the health check. Defaults to 80 if type is HTTP or 443 if type is HTTPS.", "type": "integer", "default": 80, "x-auditable": true } }, "nullable": true }, "smartshield_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "smartshield_interval": { "description": "The interval between each health check. Shorter intervals may give quicker notifications if the origin status changes, but will increase load on the origin as we check from multiple locations.", "type": "integer", "default": 60, "x-auditable": true }, "smartshield_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "smartshield_name": { "description": "A short name to identify the health check. Only alphanumeric characters, hyphens and underscores are allowed.", "type": "string", "example": "server-1", "x-auditable": true }, "smartshield_query_healthcheck": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/smartshield_address" }, "check_regions": { "$ref": "#/components/schemas/smartshield_check_regions" }, "consecutive_fails": { "$ref": "#/components/schemas/smartshield_consecutive_fails" }, "consecutive_successes": { "$ref": "#/components/schemas/smartshield_consecutive_successes" }, "description": { "$ref": "#/components/schemas/smartshield_description" }, "http_config": { "$ref": "#/components/schemas/smartshield_http_config" }, "interval": { "$ref": "#/components/schemas/smartshield_interval" }, "name": { "$ref": "#/components/schemas/smartshield_name" }, "retries": { "$ref": "#/components/schemas/smartshield_retries" }, "suspended": { "$ref": "#/components/schemas/smartshield_suspended" }, "tcp_config": { "$ref": "#/components/schemas/smartshield_tcp_config" }, "timeout": { "$ref": "#/components/schemas/smartshield_timeout" }, "type": { "$ref": "#/components/schemas/smartshield_type" } }, "required": [ "name", "address" ] }, "smartshield_response_collection": { "allOf": [ { "$ref": "#/components/schemas/smartshield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/smartshield_healthchecks" } } } } ] }, "smartshield_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters", "type": "number", "example": 2000 } } }, "smartshield_retries": { "description": "The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately.", "type": "integer", "default": 2, "x-auditable": true }, "smartshield_single_hc_id_response": { "allOf": [ { "$ref": "#/components/schemas/smartshield_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/smartshield_identifier" } } } }, "type": "object" } ] }, "smartshield_single_hc_response": { "allOf": [ { "$ref": "#/components/schemas/smartshield_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/smartshield_healthchecks" } }, "type": "object" } ] }, "smartshield_single_smart_shield_get_response": { "allOf": [ { "$ref": "#/components/schemas/smartshield_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/smartshield_smart_shield_settings_get_response" } }, "type": "object" } ] }, "smartshield_single_smart_shield_patch_response": { "allOf": [ { "$ref": "#/components/schemas/smartshield_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/smartshield_smart_shield_settings_patch_response" } }, "type": "object" } ] }, "smartshield_smart_shield_settings": { "description": "A consolidated object containing settings from multiple APIs for partial updates.", "type": "object", "properties": { "cache_reserve": { "properties": { "editable": { "description": "Whether the setting is editable.", "type": "boolean", "example": true }, "id": { "description": "The id of the Cache Reserve setting.", "type": "string", "example": "cache_reserve" }, "value": { "description": "Specifies the enablement value of Cache Reserve.", "type": "string", "example": "off", "enum": [ "on", "off" ] } } }, "regional_tiered_cache": { "type": "object", "properties": { "editable": { "description": "Whether the setting is editable.", "type": "boolean", "example": true }, "id": { "description": "The id of the Regional Tiered Cache setting.", "type": "string", "example": "regional_tiered_cache" }, "value": { "description": "Specifies the enablement value of Cache Reserve.", "type": "string", "example": "off", "enum": [ "on", "off" ] } } }, "smart_routing": { "type": "object", "properties": { "editable": { "description": "Whether the setting is editable.", "type": "boolean", "example": true }, "id": { "description": "The id of the Smart Routing setting.", "type": "string", "example": "smart_routing" }, "value": { "description": "Specifies the enablement value of Argo Smart Routing.", "type": "string", "example": "off", "enum": [ "on", "off" ] } } }, "smart_tiered_cache": { "type": "object", "properties": { "editable": { "description": "Whether the setting is editable.", "type": "boolean", "example": true }, "id": { "description": "The id of the Smart Tiered Cache setting.", "type": "string", "example": "smart_tiered_cache" }, "modified_on": { "description": "The last time the setting was modified.", "type": "string", "example": "2025-09-10T22:53:22.946098Z" }, "value": { "description": "Specifies the enablement value of Tiered Cache.", "type": "string", "example": "on", "enum": [ "on", "off" ] } } } } }, "smartshield_smart_shield_settings_get_response": { "description": "The full Smart Shield response from the GET and PATCH operations.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/smartshield_smart_shield_settings" }, { "properties": { "healthchecks_count": { "description": "The total number of health checks associated with the zone.", "type": "integer", "example": 5 } }, "type": "object" } ], "required": [ "smart_tiered_cache", "smart_routing", "regional_tiered_cache", "cache_reserve", "healthchecks_count" ] }, "smartshield_smart_shield_settings_patch_body": { "description": "The patch body for Smart Shield.", "type": "object", "properties": { "cache_reserve": { "type": "object", "properties": { "value": { "description": "Specifies the enablement value of Cache Reserve.", "type": "string", "example": "on", "enum": [ "on", "off" ] } } }, "regional_tiered_cache": { "type": "object", "properties": { "value": { "description": "Specifies the enablement value of Regional Tiered Cache.", "type": "string", "example": "on", "enum": [ "on", "off" ] } } }, "smart_routing": { "type": "object", "properties": { "value": { "description": "Specifies the enablement value of Smart Routing.", "type": "string", "example": "on", "enum": [ "on", "off" ] } } }, "smart_tiered_cache": { "type": "object", "properties": { "value": { "description": "Specifies the enablement value of Smart Tiered Cache.", "type": "string", "example": "on", "enum": [ "on", "off" ] } } } }, "example": { "smart_tiered_cache": { "value": "on" } } }, "smartshield_smart_shield_settings_patch_response": { "description": "A consolidated object containing settings from multiple APIs for partial updates.", "type": "object", "properties": { "smart_tiered_cache": { "type": "object", "properties": { "editable": { "description": "Whether the setting is editable.", "type": "boolean", "example": true }, "id": { "description": "The id of the Smart Tiered Cache setting.", "type": "string", "example": "smart_tiered_cache" }, "modified_on": { "description": "The last time the setting was modified.", "type": "string", "example": "2025-09-10T22:53:22.946098Z" }, "value": { "description": "Specifies the enablement value of Tiered Cache.", "type": "string", "example": "on", "enum": [ "on", "off" ] } } } }, "required": [ "smart_tiered_cache", "smart_routing", "regional_tiered_cache", "cache_reserve" ] }, "smartshield_status": { "description": "The current status of the origin server according to the health check.", "type": "string", "example": "healthy", "enum": [ "unknown", "healthy", "unhealthy", "suspended" ], "readOnly": true, "x-auditable": true }, "smartshield_suspended": { "description": "If suspended, no health checks are sent to the origin.", "type": "boolean", "default": false, "x-auditable": true }, "smartshield_tcp_config": { "description": "Parameters specific to TCP health check.", "type": "object", "properties": { "method": { "description": "The TCP connection method to use for the health check.", "type": "string", "default": "connection_established", "enum": [ "connection_established" ], "x-auditable": true }, "port": { "description": "Port number to connect to for the health check. Defaults to 80.", "type": "integer", "default": 80, "x-auditable": true } }, "nullable": true }, "smartshield_timeout": { "description": "The timeout (in seconds) before marking the health check as failed.", "type": "integer", "default": 5, "x-auditable": true }, "smartshield_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true, "x-auditable": true }, "smartshield_type": { "description": "The protocol to use for the health check. Currently supported protocols are 'HTTP', 'HTTPS' and 'TCP'.", "type": "string", "example": "HTTPS", "default": "HTTP", "x-auditable": true }, "snippets_Errors": { "description": "Lists error messages.", "type": "array", "items": { "$ref": "#/components/schemas/snippets_Message" }, "title": "Errors" }, "snippets_Message": { "description": "Describes an API message.", "type": "object", "properties": { "code": { "description": "Identify the message code.", "type": "integer", "example": 10000, "title": "Code", "x-auditable": true }, "message": { "description": "Describes the message text.", "type": "string", "example": "something bad happened", "minLength": 1, "title": "Description", "x-auditable": true } }, "required": [ "message" ], "title": "Message" }, "snippets_Messages": { "description": "Contain warning messages.", "type": "array", "items": { "$ref": "#/components/schemas/snippets_Message" }, "title": "Messages" }, "snippets_Page": { "description": "Specifies the current page number.", "type": "integer", "example": 1, "default": 1, "minimum": 1, "title": "Page", "x-auditable": true }, "snippets_PerPage": { "description": "Specifies how many results to return per page.", "type": "integer", "example": 25, "default": 25, "minimum": 1, "title": "Per Page", "x-auditable": true }, "snippets_Response": { "description": "Return all API responses using this object.", "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/snippets_Errors" }, "messages": { "$ref": "#/components/schemas/snippets_Messages" }, "result": { "description": "Contain the response result.", "type": "object", "title": "Result" }, "success": { "description": "Indicate whether the API call was successful.", "type": "boolean", "title": "Success", "x-auditable": true } }, "required": [ "result", "success", "errors", "messages" ], "title": "Response" }, "snippets_ResultInfo": { "description": "Additional information to navigate the results.", "type": "object", "properties": { "count": { "description": "Specify the number of results in the current page.", "type": "integer", "example": 25, "minimum": 0, "title": "Count", "x-auditable": true }, "page": { "$ref": "#/components/schemas/snippets_Page" }, "per_page": { "$ref": "#/components/schemas/snippets_PerPage" }, "total_count": { "description": "Specify the total number of results.", "type": "integer", "example": 100, "minimum": 0, "title": "Total Count", "x-auditable": true }, "total_pages": { "description": "Specify the total number of pages.", "type": "integer", "example": 10, "minimum": 1, "title": "Total Pages", "x-auditable": true } }, "required": [ "page", "per_page", "total_pages", "count", "total_count" ], "title": "Result Info" }, "snippets_Snippet": { "description": "Define a snippet.", "type": "object", "properties": { "created_on": { "description": "Indicates when the snippet was created.", "type": "string", "format": "date-time", "example": "2000-01-01T00:00:00Z", "title": "Created On", "x-auditable": true }, "modified_on": { "description": "Indicates when the snippet was last modified.", "type": "string", "format": "date-time", "example": "2000-01-01T00:00:00Z", "title": "Modified On", "x-auditable": true }, "snippet_name": { "$ref": "#/components/schemas/snippets_SnippetName" } }, "required": [ "created_on", "modified_one", "snippet_name" ], "title": "Snippet" }, "snippets_SnippetFiles": { "description": "Contain files belonging to the snippet.", "type": "array", "items": { "description": "Specify a file belonging to the snippet.", "format": "binary", "title": "File", "type": "string", "x-auditable": true }, "minItems": 1, "title": "Files" }, "snippets_SnippetMainModule": { "description": "Specify the name of the file that contains the main module of the snippet.", "type": "string", "example": "main.js", "minLength": 1, "title": "Main Module", "x-auditable": true }, "snippets_SnippetName": { "description": "Identify the snippet.", "type": "string", "example": "my_snippet", "pattern": "^[A-Za-z0-9_]+$", "title": "Snippet Name", "x-auditable": true }, "snippets_SnippetRules": { "description": "Lists snippet rules.", "type": "array", "items": { "description": "Define a snippet rule.", "properties": { "description": { "description": "Provide an informative description of the rule.", "type": "string", "example": "Execute my_snippet when IP address is 1.1.1.1.", "default": "", "title": "Description", "x-auditable": true }, "enabled": { "description": "Indicate whether to execute the rule.", "type": "boolean", "example": true, "default": false, "title": "Enabled", "x-auditable": true }, "expression": { "description": "Define the expression that determines which traffic matches the rule.", "type": "string", "example": "ip.src eq 1.1.1.1", "minLength": 1, "title": "Expression", "x-auditable": true }, "id": { "description": "Specify the unique ID of the rule.", "type": "string", "example": "3a03d665bac047339bb530ecb439a90d", "pattern": "^[0-9a-f]{32}$", "readOnly": true, "title": "ID", "x-auditable": true }, "last_updated": { "description": "Specify the timestamp of when the rule was last modified.", "type": "string", "format": "date-time", "example": "2000-01-01T00:00:00Z", "readOnly": true, "title": "Last Updated", "x-auditable": true }, "snippet_name": { "$ref": "#/components/schemas/snippets_SnippetName" } }, "required": [ "id", "expression", "snippet_name", "last_updated" ], "title": "Snippet Rule", "type": "object" }, "title": "Snippet Rules" }, "snippets_ZoneId": { "description": "Use this field to specify the unique ID of the zone.", "type": "string", "example": "9f1839b6152d298aca64c4e906b6d074", "pattern": "^[0-9a-f]{32}$", "title": "Zone ID", "x-auditable": true }, "spectrum-analytics_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/spectrum-analytics_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "spectrum-analytics_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/spectrum-analytics_messages" }, "messages": { "$ref": "#/components/schemas/spectrum-analytics_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "spectrum-analytics_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/spectrum-analytics_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/spectrum-analytics_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "spectrum-analytics_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/spectrum-analytics_api-response-common" } ] }, "spectrum-analytics_app_id_param": { "description": "Comma-delimited list of Spectrum Application Id(s). If provided, the response will be limited to Spectrum Application Id(s) that match.", "type": "string", "example": "ea95132c15732412d22c1476fa83f27a,d122c5f4bb71e25cc9e86ab43b142e2f" }, "spectrum-analytics_column": { "type": "object", "properties": { "dimensions": { "type": "array", "items": { "type": "string" } }, "metrics": { "oneOf": [ { "items": { "type": "number" }, "type": "array" }, { "items": { "items": { "type": "number" }, "type": "array" }, "type": "array" } ] } } }, "spectrum-analytics_dimensions": { "description": "Can be used to break down the data by given attributes. Options are:\n\nDimension | Name | Example\n--------------------------|---------------------------------|--------------------------\nevent | Connection Event | connect, progress, disconnect, originError, clientFiltered\nappID | Application ID | 40d67c87c6cd4b889a4fd57805225e85\ncoloName | Colo Name | SFO\nipVersion | IP version used by the client | 4, 6.", "type": "array", "items": { "enum": [ "event", "appID", "coloName", "ipVersion" ], "type": "string" }, "example": [ "event", "appID" ] }, "spectrum-analytics_filters": { "description": "Used to filter rows by one or more dimensions. Filters can be combined using OR and AND boolean logic. AND takes precedence over OR in all the expressions. The OR operator is defined using a comma (,) or OR keyword surrounded by whitespace. The AND operator is defined using a semicolon (;) or AND keyword surrounded by whitespace. Note that the semicolon is a reserved character in URLs (rfc1738) and needs to be percent-encoded as %3B. Comparison options are:\n\nOperator | Name | URL Encoded\n--------------------------|---------------------------------|--------------------------\n== | Equals | %3D%3D\n!= | Does not equals | !%3D\n\\> | Greater Than | %3E\n\\< | Less Than | %3C\n\\>= | Greater than or equal to | %3E%3D\n\\<= | Less than or equal to | %3C%3D\n\nUse the above to construct filters.", "type": "string", "example": "event==disconnect%20AND%20coloName!=SFO" }, "spectrum-analytics_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "spectrum-analytics_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "spectrum-analytics_metrics": { "description": "One or more metrics to compute. Options are:\n\nMetric | Name | Example | Unit\n--------------------------|-------------------------------------|--------------------------|--------------------------\ncount | Count of total events | 1000 | Count\nbytesIngress | Sum of ingress bytes | 1000 | Sum\nbytesEgress | Sum of egress bytes | 1000 | Sum\ndurationAvg | Average connection duration | 1.0 | Time in milliseconds\ndurationMedian | Median connection duration | 1.0 | Time in milliseconds\nduration90th | 90th percentile connection duration | 1.0 | Time in milliseconds\nduration99th | 99th percentile connection duration | 1.0 | Time in milliseconds.", "type": "array", "items": { "enum": [ "count", "bytesIngress", "bytesEgress", "durationAvg", "durationMedian", "duration90th", "duration99th" ], "type": "string" }, "example": [ "count", "bytesIngress" ] }, "spectrum-analytics_query": { "type": "object", "properties": { "dimensions": { "$ref": "#/components/schemas/spectrum-analytics_dimensions" }, "filters": { "$ref": "#/components/schemas/spectrum-analytics_filters" }, "limit": { "description": "Limit number of returned metrics.", "type": "number" }, "metrics": { "$ref": "#/components/schemas/spectrum-analytics_metrics" }, "since": { "$ref": "#/components/schemas/spectrum-analytics_since" }, "sort": { "$ref": "#/components/schemas/spectrum-analytics_sort" }, "until": { "$ref": "#/components/schemas/spectrum-analytics_until" } } }, "spectrum-analytics_query-response-aggregate": { "allOf": [ { "$ref": "#/components/schemas/spectrum-analytics_api-response-single" }, { "properties": { "result": { "type": "array", "items": { "properties": { "appID": { "allOf": [ { "description": "Application identifier." }, { "$ref": "#/components/schemas/spectrum-analytics_identifier" } ] }, "bytesEgress": { "description": "Number of bytes sent.", "type": "number" }, "bytesIngress": { "description": "Number of bytes received.", "type": "number" }, "connections": { "description": "Number of connections.", "type": "number" }, "durationAvg": { "description": "Average duration of connections.", "type": "number" } }, "required": [ "appID", "bytesIngress", "bytesEgress", "connections", "durationAvg" ], "type": "object" } } } } ] }, "spectrum-analytics_query-response-single": { "allOf": [ { "$ref": "#/components/schemas/spectrum-analytics_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "data": { "description": "List of columns returned by the analytics query.", "type": "array", "items": { "$ref": "#/components/schemas/spectrum-analytics_column" } }, "data_lag": { "description": "Number of seconds between current time and last processed event, i.e. how many seconds of data could be missing.", "type": "number", "example": 3, "minimum": 0 }, "max": { "allOf": [ { "description": "Maximum result for each selected metrics across all data." }, { "$ref": "#/components/schemas/spectrum-analytics_stat" } ] }, "min": { "allOf": [ { "description": "Minimum result for each selected metrics across all data." }, { "$ref": "#/components/schemas/spectrum-analytics_stat" } ] }, "query": { "$ref": "#/components/schemas/spectrum-analytics_query" }, "rows": { "description": "Total number of rows in the result.", "type": "number", "example": 5, "minimum": 0 }, "time_intervals": { "description": "List of time interval buckets: [start, end].", "type": "array", "items": { "items": { "$ref": "#/components/schemas/spectrum-analytics_timestamp" }, "type": "array" } }, "totals": { "allOf": [ { "description": "Total result for each selected metrics across all data." }, { "$ref": "#/components/schemas/spectrum-analytics_stat" } ] } }, "required": [ "rows", "data", "data_lag", "min", "max", "totals", "query" ] } } } ] }, "spectrum-analytics_since": { "allOf": [ { "description": "Start of time interval to query, defaults to `until` - 6 hours. Timestamp must be in RFC3339 format and uses UTC unless otherwise specified." }, { "$ref": "#/components/schemas/spectrum-analytics_timestamp" } ] }, "spectrum-analytics_sort": { "description": "The sort order for the result set; sort fields must be included in `metrics` or `dimensions`.", "type": "array", "items": { "type": "string" }, "example": [ "+count", "-bytesIngress" ] }, "spectrum-analytics_stat": { "type": "object", "example": { "bytesEgress": 100, "bytesIngress": 50 }, "additionalProperties": { "type": "number" } }, "spectrum-analytics_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "x-auditable": true }, "spectrum-analytics_until": { "allOf": [ { "description": "End of time interval to query, defaults to current time. Timestamp must be in RFC3339 format and uses UTC unless otherwise specified." }, { "$ref": "#/components/schemas/spectrum-analytics_timestamp" } ] }, "spectrum-analytics_zone_report": { "type": "object", "properties": { "totals": { "type": "object", "properties": { "bandwidth": { "type": "object", "properties": { "all": { "description": "Sum of ingress and egress bytes transferred.", "type": "number" }, "egress": { "description": "Sum of egress bytes transferred.", "type": "number" }, "ingress": { "description": "Sum of ingress bytes transferred.", "type": "number" } }, "required": [ "all", "ingress", "egress" ] } }, "required": [ "bandwidth" ] }, "zone_id": { "$ref": "#/components/schemas/spectrum-analytics_identifier" } }, "required": [ "zone_id", "totals" ] }, "spectrum-analytics_zones_report_response": { "allOf": [ { "$ref": "#/components/schemas/spectrum-analytics_api-response-collection" }, { "properties": { "query": { "properties": { "since": { "$ref": "#/components/schemas/spectrum-analytics_since" }, "until": { "$ref": "#/components/schemas/spectrum-analytics_until" } }, "required": [ "since", "until" ], "type": "object" }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/spectrum-analytics_zone_report" } } }, "required": [ "query", "result" ] } ] }, "spectrum-config_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/spectrum-config_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "spectrum-config_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/spectrum-config_messages" }, "messages": { "$ref": "#/components/schemas/spectrum-config_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "spectrum-config_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/spectrum-config_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/spectrum-config_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "spectrum-config_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/spectrum-config_api-response-common" } ] }, "spectrum-config_api-response-single-id": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/spectrum-config_api-response-common" }, { "properties": { "result": { "type": "object", "nullable": true, "properties": { "id": { "$ref": "#/components/schemas/spectrum-config_identifier" } }, "required": [ "id" ] } }, "type": "object" } ] }, "spectrum-config_app_config": { "allOf": [ { "$ref": "#/components/schemas/spectrum-config_base_app_config" }, { "properties": { "argo_smart_routing": { "$ref": "#/components/schemas/spectrum-config_argo_smart_routing" }, "dns": { "$ref": "#/components/schemas/spectrum-config_dns" }, "edge_ips": { "$ref": "#/components/schemas/spectrum-config_edge_ips" }, "ip_firewall": { "$ref": "#/components/schemas/spectrum-config_ip_firewall" }, "origin_direct": { "$ref": "#/components/schemas/spectrum-config_origin_direct" }, "origin_dns": { "$ref": "#/components/schemas/spectrum-config_origin_dns" }, "origin_port": { "$ref": "#/components/schemas/spectrum-config_origin_port" }, "protocol": { "$ref": "#/components/schemas/spectrum-config_protocol" }, "proxy_protocol": { "$ref": "#/components/schemas/spectrum-config_proxy_protocol" }, "tls": { "$ref": "#/components/schemas/spectrum-config_tls" }, "traffic_type": { "$ref": "#/components/schemas/spectrum-config_traffic_type" }, "virtual_network_id": { "$ref": "#/components/schemas/spectrum-config_virtual_network_id" } }, "required": [ "protocol", "dns", "traffic_type" ], "type": "object" } ] }, "spectrum-config_app_config_collection": { "allOf": [ { "$ref": "#/components/schemas/spectrum-config_api-response-collection" }, { "properties": { "result": { "oneOf": [ { "items": { "$ref": "#/components/schemas/spectrum-config_app_config" }, "type": "array" }, { "items": { "$ref": "#/components/schemas/spectrum-config_paygo_app_config" }, "type": "array" } ] } }, "type": "object" } ] }, "spectrum-config_app_config_single": { "allOf": [ { "$ref": "#/components/schemas/spectrum-config_api-response-single" }, { "properties": { "result": { "oneOf": [ { "$ref": "#/components/schemas/spectrum-config_app_config" }, { "$ref": "#/components/schemas/spectrum-config_paygo_app_config" } ] } }, "type": "object" } ] }, "spectrum-config_app_identifier": { "description": "App identifier.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/spectrum-config_identifier" } ], "readOnly": true }, "spectrum-config_app_protocol": { "type": "object", "properties": { "description": { "description": "The full name of the application protocol.", "type": "string", "example": "Minecraft Game Server" }, "name": { "description": "The short name of the application protocol.", "type": "string", "example": "Minecraft" }, "ports": { "description": "The available listening ports for the given protocol.", "type": "array", "items": { "maximum": 65535, "minimum": 1, "type": "integer" }, "example": [ 25565 ] }, "transport": { "description": "The transport layer protocol used by the application protocol", "type": "string", "example": "tcp" } }, "required": [ "description", "name", "ports", "transport" ] }, "spectrum-config_argo_smart_routing": { "description": "Enables Argo Smart Routing for this application.\nNotes: Only available for TCP or UDP applications with traffic_type set to \"direct\".", "type": "boolean", "example": true, "default": false }, "spectrum-config_base_app_config": { "type": "object", "properties": { "created_on": { "$ref": "#/components/schemas/spectrum-config_created" }, "id": { "$ref": "#/components/schemas/spectrum-config_app_identifier" }, "modified_on": { "$ref": "#/components/schemas/spectrum-config_modified" } }, "required": [ "id", "created_on", "modified_on" ] }, "spectrum-config_created": { "description": "When the Application was created.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/spectrum-config_timestamp" } ], "readOnly": true }, "spectrum-config_dns": { "description": "The name and type of DNS record for the Spectrum application.", "type": "object", "properties": { "name": { "$ref": "#/components/schemas/spectrum-config_dns_name" }, "type": { "$ref": "#/components/schemas/spectrum-config_dns_type" } } }, "spectrum-config_dns_name": { "description": "The name of the DNS record associated with the application.", "type": "string", "format": "hostname", "example": "ssh.example.com" }, "spectrum-config_dns_ttl": { "description": "The TTL of our resolution of your DNS record in seconds.", "type": "integer", "minimum": 600 }, "spectrum-config_dns_type": { "description": "The type of DNS record associated with the application.", "type": "string", "example": "CNAME", "enum": [ "CNAME", "ADDRESS" ] }, "spectrum-config_edge_ips": { "description": "The anycast edge IP configuration for the hostname of this application.", "default": { "connectivity": "all", "type": "dynamic" }, "oneOf": [ { "properties": { "connectivity": { "description": "The IP versions supported for inbound connections on Spectrum anycast IPs.", "type": "string", "example": "all", "enum": [ "all", "ipv4", "ipv6" ] }, "type": { "description": "The type of edge IP configuration specified. Dynamically allocated edge IPs use Spectrum anycast IPs in accordance with the connectivity you specify. Only valid with CNAME DNS names.", "type": "string", "example": "dynamic", "enum": [ "dynamic" ] } }, "type": "object" }, { "properties": { "ips": { "description": "The array of customer owned IPs we broadcast via anycast for this hostname and application.", "type": "array", "items": { "description": "Edge anycast IPs.", "example": "192.0.2.1", "type": "string" }, "example": [ "192.0.2.1" ] }, "type": { "description": "The type of edge IP configuration specified. Statically allocated edge IPs use customer IPs in accordance with the ips array you specify. Only valid with ADDRESS DNS names.", "type": "string", "example": "static", "enum": [ "static" ] } }, "type": "object" } ] }, "spectrum-config_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "spectrum-config_ip_firewall": { "description": "Enables IP Access Rules for this application.\nNotes: Only available for TCP applications.", "type": "boolean", "example": false, "default": false }, "spectrum-config_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "spectrum-config_modified": { "description": "When the Application was last modified.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/spectrum-config_timestamp" } ], "readOnly": true }, "spectrum-config_origin_direct": { "description": "List of origin IP addresses. Array may contain multiple IP addresses for load balancing.", "type": "array", "items": { "example": "tcp://127.0.0.1:8080", "format": "URI", "type": "string" } }, "spectrum-config_origin_dns": { "description": "The name and type of DNS record for the Spectrum application.", "type": "object", "properties": { "name": { "$ref": "#/components/schemas/spectrum-config_origin_dns_name" }, "ttl": { "$ref": "#/components/schemas/spectrum-config_dns_ttl" }, "type": { "$ref": "#/components/schemas/spectrum-config_origin_dns_type" } } }, "spectrum-config_origin_dns_name": { "description": "The name of the DNS record associated with the origin.", "type": "string", "format": "hostname", "example": "origin.example.com" }, "spectrum-config_origin_dns_type": { "description": "The type of DNS record associated with the origin. \"\" is used to specify a combination of A/AAAA records.", "type": "string", "example": "", "enum": [ "", "A", "AAAA", "SRV" ] }, "spectrum-config_origin_port": { "description": "The destination port at the origin. Only specified in conjunction with origin_dns. May use an integer to specify a single origin port, for example `1000`, or a string to specify a range of origin ports, for example `\"1000-2000\"`.\nNotes: If specifying a port range, the number of ports in the range must match the number of ports specified in the \"protocol\" field.", "example": 22, "anyOf": [ { "type": "integer" }, { "type": "string" } ], "maximum": 65535, "minimum": 1 }, "spectrum-config_paygo_app_config": { "allOf": [ { "$ref": "#/components/schemas/spectrum-config_base_app_config" }, { "properties": { "dns": { "$ref": "#/components/schemas/spectrum-config_dns" }, "origin_direct": { "$ref": "#/components/schemas/spectrum-config_origin_direct" }, "protocol": { "$ref": "#/components/schemas/spectrum-config_protocol" } }, "required": [ "protocol", "dns" ], "type": "object" } ] }, "spectrum-config_protocol": { "description": "The port configuration at Cloudflare's edge. May specify a single port, for example `\"tcp/1000\"`, or a range of ports, for example `\"tcp/1000-2000\"`.", "type": "string", "example": "tcp/22" }, "spectrum-config_protocol_collection": { "allOf": [ { "$ref": "#/components/schemas/spectrum-config_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/spectrum-config_app_protocol" } } }, "type": "object" } ] }, "spectrum-config_proxy_protocol": { "description": "Enables Proxy Protocol to the origin. Refer to [Enable Proxy protocol](https://developers.cloudflare.com/spectrum/getting-started/proxy-protocol/) for implementation details on PROXY Protocol V1, PROXY Protocol V2, and Simple Proxy Protocol.", "type": "string", "example": "off", "default": "off", "enum": [ "off", "v1", "v2", "simple" ] }, "spectrum-config_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "x-auditable": true }, "spectrum-config_tls": { "description": "The type of TLS termination associated with the application.", "type": "string", "example": "off", "default": "off", "enum": [ "off", "flexible", "full", "strict" ] }, "spectrum-config_traffic_type": { "description": "Determines how data travels from the edge to your origin. When set to \"direct\", Spectrum will send traffic directly to your origin, and the application's type is derived from the `protocol`. When set to \"http\" or \"https\", Spectrum will apply Cloudflare's HTTP/HTTPS features as it sends traffic to your origin, and the application type matches this property exactly.", "type": "string", "example": "direct", "default": "direct", "enum": [ "direct", "http", "https" ] }, "spectrum-config_update_app_config": { "oneOf": [ { "$ref": "#/components/schemas/spectrum-config_app_config" }, { "$ref": "#/components/schemas/spectrum-config_paygo_app_config" } ] }, "spectrum-config_virtual_network_id": { "description": "Optional UUID of a virtual network for routing origin traffic through tunnel virtual networks.", "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, "spectrum-config_zone_identifier": { "description": "Zone identifier.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/spectrum-config_identifier" } ], "readOnly": true }, "speed_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/speed_messages" }, "messages": { "$ref": "#/components/schemas/speed_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "x-auditable": true } }, "required": [ "success", "errors", "messages" ] }, "speed_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/speed_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/speed_messages" } ] }, "result": { "type": "object", "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "x-auditable": true } }, "required": [ "success", "errors", "messages", "result" ] }, "speed_api-response-single-id": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/speed_api-response-common" }, { "properties": { "result": { "type": "object", "nullable": true, "properties": { "id": { "$ref": "#/components/schemas/speed_identifier" } }, "required": [ "id" ] } }, "type": "object" } ] }, "speed_automatic_platform_optimization_response": { "description": "Controls Automatic Platform Optimization (APO) for WordPress.", "allOf": [ { "$ref": "#/components/schemas/speed_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "automatic_platform_optimization", "enum": [ "automatic_platform_optimization" ], "x-auditable": true }, "value": { "$ref": "#/components/schemas/speed_automatic_platform_optimization_value" } }, "type": "object" } ], "title": "Automatic Platform Optimization setting" }, "speed_automatic_platform_optimization_value": { "description": "Configuration for Automatic Platform Optimization (APO) for WordPress.\nSet to \"off\" to disable, or provide an object to configure APO settings.\n", "oneOf": [ { "description": "Disable Automatic Platform Optimization.", "enum": [ "off" ], "type": "string" }, { "properties": { "cache_by_device_type": { "description": "Whether to cache by device type.", "type": "boolean", "example": false }, "cf": { "description": "Whether the zone is proxied through Cloudflare.", "type": "boolean", "example": true }, "enabled": { "description": "Whether APO is enabled.", "type": "boolean", "example": true }, "hostnames": { "description": "List of hostnames where APO is active.", "type": "array", "items": { "type": "string" }, "example": [ "www.example.com" ] }, "recheck": { "description": "Whether to recheck WordPress and plugin detection.", "type": "boolean", "example": false }, "wordpress": { "description": "Whether the site is a WordPress site.", "type": "boolean", "example": true }, "wp_plugin": { "description": "Whether the Cloudflare WordPress plugin is installed.", "type": "boolean", "example": true } }, "required": [ "cf", "enabled", "wordpress", "wp_plugin" ], "type": "object" } ], "title": "Automatic Platform Optimization value" }, "speed_base": { "properties": { "editable": { "description": "Whether or not this setting can be modified for this zone (based on your Cloudflare plan level).", "type": "boolean", "enum": [ true, false ], "readOnly": true, "x-auditable": true }, "id": { "description": "Identifier of the zone setting.", "type": "string", "example": "development_mode", "x-auditable": true }, "modified_on": { "description": "last time this setting was modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "nullable": true, "readOnly": true, "x-auditable": true }, "value": { "description": "Current value of the zone setting.", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } } }, "speed_binary_ast_response": { "description": "Controls Binary AST JavaScript parsing for the zone.", "allOf": [ { "$ref": "#/components/schemas/speed_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "binary_ast", "enum": [ "binary_ast" ], "x-auditable": true }, "value": { "$ref": "#/components/schemas/speed_binary_ast_value" } }, "type": "object" } ], "title": "Binary AST setting" }, "speed_binary_ast_value": { "description": "Controls Binary AST behavior:\n- \"off\": Feature disabled.\n- \"on\": Binary AST enabled.\n- \"latest\": Binary AST enabled using the latest version.\n", "type": "string", "enum": [ "off", "on", "latest" ], "x-auditable": true }, "speed_cloudflare_fonts": { "description": "Enhance your website's font delivery with Cloudflare Fonts. Deliver Google Hosted fonts from your own domain,\nboost performance, and enhance user privacy. Refer to the Cloudflare Fonts documentation for more information.\n", "allOf": [ { "$ref": "#/components/schemas/speed_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "fonts", "enum": [ "fonts" ], "x-auditable": true }, "value": { "$ref": "#/components/schemas/speed_cloudflare_fonts_value" } }, "type": "object" } ], "title": "Cloudflare Fonts" }, "speed_cloudflare_fonts_value": { "description": "Whether the feature is enabled or disabled.", "type": "string", "default": "off", "enum": [ "on", "off" ], "x-auditable": true }, "speed_cloudflare_speed_brain_response": { "allOf": [ { "$ref": "#/components/schemas/speed_base" }, { "properties": { "value": { "description": "Whether the feature is enabled or disabled.\nDefaults to \"on\" for Free plans, otherwise defaults to \"off\".\n", "type": "string" } }, "type": "object" } ], "title": "Cloudflare Speed Brain response" }, "speed_h2_prioritization_response": { "description": "Controls HTTP/2 Prioritization for the zone.", "allOf": [ { "$ref": "#/components/schemas/speed_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "h2_prioritization", "enum": [ "h2_prioritization" ], "x-auditable": true }, "value": { "$ref": "#/components/schemas/speed_h2_prioritization_value" } }, "type": "object" } ], "title": "HTTP/2 Prioritization setting" }, "speed_h2_prioritization_value": { "description": "Controls HTTP/2 Prioritization behavior:\n- \"off\": Use browser default prioritization.\n- \"on\": Use Cloudflare's optimized prioritization.\n- \"custom\": Use custom prioritization rules.\n", "type": "string", "enum": [ "off", "on", "custom" ], "x-auditable": true }, "speed_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "speed_image_resizing_response": { "description": "Controls Cloudflare Image Resizing for the zone.", "allOf": [ { "$ref": "#/components/schemas/speed_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "image_resizing", "enum": [ "image_resizing" ], "x-auditable": true }, "value": { "$ref": "#/components/schemas/speed_image_resizing_value" } }, "type": "object" } ], "title": "Image Resizing setting" }, "speed_image_resizing_value": { "description": "Controls Image Resizing behavior:\n- \"off\": Feature disabled.\n- \"on\": Resizing is enabled for same-zone images only.\n- \"open\": Resizing is enabled for images from any origin.\n- \"latest\": Resizing is enabled for same-zone images using the latest version.\n", "type": "string", "enum": [ "off", "on", "open", "latest" ], "x-auditable": true }, "speed_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000, "x-auditable": true }, "message": { "type": "string", "x-auditable": true } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "speed_transformations_allowed_origins_response": { "description": "Controls which origins are allowed to request image and video transformations.\n", "allOf": [ { "$ref": "#/components/schemas/speed_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "image_resizing_allowed_origins", "enum": [ "image_resizing_allowed_origins" ], "x-auditable": true }, "value": { "$ref": "#/components/schemas/speed_transformations_allowed_origins_value" } }, "type": "object" } ], "title": "Image Transformations Allowed Origins setting" }, "speed_transformations_allowed_origins_value": { "description": "Comma-separated list of allowed origin domains for image and video transformations.\nUse \"*\" to allow all origins (default).\n", "type": "string", "example": "example.com,cdn.example.com", "x-auditable": true }, "speed_transformations_c2pa_response": { "description": "Controls C2PA signing for images processed through Cloudflare Image Transformations.", "allOf": [ { "$ref": "#/components/schemas/speed_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "image_resizing_c2pa", "enum": [ "image_resizing_c2pa" ], "x-auditable": true }, "value": { "$ref": "#/components/schemas/speed_transformations_c2pa_value" } }, "type": "object" } ], "title": "Image Transformations C2PA setting" }, "speed_transformations_c2pa_value": { "description": "Whether C2PA signing is enabled for image transformations.", "type": "string", "enum": [ "off", "on" ], "x-auditable": true }, "speed_transformations_config_response": { "description": "Combined view of Transformations, Allowed Origins, and C2PA settings for a zone.\n", "allOf": [ { "$ref": "#/components/schemas/speed_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "transformations_config", "enum": [ "transformations_config" ], "x-auditable": true }, "value": { "$ref": "#/components/schemas/speed_transformations_config_value" } }, "type": "object" } ], "title": "Transformations combined configuration" }, "speed_transformations_config_value": { "description": "Combined configuration value for Transformations. All fields are optional on PATCH;\nomitted fields are left unchanged.\n", "type": "object", "properties": { "allowed_origins": { "description": "Comma-separated list of allowed origin domains for image and video transformations.\nUse \"*\" to allow all origins (default).\n", "type": "string", "example": "example.com,cdn.example.com", "x-auditable": true }, "c2pa": { "description": "Whether C2PA signing is enabled for image transformations.", "type": "string", "enum": [ "off", "on" ], "x-auditable": true }, "transformations": { "description": "Controls Image Transformations behavior:\n- \"off\": Feature disabled.\n- \"on\": Transformations enabled for same-zone images only.\n- \"open\": Transformations enabled for images from any origin.\n- \"latest\": Transformations enabled using the latest version.\n", "type": "string", "enum": [ "off", "on", "open", "latest" ], "x-auditable": true } } }, "speed_ut_billing_response": { "description": "Controls Unique Transformations billing for the account.", "allOf": [ { "$ref": "#/components/schemas/speed_base" }, { "properties": { "id": { "description": "ID of the account setting.", "type": "string", "example": "ut_billing", "enum": [ "ut_billing" ], "x-auditable": true }, "value": { "$ref": "#/components/schemas/speed_ut_billing_value" } }, "type": "object" } ], "title": "Unique Transformations billing setting" }, "speed_ut_billing_value": { "description": "Enables Unique Transformations billing for the account.\nNote: once enabled, this setting cannot be set back to \"off\".\n", "type": "string", "enum": [ "on" ], "x-auditable": true }, "speed_zone_config_item": { "description": "A configuration item for a specific zone and feature.", "type": "object", "properties": { "cf_zone_tag": { "description": "Zone tag identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "x-auditable": true }, "editable": { "description": "Whether this setting can be modified.", "type": "boolean", "example": true, "readOnly": true, "x-auditable": true }, "id": { "description": "Feature identifier.", "type": "string", "example": "image_resizing", "x-auditable": true }, "modified_on": { "description": "When this setting was last modified.", "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z", "nullable": true, "readOnly": true, "x-auditable": true }, "value": { "description": "Current value of the feature setting.", "example": "on", "x-auditable": true } }, "title": "Zone configuration item" }, "stream_accessRules": { "description": "Defines rules for fine-grained control over content than signed URL tokens alone. Access rules primarily make tokens conditionally valid based on user information. Access Rules are specified on token payloads as the `accessRules` property containing an array of Rule objects.", "type": "object", "properties": { "action": { "description": "The action to take when a request matches a rule. If the action is `block`, the signed token blocks views for viewers matching the rule.", "type": "string", "example": "allow", "enum": [ "allow", "block" ], "x-auditable": true }, "country": { "description": "An array of 2-letter country codes in ISO 3166-1 Alpha-2 format used to match requests.", "type": "array", "items": { "type": "string", "x-auditable": true } }, "ip": { "description": "An array of IPv4 or IPV6 addresses or CIDRs used to match requests.", "type": "array", "items": { "type": "string", "x-auditable": true } }, "type": { "description": "Lists available rule types to match for requests. An `any` type matches all requests and can be used as a wildcard to apply default actions after other rules.", "type": "string", "example": "ip.src", "enum": [ "any", "ip.src", "ip.geoip.country" ], "x-auditable": true } } }, "stream_account_identifier": { "description": "The account identifier tag.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "stream_addAudioTrackResponse": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/stream_additionalAudio" } }, "type": "object" } ] }, "stream_additionalAudio": { "type": "object", "properties": { "default": { "$ref": "#/components/schemas/stream_audio_default" }, "label": { "$ref": "#/components/schemas/stream_audio_label" }, "status": { "$ref": "#/components/schemas/stream_audio_state" }, "uid": { "$ref": "#/components/schemas/stream_identifier" } } }, "stream_allowedOrigins": { "description": "Lists the origins allowed to display the video. Enter allowed origin domains in an array and use `*` for wildcard subdomains. Empty arrays allow the video to be viewed on any origin.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "example.com" ] }, "stream_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/stream_messages" }, "messages": { "$ref": "#/components/schemas/stream_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "stream_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/stream_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/stream_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "stream_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/stream_api-response-common" } ] }, "stream_asc": { "description": "Lists videos in ascending order of creation.", "type": "boolean", "example": true, "default": false }, "stream_audio_default": { "description": "Denotes whether the audio track will be played by default in a player.", "type": "boolean", "default": false, "x-auditable": true }, "stream_audio_identifier": { "description": "The unique identifier for an additional audio track.", "type": "string", "example": "ea95132c15732412d22c1476fa83f27a", "maxLength": 32, "x-auditable": true }, "stream_audio_label": { "description": "A string to uniquely identify the track amongst other audio track labels for the specified video.", "type": "string", "example": "director commentary", "x-auditable": true }, "stream_audio_state": { "description": "Specifies the processing status of the video.", "type": "string", "enum": [ "queued", "ready", "error" ], "x-auditable": true }, "stream_caption_basic_upload": { "type": "object", "properties": { "file": { "description": "The WebVTT file containing the caption or subtitle content.", "type": "string", "example": "@/Users/kyle/Desktop/tr.vtt", "x-auditable": true } }, "required": [ "file" ] }, "stream_caption_status": { "description": "The status of a generated caption.", "type": "string", "enum": [ "ready", "inprogress", "error" ], "x-auditable": true }, "stream_captions": { "type": "object", "properties": { "generated": { "$ref": "#/components/schemas/stream_generated_caption" }, "label": { "$ref": "#/components/schemas/stream_label" }, "language": { "$ref": "#/components/schemas/stream_language" }, "status": { "$ref": "#/components/schemas/stream_caption_status" } } }, "stream_clipResponseSingle": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/stream_videos" } }, "type": "object" } ] }, "stream_clipped_from_video_uid": { "description": "The unique video identifier (UID).", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "stream_copyAudioTrack": { "type": "object", "properties": { "label": { "$ref": "#/components/schemas/stream_audio_label" }, "url": { "description": "An audio track URL. The server must be publicly routable and support `HTTP HEAD` requests and `HTTP GET` range requests. The server should respond to `HTTP HEAD` requests with a `content-range` header that includes the size of the file.", "type": "string", "format": "uri", "example": "https://www.examplestorage.com/audio_file.mp3", "x-auditable": true } }, "required": [ "label" ] }, "stream_create_input_request": { "properties": { "defaultCreator": { "$ref": "#/components/schemas/stream_live_input_default_creator" }, "deleteRecordingAfterDays": { "$ref": "#/components/schemas/stream_live_input_recording_deletion" }, "enabled": { "$ref": "#/components/schemas/stream_live_input_enabled" }, "meta": { "$ref": "#/components/schemas/stream_live_input_metadata" }, "preferLowLatency": { "$ref": "#/components/schemas/stream_live_input_prefer_low_latency" }, "recording": { "$ref": "#/components/schemas/stream_live_input_recording_settings" } } }, "stream_create_output_request": { "properties": { "enabled": { "$ref": "#/components/schemas/stream_output_enabled" }, "streamKey": { "$ref": "#/components/schemas/stream_output_streamKey" }, "url": { "$ref": "#/components/schemas/stream_output_url" } }, "required": [ "url", "streamKey" ] }, "stream_created": { "description": "The date and time the media item was created.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z", "x-auditable": true }, "stream_creator": { "description": "A user-defined identifier for the media creator.", "type": "string", "example": "creator-id_abcde12345", "maxLength": 64, "x-auditable": true }, "stream_deleted_response": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-single" }, { "properties": { "result": { "type": "string", "example": "ok" } }, "type": "object" } ] }, "stream_direct_upload_request": { "type": "object", "properties": { "allowedOrigins": { "$ref": "#/components/schemas/stream_allowedOrigins" }, "creator": { "$ref": "#/components/schemas/stream_creator" }, "expiry": { "description": "The date and time after upload when videos will not be accepted.", "type": "string", "format": "date-time", "example": "2021-01-02T02:20:00Z", "default": "Now + 30 minutes", "x-auditable": true }, "maxDurationSeconds": { "$ref": "#/components/schemas/stream_maxDurationSeconds" }, "meta": { "$ref": "#/components/schemas/stream_media_metadata" }, "requireSignedURLs": { "$ref": "#/components/schemas/stream_requireSignedURLs" }, "scheduledDeletion": { "$ref": "#/components/schemas/stream_scheduledDeletion" }, "thumbnailTimestampPct": { "$ref": "#/components/schemas/stream_thumbnailTimestampPct" }, "watermark": { "$ref": "#/components/schemas/stream_watermark_at_upload" } }, "required": [ "maxDurationSeconds" ] }, "stream_direct_upload_response": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "scheduledDeletion": { "$ref": "#/components/schemas/stream_scheduledDeletion" }, "uid": { "$ref": "#/components/schemas/stream_identifier" }, "uploadURL": { "description": "The URL an unauthenticated upload can use for a single `HTTP POST multipart/form-data` request.", "type": "string", "example": "www.example.com/samplepath" }, "watermark": { "$ref": "#/components/schemas/stream_watermarks" } } } }, "type": "object" } ] }, "stream_direct_user": { "description": "Provisions a URL to let your end users upload videos directly to Cloudflare Stream without exposing your API token to clients.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "stream_download_percent_complete": { "description": "Indicates the progress as a percentage between 0 and 100.", "type": "number", "maximum": 100, "minimum": 0, "x-auditable": true }, "stream_download_status": { "description": "The status of a generated download.", "type": "string", "enum": [ "ready", "inprogress", "error" ], "x-auditable": true }, "stream_download_type": { "description": "The type of downloads available are: `default`, `audio`.", "type": "string", "example": "audio", "default": "default", "enum": [ "default", "audio" ], "x-auditable": true }, "stream_download_url": { "description": "The URL to access the generated download.", "type": "string", "format": "uri", "example": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/downloads/default.mp4", "x-auditable": true }, "stream_downloadedFrom": { "description": "The source URL for a downloaded image. If the watermark profile was created via direct upload, this field is null.", "type": "string", "example": "https://company.com/logo.png", "x-auditable": true }, "stream_downloads": { "type": "object", "properties": { "percentComplete": { "$ref": "#/components/schemas/stream_download_percent_complete" }, "status": { "$ref": "#/components/schemas/stream_download_status" }, "url": { "$ref": "#/components/schemas/stream_download_url" } }, "required": [ "status", "percentComplete" ] }, "stream_downloads_response": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-single" }, { "properties": { "result": { "description": "An object with download type keys. Each key is optional and only present if that download type has been created.", "type": "object", "properties": { "audio": { "description": "The audio-only download. Only present if this download type has been created.", "allOf": [ { "$ref": "#/components/schemas/stream_downloads" } ] }, "default": { "description": "The default video download. Only present if this download type has been created.", "allOf": [ { "$ref": "#/components/schemas/stream_downloads" } ] } } } }, "type": "object" } ] }, "stream_duration": { "description": "The duration of the video in seconds. A value of `-1` means the duration is unknown. The duration becomes available after the upload and before the video is ready.", "type": "number", "x-auditable": true }, "stream_editAudioTrack": { "type": "object", "properties": { "default": { "$ref": "#/components/schemas/stream_audio_default" }, "label": { "$ref": "#/components/schemas/stream_audio_label" } } }, "stream_end": { "description": "Lists videos created before the specified date.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z" }, "stream_end_time_seconds": { "description": "Specifies the end time for the video clip in seconds.", "type": "integer", "x-auditable": true }, "stream_errorReasonCode": { "description": "Specifies why the video failed to encode. This field is empty if the video is not in an `error` state. Preferred for programmatic use.", "type": "string", "example": "ERR_NON_VIDEO", "x-auditable": true }, "stream_errorReasonText": { "description": "Specifies why the video failed to encode using a human readable error message in English. This field is empty if the video is not in an `error` state.", "type": "string", "example": "The file was not recognized as a valid video file.", "x-auditable": true }, "stream_generated_caption": { "description": "Whether the caption was generated via AI.", "type": "boolean", "example": true, "x-auditable": true }, "stream_height": { "description": "The height of the image in pixels.", "type": "integer", "x-auditable": true }, "stream_identifier": { "description": "A Cloudflare-generated unique identifier for a media item.", "type": "string", "example": "ea95132c15732412d22c1476fa83f27a", "maxLength": 32, "x-auditable": true }, "stream_identifier-2": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "stream_include_counts": { "description": "Includes the total number of videos associated with the submitted query parameters.", "type": "boolean", "example": true, "default": false }, "stream_input": { "type": "object", "properties": { "height": { "description": "The video height in pixels. A value of `-1` means the height is unknown. The value becomes available after the upload and before the video is ready.", "type": "integer", "x-auditable": true }, "width": { "description": "The video width in pixels. A value of `-1` means the width is unknown. The value becomes available after the upload and before the video is ready.", "type": "integer", "x-auditable": true } } }, "stream_input_rtmps": { "description": "Details for streaming to an live input using RTMPS.", "type": "object", "properties": { "streamKey": { "$ref": "#/components/schemas/stream_input_rtmps_stream_key" }, "url": { "$ref": "#/components/schemas/stream_input_rtmps_url" } } }, "stream_input_rtmps_stream_key": { "description": "The secret key to use when streaming via RTMPS to a live input.", "type": "string", "example": "2fb3cb9f17e68a2568d6ebed8d5505eak3ceaf8c9b1f395e1b76b79332497cada", "x-sensitive": true }, "stream_input_rtmps_url": { "description": "The RTMPS URL you provide to the broadcaster, which they stream live video to.", "type": "string", "example": "rtmps://live.cloudflare.com:443/live/", "x-sensitive": true }, "stream_input_srt": { "description": "Details for streaming to a live input using SRT.", "type": "object", "properties": { "passphrase": { "$ref": "#/components/schemas/stream_input_srt_stream_passphrase" }, "streamId": { "$ref": "#/components/schemas/stream_input_srt_stream_id" }, "url": { "$ref": "#/components/schemas/stream_input_srt_url" } } }, "stream_input_srt_stream_id": { "description": "The identifier of the live input to use when streaming via SRT.", "type": "string", "example": "f256e6ea9341d51eea64c9454659e576", "x-auditable": true }, "stream_input_srt_stream_passphrase": { "description": "The secret key to use when streaming via SRT to a live input.", "type": "string", "example": "2fb3cb9f17e68a2568d6ebed8d5505eak3ceaf8c9b1f395e1b76b79332497cada", "x-sensitive": true }, "stream_input_srt_url": { "description": "The SRT URL you provide to the broadcaster, which they stream live video to.", "type": "string", "example": "srt://live.cloudflare.com:778", "x-sensitive": true }, "stream_input_webrtc": { "description": "Details for streaming to a live input using WebRTC.", "type": "object", "properties": { "url": { "$ref": "#/components/schemas/stream_input_webrtc_url" } } }, "stream_input_webrtc_url": { "description": "The WebRTC URL you provide to the broadcaster, which they stream live video to.", "type": "string", "example": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/b236bde30eb07b9d01318940e5fc3edake34a3efb3896e18f2dc277ce6cc993ad/webRTC/publish", "x-sensitive": true }, "stream_jwk": { "description": "The signing key in JWK format.", "type": "string", "example": "eyJ1c2UiOiJzaWciLCJrdHkiOiJSU0EiLCJraWQiOiI1MjEzY2ZhMTIxZjcwYjhjMTM4MDY4NmZmYzM3MWJhMyIsImFsZyI6IlJTMjU2IiwibiI6IjBUandqT2laV21KNDN2ZjNUbzREb1htWFd0SkdOR3lYZmh5dHRMYUJnRjEtRVFXUURLaG9LYm9hS21xakNBc21za3V0YkxVN1BVOGRrUU5ER1p3S3VWczA4elNaNGt4aTR0RWdQUFp5dDdkWEMtbFlSWW95ckFHRjRBWGh5MzI5YkhDUDFJbHJCQl9Ba0dnbmRMQWd1bnhZMHJSZ2N2T3ppYXc2S0p4Rm5jMlVLMFdVOGIwcDRLS0hHcDFLTDlkazBXVDhkVllxYmVSaUpqQ2xVRW1oOHl2OUNsT1ZhUzRLeGlYNnhUUTREWnc2RGFKZklWM1F0Tmd2cG1ieWxOSmFQSG5zc3JodDJHS1A5NjJlS2poUVJsaWd2SFhKTE9uSm9KZkxlSUVIWi1peFdmY1RETUg5MnNHdm93MURPanhMaUNOMXpISy1oN2JMb1hUaUxnYzRrdyIsImUiOiJBUUFCIiwiZCI6IndpQWEwaU5mWnNYSGNOcVMxSWhnUmdzVHJHay1TcFlYV2lReDZHTU9kWlJKekhGazN0bkRERFJvNHNKZTBxX0dEOWkzNlEyZkVadS15elpEcEJkc3U5OHNtaHhNU19Ta0s5X3VFYUo1Zm96V2IyN3JRRnFoLVliUU9MUThkUnNPRHZmQl9Hb2txWWJzblJDR3kzWkFaOGZJZ25ocXBUNEpiOHdsaWxpMUgxeFpzM3RnTWtkTEluTm1yMFAtcTYxZEtNd3JYZVRoSWNEc0kyb2Z1LTFtRm1MWndQb2ZGbmxaTW9QN1pfRU5pUGNfWGtWNzFhaHBOZE9pcW5ablZtMHBCNE5QS1UweDRWTjQyYlAzWEhMUmpkV2hJOGt3SC1BdXhqb3BLaHJ0R2tvcG1jZFRkM1ZRdElaOGRpZHByMXpBaEpvQi16ZVlIaTFUel9ZSFFld0FRUSIsInAiOiIyVTZFVUJka3U3TndDYXoyNzZuWGMxRXgwVHpNZjU4U0UtU2M2eUNaYWk2TkwzVURpWi1mNHlIdkRLYnFGUXdLWDNwZ0l2aVE3Y05QYUpkbE9NeS1mU21GTXU3V3hlbVZYamFlTjJCMkRDazhQY0NEOVgxU2hhR3E1ZUdSSHNObVUtSDNxTG1FRGpjLWliazRHZ0RNb2lVYjQ2OGxFZHAwU2pIOXdsOUdsYTgiLCJxIjoiOW5ucXg5ZnNNY2dIZ29DemhfVjJmaDhoRUxUSUM5aFlIOVBCTG9aQjZIaE1TWG1ja1BSazVnUlpPWlFEN002TzlMaWZjNmFDVXdEbjBlQzU2YkFDNUNrcWxjODJsVDhzTWlMeWJyTjh3bWotcjNjSTBGQTlfSGQySEY1ZkgycnJmenVqd0NWM3czb09Ud3p4d1g3c2xKbklRanphel91SzEyWEtucVZZcUYwIiwiZHAiOiJxQklTUTlfVUNWaV9Ucng0UU9VYnZoVU9jc2FUWkNHajJiNzNudU9YeElnOHFuZldSSnN4RG5zd2FKaXdjNWJjYnZ3M1h0VGhRd1BNWnhpeE1UMHFGNlFGWVY5WXZibnJ6UEp4YkdNdTZqajZYc2lIUjFlbWU3U09lVDM4Xzg0aFZyOXV6UkN2RWstb0R0MHlodW9YVzFGWVFNRTE2cGtMV0ZkUjdRUERsQUUiLCJkcSI6Im5zQUp3eXZFbW8tdW5wU01qYjVBMHB6MExCRjBZNFMxeGRJYXNfLVBSYzd0dThsVFdWMl8teExEOFR6dmhqX0lmY0RJR3JJZGNKNjlzVVZnR1M3ZnZkcng3Y21uNjFyai1XcmU0UVJFRC1lV1dxZDlpc2FVRmg5UGVKZ2tCbFZVVnYtdnladVlWdFF2a1NUU05ZR3RtVXl2V2xKZDBPWEFHRm9jdGlfak9aVSIsInFpIjoib0dYaWxLQ2NKRXNFdEE1eG54WUdGQW5UUjNwdkZLUXR5S0F0UGhHaHkybm5ya2VzN1RRaEFxMGhLRWZtU1RzaE1hNFhfd05aMEstX1F0dkdoNDhpeHdTTDVLTEwxZnFsY0k2TF9XUnF0cFQxS21LRERlUHR2bDVCUzFGbjgwSGFwR215cmZRWUU4S09QR2UwUl82S1BOZE1vc3dYQ3Nfd0RYMF92ZzNoNUxRIn0=", "x-sensitive": true }, "stream_key_generation_response": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/stream_keys" } }, "type": "object" } ] }, "stream_key_response_collection": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "properties": { "created": { "$ref": "#/components/schemas/stream_signing_key_created" }, "id": { "$ref": "#/components/schemas/stream_identifier-2" }, "key_id": { "description": "The unique identifier for the signing key.", "type": "string", "example": "e9db990a82666dd571c77f944a5c5c8d" } }, "type": "object" } } }, "type": "object" } ] }, "stream_keys": { "type": "object", "properties": { "created": { "$ref": "#/components/schemas/stream_signing_key_created" }, "id": { "$ref": "#/components/schemas/stream_identifier-2" }, "jwk": { "$ref": "#/components/schemas/stream_jwk" }, "pem": { "$ref": "#/components/schemas/stream_pem" } } }, "stream_label": { "description": "The language label displayed in the native language to users.", "type": "string", "example": "Türkçe", "x-auditable": true }, "stream_language": { "description": "The language tag in BCP 47 format.", "type": "string", "example": "tr", "x-auditable": true }, "stream_language_response_collection": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/stream_captions" } } }, "type": "object" } ] }, "stream_language_response_single": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/stream_captions" } }, "type": "object" } ] }, "stream_listAudioTrackResponse": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "audio": { "description": "Array of audio tracks for the video.", "type": "array", "items": { "$ref": "#/components/schemas/stream_additionalAudio" } } } } }, "type": "object" } ] }, "stream_liveInput": { "description": "The live input ID used to upload a video with Stream Live.", "type": "string", "example": "fc0a8dc887b16759bfd9ad922230a014", "maxLength": 32, "x-auditable": true }, "stream_live_input": { "description": "Details about a live input.", "type": "object", "properties": { "created": { "$ref": "#/components/schemas/stream_live_input_created" }, "deleteRecordingAfterDays": { "$ref": "#/components/schemas/stream_live_input_recording_deletion" }, "enabled": { "$ref": "#/components/schemas/stream_live_input_enabled" }, "keysRotatedAt": { "$ref": "#/components/schemas/stream_live_input_keys_rotated_at" }, "meta": { "$ref": "#/components/schemas/stream_live_input_metadata" }, "modified": { "$ref": "#/components/schemas/stream_live_input_modified" }, "playback": { "$ref": "#/components/schemas/stream_live_input_playback" }, "preferLowLatency": { "$ref": "#/components/schemas/stream_live_input_prefer_low_latency" }, "recording": { "$ref": "#/components/schemas/stream_live_input_recording_settings" }, "rtmps": { "$ref": "#/components/schemas/stream_input_rtmps" }, "rtmpsPlayback": { "$ref": "#/components/schemas/stream_playback_rtmps" }, "srt": { "$ref": "#/components/schemas/stream_input_srt" }, "srtPlayback": { "$ref": "#/components/schemas/stream_playback_srt" }, "status": { "$ref": "#/components/schemas/stream_live_input_status" }, "uid": { "$ref": "#/components/schemas/stream_live_input_identifier" }, "webRTC": { "$ref": "#/components/schemas/stream_input_webrtc" }, "webRTCPlayback": { "$ref": "#/components/schemas/stream_playback_webrtc" } } }, "stream_live_input_created": { "description": "The date and time the live input was created.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z", "x-auditable": true }, "stream_live_input_default_creator": { "description": "Sets the creator ID asssociated with this live input.", "type": "string", "x-auditable": true }, "stream_live_input_enabled": { "description": "Indicates whether the live input is enabled and can accept streams.", "type": "boolean", "example": true, "default": true, "x-auditable": true }, "stream_live_input_identifier": { "description": "A unique identifier for a live input.", "type": "string", "example": "66be4bf738797e01e1fca35a7bdecdcd", "maxLength": 32, "x-auditable": true }, "stream_live_input_keys_rotated_at": { "description": "The date and time the live input keys were last rotated. Omitted for live inputs that have never had their keys rotated.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z", "nullable": true, "x-auditable": true }, "stream_live_input_metadata": { "description": "A user modifiable key-value store used to reference other systems of record for managing live inputs.", "type": "object", "example": { "name": "test stream 1" } }, "stream_live_input_modified": { "description": "The date and time the live input was last modified.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z", "x-auditable": true }, "stream_live_input_object_without_url": { "properties": { "created": { "$ref": "#/components/schemas/stream_live_input_created" }, "deleteRecordingAfterDays": { "$ref": "#/components/schemas/stream_live_input_recording_deletion" }, "enabled": { "$ref": "#/components/schemas/stream_live_input_enabled" }, "meta": { "$ref": "#/components/schemas/stream_live_input_metadata" }, "modified": { "$ref": "#/components/schemas/stream_live_input_modified" }, "uid": { "$ref": "#/components/schemas/stream_live_input_identifier" } } }, "stream_live_input_playback": { "description": "Details for playing a live input's broadcast using the HLS or DASH manifests. URLs reference the live input ID.", "type": "object", "properties": { "dash": { "$ref": "#/components/schemas/stream_playback_dash_url" }, "hls": { "$ref": "#/components/schemas/stream_playback_hls_url" } }, "required": [ "hls", "dash" ] }, "stream_live_input_prefer_low_latency": { "description": "When enabled, the live stream is delivered using Low-Latency HLS (LL-HLS), reducing glass-to-glass latency for viewers at the cost of reduced player compatibility.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "stream_live_input_recording_allowedOrigins": { "description": "Lists the origins allowed to display videos created with this input. Enter allowed origin domains in an array and use `*` for wildcard subdomains. An empty array allows videos to be viewed on any origin.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "example.com" ] }, "stream_live_input_recording_deletion": { "description": "Indicates the number of days after which the live inputs recordings will be deleted. When a stream completes and the recording is ready, the value is used to calculate a scheduled deletion date for that recording. Omit the field to indicate no change, or include with a `null` value to remove an existing scheduled deletion.", "type": "number", "example": 45, "minimum": 30, "x-auditable": true }, "stream_live_input_recording_hideLiveViewerCount": { "description": "Disables reporting the number of live viewers when this property is set to `true`.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "stream_live_input_recording_mode": { "description": "Specifies the recording behavior for the live input. Set this value to `off` to prevent a recording. Set the value to `automatic` to begin a recording and transition to on-demand after Stream Live stops receiving input.", "type": "string", "example": "automatic", "default": "off", "enum": [ "off", "automatic" ], "x-auditable": true }, "stream_live_input_recording_requireSignedURLs": { "description": "Indicates if a video using the live input has the `requireSignedURLs` property set. Also enforces access controls on any video recording of the livestream with the live input.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "stream_live_input_recording_settings": { "description": "Records the input to a Cloudflare Stream video. Behavior depends on the mode. In most cases, the video will initially be viewable as a live video and transition to on-demand after a condition is satisfied.", "type": "object", "properties": { "allowedOrigins": { "$ref": "#/components/schemas/stream_live_input_recording_allowedOrigins" }, "hideLiveViewerCount": { "$ref": "#/components/schemas/stream_live_input_recording_hideLiveViewerCount" }, "mode": { "$ref": "#/components/schemas/stream_live_input_recording_mode" }, "requireSignedURLs": { "$ref": "#/components/schemas/stream_live_input_recording_requireSignedURLs" }, "timeoutSeconds": { "$ref": "#/components/schemas/stream_live_input_recording_timeoutSeconds" } }, "example": { "hideLiveViewerCount": false, "mode": "off", "requireSignedURLs": false, "timeoutSeconds": 0 } }, "stream_live_input_recording_timeoutSeconds": { "description": "Determines the amount of time a live input configured in `automatic` mode should wait before a recording transitions from live to on-demand. `0` is recommended for most use cases and indicates the platform default should be used.", "type": "integer", "default": 0, "x-auditable": true }, "stream_live_input_response_collection": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "liveInputs": { "type": "array", "items": { "$ref": "#/components/schemas/stream_live_input_object_without_url" } }, "range": { "description": "The total number of remaining live inputs based on cursor position.", "type": "integer", "example": 1000 }, "total": { "description": "The total number of live inputs that match the provided filters.", "type": "integer", "example": 35586 } } } }, "type": "object" } ] }, "stream_live_input_response_single": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/stream_live_input" } }, "type": "object" } ] }, "stream_live_input_status": { "description": "The connection status of a live input.", "type": "string", "enum": [ null, "connected", "reconnected", "reconnecting", "client_disconnect", "ttl_exceeded", "failed_to_connect", "failed_to_reconnect", "new_configuration_accepted" ], "nullable": true, "x-auditable": true }, "stream_maxDurationSeconds": { "description": "The maximum duration in seconds for a video upload. Can be set for a video that is not yet uploaded to limit its duration. Uploads that exceed the specified duration will fail during processing. A value of `-1` means the value is unknown.", "type": "integer", "maximum": 36000, "minimum": 1, "x-auditable": true }, "stream_media_metadata": { "description": "A user modifiable key-value store used to reference other systems of record for managing videos.", "type": "object", "example": { "name": "video12345.mp4" } }, "stream_media_state": { "description": "Specifies the processing status for all quality levels for a video.", "type": "string", "example": "inprogress", "enum": [ "pendingupload", "downloading", "queued", "inprogress", "ready", "error", "live-inprogress" ], "x-auditable": true }, "stream_media_status": { "description": "Specifies a detailed status for a video. If the `state` is `inprogress` or `error`, the `step` field returns `encoding` or `manifest`. If the `state` is `inprogress`, `pctComplete` returns a number between 0 and 100 to indicate the approximate percent of completion. If the `state` is `error`, `errorReasonCode` and `errorReasonText` provide additional details.", "properties": { "errorReasonCode": { "$ref": "#/components/schemas/stream_errorReasonCode" }, "errorReasonText": { "$ref": "#/components/schemas/stream_errorReasonText" }, "pctComplete": { "$ref": "#/components/schemas/stream_pctComplete" }, "state": { "$ref": "#/components/schemas/stream_media_state" } } }, "stream_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "stream_modified": { "description": "The date and time the media item was last modified.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z", "x-auditable": true }, "stream_name": { "description": "A short description of the watermark profile.", "type": "string", "example": "Marketing Videos", "default": "", "x-auditable": true }, "stream_notificationUrl": { "description": "The URL where webhooks will be sent.", "type": "string", "format": "uri", "example": "https://example.com", "x-auditable": true }, "stream_oneTimeUploadExpiry": { "description": "The date and time when the video upload URL is no longer valid for direct user uploads.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z", "x-auditable": true }, "stream_opacity": { "description": "The translucency of the image. A value of `0.0` makes the image completely transparent, and `1.0` makes the image completely opaque. Note that if the image is already semi-transparent, setting this to `1.0` will not make the image completely opaque.", "type": "number", "example": 0.75, "default": 1, "maximum": 1, "minimum": 0, "x-auditable": true }, "stream_output": { "properties": { "enabled": { "$ref": "#/components/schemas/stream_output_enabled" }, "streamKey": { "$ref": "#/components/schemas/stream_output_streamKey" }, "uid": { "$ref": "#/components/schemas/stream_output_identifier" }, "url": { "$ref": "#/components/schemas/stream_output_url" } } }, "stream_output_enabled": { "description": "When enabled, live video streamed to the associated live input will be sent to the output URL. When disabled, live video will not be sent to the output URL, even when streaming to the associated live input. Use this to control precisely when you start and stop simulcasting to specific destinations like YouTube and Twitch.", "type": "boolean", "example": true, "default": true, "x-auditable": true }, "stream_output_identifier": { "description": "A unique identifier for the output.", "type": "string", "example": "baea4d9c515887b80289d5c33cf01145", "maxLength": 32, "x-auditable": true }, "stream_output_response_collection": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/stream_output" } } }, "type": "object" } ] }, "stream_output_response_single": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/stream_output" } }, "type": "object" } ] }, "stream_output_streamKey": { "description": "The streamKey used to authenticate against an output's target.", "type": "string", "example": "uzya-f19y-g2g9-a2ee-51j2", "x-sensitive": true }, "stream_output_url": { "description": "The URL an output uses to restream.", "type": "string", "example": "rtmp://a.rtmp.youtube.com/live2", "x-sensitive": true }, "stream_padding": { "description": "The whitespace between the adjacent edges (determined by position) of the video and the image. `0.0` indicates no padding, and `1.0` indicates a fully padded video width or length, as determined by the algorithm.", "type": "number", "example": 0.1, "default": 0.05, "maximum": 1, "minimum": 0, "x-auditable": true }, "stream_pctComplete": { "description": "Indicates the progress as a percentage between 0 and 100.", "type": "string", "example": "45", "x-auditable": true }, "stream_pem": { "description": "The signing key in PEM format.", "type": "string", "example": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFcGdJQkFBS0NBUUVBMFRqd2pPaVpXbUo0M3ZmM1RvNERvWG1YV3RKR05HeVhmaHl0dExhQmdGMStFUVdRCkRLaG9LYm9hS21xakNBc21za3V0YkxVN1BVOGRrUU5ER1p3S3VWczA4elNaNGt4aTR0RWdQUFp5dDdkWEMrbFkKUllveXJBR0Y0QVhoeTMyOWJIQ1AxSWxyQkIvQWtHZ25kTEFndW54WTByUmdjdk96aWF3NktKeEZuYzJVSzBXVQo4YjBwNEtLSEdwMUtMOWRrMFdUOGRWWXFiZVJpSmpDbFVFbWg4eXY5Q2xPVmFTNEt4aVg2eFRRNERadzZEYUpmCklWM1F0Tmd2cG1ieWxOSmFQSG5zc3JodDJHS1A5NjJlS2poUVJsaWd2SFhKTE9uSm9KZkxlSUVIWitpeFdmY1QKRE1IOTJzR3ZvdzFET2p4TGlDTjF6SEsraDdiTG9YVGlMZ2M0a3dJREFRQUJBb0lCQVFEQ0lCclNJMTlteGNkdwoycExVaUdCR0N4T3NhVDVLbGhkYUpESG9ZdzUxbEVuTWNXVGUyY01NTkdqaXdsN1NyOFlQMkxmcERaOFJtNzdMCk5rT2tGMnk3M3l5YUhFeEw5S1FyMys0Um9ubCtqTlp2YnV0QVdxSDVodEE0dER4MUd3NE85OEg4YWlTcGh1eWQKRUliTGRrQm54OGlDZUdxbFBnbHZ6Q1dLV0xVZlhGbXplMkF5UjBzaWMyYXZRLzZyclYwb3pDdGQ1T0Vod093agphaCs3N1dZV1l0bkEraDhXZVZreWcvdG44UTJJOXo5ZVJYdlZxR2sxMDZLcWRtZFdiU2tIZzA4cFRUSGhVM2paCnMvZGNjdEdOMWFFanlUQWY0QzdHT2lrcUd1MGFTaW1aeDFOM2RWQzBobngySjJtdlhNQ0VtZ0g3TjVnZUxWUFAKOWdkQjdBQkJBb0dCQU5sT2hGQVhaTHV6Y0Ftczl1K3AxM05STWRFOHpIK2ZFaFBrbk9zZ21Xb3VqUzkxQTRtZgpuK01oN3d5bTZoVU1DbDk2WUNMNGtPM0RUMmlYWlRqTXZuMHBoVEx1MXNYcGxWNDJuamRnZGd3cFBEM0FnL1Y5ClVvV2hxdVhoa1I3RFpsUGg5Nmk1aEE0M1BvbTVPQm9BektJbEcrT3ZKUkhhZEVveC9jSmZScFd2QW9HQkFQWjUKNnNmWDdESElCNEtBczRmMWRuNGZJUkMweUF2WVdCL1R3UzZHUWVoNFRFbDVuSkQwWk9ZRVdUbVVBK3pPanZTNApuM09tZ2xNQTU5SGd1ZW13QXVRcEtwWFBOcFUvTERJaThtNnpmTUpvL3E5M0NOQlFQZngzZGh4ZVh4OXE2Mzg3Cm84QWxkOE42RGs4TThjRis3SlNaeUVJODJzLzdpdGRseXA2bFdLaGRBb0dCQUtnU0VrUGYxQWxZdjA2OGVFRGwKRzc0VkRuTEdrMlFobzltKzk1N2psOFNJUEtwMzFrU2JNUTU3TUdpWXNIT1czRzc4TjE3VTRVTUR6R2NZc1RFOQpLaGVrQldGZldMMjU2OHp5Y1d4akx1bzQrbDdJaDBkWHBudTBqbms5L1AvT0lWYS9iczBRcnhKUHFBN2RNb2JxCkYxdFJXRURCTmVxWkMxaFhVZTBEdzVRQkFvR0JBSjdBQ2NNcnhKcVBycDZVakkyK1FOS2M5Q3dSZEdPRXRjWFMKR3JQL2owWE83YnZKVTFsZHYvc1N3L0U4NzRZL3lIM0F5QnF5SFhDZXZiRkZZQmt1MzczYThlM0pwK3RhNC9scQozdUVFUkEvbmxscW5mWXJHbEJZZlQzaVlKQVpWVkZiL3I4bWJtRmJVTDVFazBqV0JyWmxNcjFwU1hkRGx3QmhhCkhMWXY0em1WQW9HQkFLQmw0cFNnbkNSTEJMUU9jWjhXQmhRSjAwZDZieFNrTGNpZ0xUNFJvY3RwNTY1SHJPMDAKSVFLdElTaEg1a2s3SVRHdUYvOERXZEN2djBMYnhvZVBJc2NFaStTaXk5WDZwWENPaS8xa2FyYVU5U3BpZ3czago3YjVlUVV0UlovTkIycVJwc3EzMEdCUENqanhudEVmK2lqelhUS0xNRndyUDhBMTlQNzRONGVTMAotLS0tLUVORCBSU0EgUFJJVkFURSBLRVktLS0tLQo=", "x-sensitive": true }, "stream_playback": { "type": "object", "properties": { "dash": { "description": "DASH Media Presentation Description for the video.", "type": "string", "example": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.mpd", "x-auditable": true }, "hls": { "description": "The HLS manifest for the video.", "type": "string", "example": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.m3u8", "x-auditable": true } } }, "stream_playback_dash_url": { "description": "The DASH manifest URL used to play live video, referencing the live input ID.", "type": "string", "example": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/66be4bf738797e01e1fca35a7bdecdcd/manifest/video.mpd", "x-auditable": true }, "stream_playback_hls_url": { "description": "The HLS manifest URL used to play live video, referencing the live input ID.", "type": "string", "example": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/66be4bf738797e01e1fca35a7bdecdcd/manifest/video.m3u8", "x-auditable": true }, "stream_playback_rtmps": { "description": "Details for playback from an live input using RTMPS.", "type": "object", "properties": { "streamKey": { "$ref": "#/components/schemas/stream_playback_rtmps_stream_key" }, "url": { "$ref": "#/components/schemas/stream_playback_rtmps_url" } } }, "stream_playback_rtmps_stream_key": { "description": "The secret key to use for playback via RTMPS.", "type": "string", "example": "2fb3cb9f17e68a2568d6ebed8d5505eak3ceaf8c9b1f395e1b76b79332497cada", "x-sensitive": true }, "stream_playback_rtmps_url": { "description": "The URL used to play live video over RTMPS.", "type": "string", "example": "rtmps://live.cloudflare.com:443/live/", "x-sensitive": true }, "stream_playback_srt": { "description": "Details for playback from an live input using SRT.", "type": "object", "properties": { "passphrase": { "$ref": "#/components/schemas/stream_playback_srt_stream_passphrase" }, "streamId": { "$ref": "#/components/schemas/stream_playback_srt_stream_id" }, "url": { "$ref": "#/components/schemas/stream_playback_srt_url" } } }, "stream_playback_srt_stream_id": { "description": "The identifier of the live input to use for playback via SRT.", "type": "string", "example": "f256e6ea9341d51eea64c9454659e576", "x-auditable": true }, "stream_playback_srt_stream_passphrase": { "description": "The secret key to use for playback via SRT.", "type": "string", "example": "2fb3cb9f17e68a2568d6ebed8d5505eak3ceaf8c9b1f395e1b76b79332497cada", "x-sensitive": true }, "stream_playback_srt_url": { "description": "The URL used to play live video over SRT.", "type": "string", "example": "rtmps://live.cloudflare.com:443/live/", "x-sensitive": true }, "stream_playback_webrtc": { "description": "Details for playback from a live input using WebRTC.", "type": "object", "properties": { "url": { "$ref": "#/components/schemas/stream_playback_webrtc_url" } } }, "stream_playback_webrtc_url": { "description": "The URL used to play live video over WebRTC.", "type": "string", "example": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/b236bde30eb07b9d01318940e5fc3edake34a3efb3896e18f2dc277ce6cc993ad/webRTC/play", "x-sensitive": true }, "stream_position": { "description": "The location of the image. Valid positions are: `upperRight`, `upperLeft`, `lowerLeft`, `lowerRight`, and `center`. Note that `center` ignores the `padding` parameter.", "type": "string", "example": "center", "default": "upperRight", "x-auditable": true }, "stream_preview": { "description": "The video's preview page URI. This field is omitted until encoding is complete.", "type": "string", "format": "uri", "example": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/watch", "x-auditable": true }, "stream_readyToStream": { "description": "Indicates whether the video is playable. The field is empty if the video is not ready for viewing or the live stream is still in progress.", "type": "boolean", "example": true, "x-auditable": true }, "stream_readyToStreamAt": { "description": "Indicates the time at which the video became playable. The field is empty if the video is not ready for viewing or the live stream is still in progress.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z", "x-auditable": true }, "stream_requireSignedURLs": { "description": "Indicates whether the video can be a accessed using the UID. When set to `true`, a signed token must be generated with a signing key to view the video.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "stream_scale": { "description": "The size of the image relative to the overall size of the video. This parameter will adapt to horizontal and vertical videos automatically. `0.0` indicates no scaling (use the size of the image as-is), and `1.0 `fills the entire video.", "type": "number", "example": 0.1, "default": 0.15, "maximum": 1, "minimum": 0, "x-auditable": true }, "stream_scheduledDeletion": { "description": "Indicates the date and time at which the video will be deleted. Omit the field to indicate no change, or include with a `null` value to remove an existing scheduled deletion. If specified, must be at least 30 days from upload time.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z", "x-auditable": true }, "stream_search": { "description": "Provides a partial word match of the `name` key in the `meta` field. Slow for medium to large video libraries. May be unavailable for very large libraries.", "type": "string", "example": "puppy.mp4", "x-auditable": true }, "stream_signed_token_request": { "type": "object", "properties": { "accessRules": { "description": "The optional list of access rule constraints on the token. Access can be blocked or allowed based on an IP, IP range, or by country. Access rules are evaluated from first to last. If a rule matches, the associated action is applied and no further rules are evaluated.", "type": "array", "items": { "$ref": "#/components/schemas/stream_accessRules" }, "example": [ { "action": "block", "country": [ "US", "MX" ], "type": "ip.geoip.country" }, { "action": "allow", "ip": [ "93.184.216.0/24", "2400:cb00::/32" ], "type": "ip.src" }, { "action": "block", "type": "any" } ] }, "downloadable": { "description": "The optional boolean value that enables using signed tokens to access MP4 download links for a video.", "type": "boolean", "default": false, "x-auditable": true }, "exp": { "description": "The optional unix epoch timestamp that specficies the time after a token is not accepted. The maximum time specification is 24 hours from issuing time. If this field is not set, the default is one hour after issuing.", "type": "integer" }, "flags": { "description": "Optional flags for the signed token.", "type": "object", "properties": { "original": { "description": "Whether to return the original video without transformations.", "type": "boolean", "default": false } } }, "id": { "description": "The optional ID of a Stream signing key. If present, the `pem` field is also required.", "type": "string", "example": "ab0d4ef71g4425f8dcba9041231813000", "x-auditable": true }, "nbf": { "description": "The optional unix epoch timestamp that specifies the time before a the token is not accepted. If this field is not set, the default is one hour before issuing.", "type": "integer", "x-auditable": true }, "pem": { "description": "The optional base64 encoded private key in PEM format associated with a Stream signing key. If present, the `id` field is also required.", "type": "string", "example": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFcEFJQkFBS0NBUUVBc284dnBvOFpEWXRkOUgzbWlPaW1qYXAzVXlVM0oyZ3kwTUYvN1R4blJuRnkwRHpDCkxqUk9naFZsQ0hPQmxsd3NVaE9GU0lyYnN4K05tUTdBeS90TFpXSGxuVGF3UWJ5WGZGOStJeDhVSnNlSHBGV1oKNVF5Z1JYd2liSjh1MVVsZ2xlcmZHMkpueldjVXpZTzEySktZN3doSkw1ajROMWgxZFJNUXQ5Q1pkZFlCQWRzOQpCdk02cjRFMDcxQkhQekhWeDMrUTI1VWtubGdUNXIwS3FiM1E1Y0dlTlBXY1JreW1ybkJEWWR0OXR4eFFMb1dPCllzNXdsMnVYWFVYL0VGcDMwajU0Nmp6czllWExLYlNDbjJjTDZFVE96Y2x3aG9DRGx2a2VQT05rUE9LMDVKNUMKTm1TdFdhMG9hV1VGRzM0MFl3cVVrWGt4OU9tNndXd1JldU1uU1FJREFRQUJBb0lCQUFJOHo1ck5kOEdtOGJBMgo1S3pxQjI1R2lOVENwbUNJeW53NXRJWHZTQmNHcEdydUcvdlN2WG9kVlFVSVY0TWdHQkVXUEFrVzdsNWVBcHI4CnA1ZFd5SkRXYTNkdklFSE9vSEpYU3dBYksxZzZEMTNVa2NkZ1EyRGpoNVhuWDhHZCtBY2c2SmRTQWgxOWtYSHEKMk54RUtBVDB6Ri83a1g2MkRkREFBcWxmQkpGSXJodVIvZUdEVWh4L2piTTRhQ2JCcFdiM0pnRE9OYm5tS1ZoMwpxS2ZwZmRZZENZU1lzWUxrNTlxRDF2VFNwUVFUQ0VadW9VKzNzRVNhdkJzaUs1bU0vTzY5ZkRMRXNURG1MeTVQCmhEK3BMQXI0SlhNNjFwRGVBS0l3cUVqWWJybXlDRHRXTUdJNnZzZ0E1eXQzUUJaME9vV2w5QUkwdWxoZ3p4dXQKZ2ZFNTRRRUNnWUVBN0F3a0lhVEEzYmQ4Nk9jSVZnNFlrWGk1cm5aNDdsM1k4V24zcjIzUmVISXhLdkllRUtSbgp5bUlFNDFtRVBBSmlGWFpLK1VPTXdkeS9EcnFJUithT1JiT2NiV01jWUg2QzgvbG1wdVJFaXE3SW1Ub3VWcnA4CnlnUkprMWprVDA4cTIvNmg4eTBEdjJqMitsaHFXNzRNOUt0cmwxcTRlWmZRUFREL01tR1NnTWtDZ1lFQXdhY04KaSttN1p6dnJtL3NuekF2VlZ5SEtwZHVUUjNERk1naC9maC9tZ0ZHZ1RwZWtUOVV5b3FleGNYQXdwMVlhL01iQQoyNTVJVDZRbXZZTm5yNXp6Wmxic2tMV0hsYllvbWhmWnVXTHhXR3hRaEFORWdaMFVVdUVTRGMvbWx2UXZHbEtSCkZoaGhBUWlVSmdDamhPaHk1SlBiNGFldGRKd0UxK09lVWRFaE1vRUNnWUVBNG8yZ25CM1o4ck5xa3NzemlBek4KYmNuMlJVbDJOaW9pejBwS3JMaDFaT29NNE5BekpQdjJsaHRQMzdtS0htS1hLMHczRjFqTEgwSTBxZmxFVmVZbQpSU1huakdHazJjUnpBYUVzOGgrQzNheDE0Z01pZUtGU3BqNUpNOEFNbVVZOXQ1cUVhN2FYc3o0V1ZoOUlMYmVTCkRiNzlhKzVwd21LQVBrcnBsTHhyZFdrQ2dZQlNNSHVBWVdBbmJYZ1BDS2FZWklGVWJNUWNacmY0ZnpWQ2lmYksKYWZHampvRlNPZXdEOGdGK3BWdWJRTGwxbkFieU44ek1xVDRaaHhybUhpcFlqMjJDaHV2NmN3RXJtbGRiSnpwQwpBMnRaVXdkTk1ESFlMUG5lUHlZeGRJWnlsUXFVeW14SGkydElUQUxNcWtLOGV3ZWdXZHpkeGhQSlJScU5JazhrCmZIVHhnUUtCZ1FEUFc2UXIxY3F3QjNUdnVWdWR4WGRqUTdIcDFodXhrNEVWaEFJZllKNFhSTW1NUE5YS28wdHUKdUt6LzE0QW14R0dvSWJxYVc1bDMzeFNteUxhem84clNUN0tSTjVKME9JSHcrZkR5SFgxdHpVSjZCTldDcEFTcwpjbWdNK0htSzVON0w2bkNaZFJQY2IwU1hGaVRQUGhCUG1PVWFDUnpER0ZMK2JYM1VwajJKbWc9PQotLS0tLUVORCBSU0EgUFJJVkFURSBLRVktLS0tLQo=", "x-sensitive": true } } }, "stream_signed_token_response": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "token": { "description": "The signed token used with the signed URLs feature.", "type": "string", "example": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImU5ZGI5OTBhODI2NjZkZDU3MWM3N2Y5NDRhNWM1YzhkIn0.eyJzdWIiOiJlYTk1MTMyYzE1NzMyNDEyZDIyYzE0NzZmYTgzZjI3YSIsImtpZCI6ImU5ZGI5OTBhODI2NjZkZDU3MWM3N2Y5NDRhNWM1YzhkIiwiZXhwIjoiMTUzNzQ2MDM2NSIsIm5iZiI6IjE1Mzc0NTMxNjUifQ.OZhqOARADn1iubK6GKcn25hN3nU-hCFF5q9w2C4yup0C4diG7aMIowiRpP-eDod8dbAJubsiFuTKrqPcmyCKWYsiv0TQueukqbQlF7HCO1TV-oF6El5-7ldJ46eD-ZQ0XgcIYEKrQOYFF8iDQbqPm3REWd6BnjKZdeVrLzuRaiSnZ9qqFpGu5dfxIY9-nZKDubJHqCr3Imtb211VIG_b9MdtO92JjvkDS-rxT_pkEfTZSafl1OU-98A7KBGtPSJHz2dHORIrUiTA6on4eIXTj9aFhGiir4rSn-rn0OjPRTtJMWIDMoQyE_fwrSYzB7MPuzL2t82BWaEbHZTfixBm5A", "x-sensitive": true } } } }, "type": "object" } ] }, "stream_signing_key_created": { "description": "The date and time a signing key was created.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z", "x-auditable": true }, "stream_size": { "description": "The size of the media item in bytes.", "type": "number", "example": 4190963, "x-auditable": true }, "stream_start": { "description": "Lists videos created after the specified date.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z" }, "stream_start_time_seconds": { "description": "Specifies the start time for the video clip in seconds.", "type": "integer", "x-auditable": true }, "stream_storage_use_response": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "creator": { "$ref": "#/components/schemas/stream_creator" }, "totalStorageMinutes": { "description": "The total minutes of video content stored in the account. May contain decimal values.", "type": "number", "format": "float" }, "totalStorageMinutesLimit": { "description": "The storage capacity alloted for the account.", "type": "integer" }, "videoCount": { "description": "The total count of videos associated with the account.", "type": "integer" } } } }, "type": "object" } ] }, "stream_thumbnailTimestampPct": { "description": "The timestamp for a thumbnail image calculated as a percentage value of the video's duration. To convert from a second-wise timestamp to a percentage, divide the desired timestamp by the total duration of the video. If this value is not set, the default thumbnail image is taken from 0s of the video.", "type": "number", "example": 0.529241, "default": 0, "maximum": 1, "minimum": 0, "x-auditable": true }, "stream_thumbnail_url": { "description": "The media item's thumbnail URI. This field is omitted until encoding is complete.", "type": "string", "format": "uri", "example": "https://customer-m033z5x00ks6nunl.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/thumbnails/thumbnail.jpg", "x-auditable": true }, "stream_tus_resumable": { "description": "Specifies the TUS protocol version. This value must be included in every upload request.\nNotes: The only supported version of TUS protocol is 1.0.0.", "type": "string", "example": "1.0.0", "enum": [ "1.0.0" ], "x-auditable": true }, "stream_type": { "description": "Specifies whether the video is `vod` or `live`.", "type": "string", "example": "live", "x-auditable": true }, "stream_update_input_request": { "properties": { "defaultCreator": { "$ref": "#/components/schemas/stream_live_input_default_creator" }, "deleteRecordingAfterDays": { "$ref": "#/components/schemas/stream_live_input_recording_deletion" }, "enabled": { "$ref": "#/components/schemas/stream_live_input_enabled" }, "meta": { "$ref": "#/components/schemas/stream_live_input_metadata" }, "preferLowLatency": { "$ref": "#/components/schemas/stream_live_input_prefer_low_latency" }, "recording": { "$ref": "#/components/schemas/stream_live_input_recording_settings" } } }, "stream_update_output_request": { "properties": { "enabled": { "$ref": "#/components/schemas/stream_output_enabled" } }, "required": [ "enabled" ] }, "stream_upload_length": { "description": "Indicates the size of the entire upload in bytes. The value must be a non-negative integer.", "type": "integer", "minimum": 0, "x-auditable": true }, "stream_upload_metadata": { "description": "Comma-separated key-value pairs following the TUS protocol specification. Values are Base-64 encoded.\nSupported keys: `name`, `requiresignedurls`, `allowedorigins`, `thumbnailtimestamppct`, `watermark`, `scheduleddeletion`, `maxdurationseconds`.", "type": "string", "example": "name aGVsbG8gd29ybGQ=, requiresignedurls, allowedorigins ZXhhbXBsZS5jb20sdGVzdC5jb20=", "x-auditable": true }, "stream_uploaded": { "description": "The date and time the media item was uploaded.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z", "x-auditable": true }, "stream_videoClipStandard": { "type": "object", "properties": { "allowedOrigins": { "$ref": "#/components/schemas/stream_allowedOrigins" }, "clippedFromVideoUID": { "$ref": "#/components/schemas/stream_clipped_from_video_uid" }, "creator": { "$ref": "#/components/schemas/stream_creator" }, "endTimeSeconds": { "$ref": "#/components/schemas/stream_end_time_seconds" }, "input": { "description": "A video's URL. Preferred over 'url'.", "type": "string", "format": "uri", "example": "https://example.com/myvideo.mp4" }, "meta": { "$ref": "#/components/schemas/stream_media_metadata" }, "name": { "description": "A name for the video.", "type": "string", "example": "myvideo.mp4" }, "requireSignedURLs": { "$ref": "#/components/schemas/stream_requireSignedURLs" }, "scheduledDeletion": { "$ref": "#/components/schemas/stream_scheduledDeletion" }, "startTimeSeconds": { "$ref": "#/components/schemas/stream_start_time_seconds" }, "thumbnailTimestampPct": { "$ref": "#/components/schemas/stream_thumbnailTimestampPct" }, "url": { "description": "A video's URL (legacy field, use 'input' instead).", "type": "string", "format": "uri", "example": "https://example.com/myvideo.mp4" }, "watermark": { "$ref": "#/components/schemas/stream_watermarkAtUpload" } }, "required": [ "clippedFromVideoUID", "startTimeSeconds", "endTimeSeconds" ] }, "stream_video_copy_request": { "description": "Copy upload request. Provide `input` (preferred) or `url` (deprecated).", "type": "object", "properties": { "allowedOrigins": { "$ref": "#/components/schemas/stream_allowedOrigins" }, "creator": { "$ref": "#/components/schemas/stream_creator" }, "input": { "description": "A video's URL. The server must be publicly routable and support `HTTP HEAD` requests and `HTTP GET` range requests. The server should respond to `HTTP HEAD` requests with a `content-range` header that includes the size of the file. This is the preferred field over `url`.", "type": "string", "format": "uri", "example": "https://example.com/myvideo.mp4" }, "meta": { "$ref": "#/components/schemas/stream_media_metadata" }, "name": { "description": "A video's name. Used for legacy compatibility.", "type": "string", "example": "myvideo.mp4" }, "requireSignedURLs": { "$ref": "#/components/schemas/stream_requireSignedURLs" }, "scheduledDeletion": { "$ref": "#/components/schemas/stream_scheduledDeletion" }, "thumbnailTimestampPct": { "$ref": "#/components/schemas/stream_thumbnailTimestampPct" }, "url": { "description": "A video's URL. The server must be publicly routable and support `HTTP HEAD` requests and `HTTP GET` range requests. The server should respond to `HTTP HEAD` requests with a `content-range` header that includes the size of the file. This field is deprecated in favor of `input`.", "type": "string", "format": "uri", "example": "https://example.com/myvideo.mp4" }, "watermark": { "$ref": "#/components/schemas/stream_watermark_at_upload" } }, "anyOf": [ { "required": [ "input" ], "type": "object" }, { "required": [ "url" ], "type": "object" } ] }, "stream_video_name": { "description": "Provides a fast, exact string match on the `name` key in the `meta` field.", "type": "string", "example": "puppy.mp4", "x-auditable": true }, "stream_video_response_collection": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/stream_videos" } } }, "type": "object" }, { "properties": { "range": { "description": "The total number of remaining videos based on cursor position.", "type": "integer", "example": 1000 }, "total": { "description": "The total number of videos that match the provided filters.", "type": "integer", "example": 35586 } }, "type": "object" } ] }, "stream_video_response_single": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/stream_videos" } }, "type": "object" } ] }, "stream_video_update": { "type": "object", "properties": { "allowedOrigins": { "$ref": "#/components/schemas/stream_allowedOrigins" }, "creator": { "$ref": "#/components/schemas/stream_creator" }, "maxDurationSeconds": { "$ref": "#/components/schemas/stream_maxDurationSeconds" }, "meta": { "$ref": "#/components/schemas/stream_media_metadata" }, "publicDetails": { "description": "Public details for the video including title, share link, channel link, and logo.", "type": "object", "properties": { "channel_link": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "share_link": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true } } }, "requireSignedURLs": { "$ref": "#/components/schemas/stream_requireSignedURLs" }, "scheduledDeletion": { "$ref": "#/components/schemas/stream_scheduledDeletion" }, "thumbnailTimestampPct": { "$ref": "#/components/schemas/stream_thumbnailTimestampPct" }, "uid": { "description": "The unique identifier for the video. Can be used to verify the video being updated.", "type": "string", "example": "ea95132c15732412d22c1476fa83f27a" }, "uploadExpiry": { "$ref": "#/components/schemas/stream_oneTimeUploadExpiry" } } }, "stream_videos": { "type": "object", "properties": { "allowedOrigins": { "$ref": "#/components/schemas/stream_allowedOrigins" }, "clippedFrom": { "description": "The unique identifier of the source video this video was clipped from.", "type": "string", "example": "ea95132c15732412d22c1476fa83f27a" }, "created": { "$ref": "#/components/schemas/stream_created" }, "creator": { "$ref": "#/components/schemas/stream_creator" }, "duration": { "$ref": "#/components/schemas/stream_duration" }, "input": { "$ref": "#/components/schemas/stream_input" }, "liveInput": { "$ref": "#/components/schemas/stream_liveInput" }, "maxDurationSeconds": { "$ref": "#/components/schemas/stream_maxDurationSeconds" }, "maxSizeBytes": { "description": "The maximum size in bytes for the video upload.", "type": "integer", "format": "int64" }, "meta": { "$ref": "#/components/schemas/stream_media_metadata" }, "modified": { "$ref": "#/components/schemas/stream_modified" }, "playback": { "$ref": "#/components/schemas/stream_playback" }, "preview": { "$ref": "#/components/schemas/stream_preview" }, "publicDetails": { "description": "Public details for the video including title, share link, channel link, and logo.", "type": "object", "properties": { "channel_link": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "media_id": { "type": "integer" }, "share_link": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true } } }, "readyToStream": { "$ref": "#/components/schemas/stream_readyToStream" }, "readyToStreamAt": { "$ref": "#/components/schemas/stream_readyToStreamAt" }, "requireSignedURLs": { "$ref": "#/components/schemas/stream_requireSignedURLs" }, "scheduledDeletion": { "$ref": "#/components/schemas/stream_scheduledDeletion" }, "size": { "$ref": "#/components/schemas/stream_size" }, "status": { "$ref": "#/components/schemas/stream_media_status" }, "thumbnail": { "$ref": "#/components/schemas/stream_thumbnail_url" }, "thumbnailTimestampPct": { "$ref": "#/components/schemas/stream_thumbnailTimestampPct" }, "uid": { "$ref": "#/components/schemas/stream_identifier" }, "uploadExpiry": { "$ref": "#/components/schemas/stream_oneTimeUploadExpiry" }, "uploaded": { "$ref": "#/components/schemas/stream_uploaded" }, "watermark": { "$ref": "#/components/schemas/stream_watermarks" } } }, "stream_watermarkAtUpload": { "type": "object", "properties": { "uid": { "description": "The unique identifier for the watermark profile.", "type": "string", "example": "ea95132c15732412d22c1476fa83f27a", "maxLength": 32, "x-auditable": true } } }, "stream_watermark_at_upload": { "type": "object", "properties": { "uid": { "description": "The unique identifier for the watermark profile.", "type": "string", "example": "ea95132c15732412d22c1476fa83f27a", "maxLength": 32, "x-auditable": true } } }, "stream_watermark_basic_upload": { "type": "object", "properties": { "file": { "description": "The image file to upload.", "type": "string", "example": "@/Users/rchen/Downloads/watermark.png", "x-auditable": true }, "name": { "$ref": "#/components/schemas/stream_name" }, "opacity": { "$ref": "#/components/schemas/stream_opacity" }, "padding": { "$ref": "#/components/schemas/stream_padding" }, "position": { "$ref": "#/components/schemas/stream_position" }, "scale": { "$ref": "#/components/schemas/stream_scale" } }, "required": [ "file" ] }, "stream_watermark_created": { "description": "The date and a time a watermark profile was created.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z", "x-auditable": true }, "stream_watermark_identifier": { "description": "The unique identifier for a watermark profile.", "type": "string", "example": "ea95132c15732412d22c1476fa83f27a", "maxLength": 32, "x-auditable": true }, "stream_watermark_response_collection": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/stream_watermarks" } } }, "type": "object" } ] }, "stream_watermark_response_single": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/stream_watermarks" } }, "type": "object" } ] }, "stream_watermark_size": { "description": "The size of the image in bytes.", "type": "number", "example": 29472, "x-auditable": true }, "stream_watermarks": { "type": "object", "properties": { "created": { "$ref": "#/components/schemas/stream_watermark_created" }, "downloadedFrom": { "$ref": "#/components/schemas/stream_downloadedFrom" }, "height": { "$ref": "#/components/schemas/stream_height" }, "name": { "$ref": "#/components/schemas/stream_name" }, "opacity": { "$ref": "#/components/schemas/stream_opacity" }, "padding": { "$ref": "#/components/schemas/stream_padding" }, "position": { "$ref": "#/components/schemas/stream_position" }, "scale": { "$ref": "#/components/schemas/stream_scale" }, "size": { "$ref": "#/components/schemas/stream_watermark_size" }, "uid": { "$ref": "#/components/schemas/stream_watermark_identifier" }, "width": { "$ref": "#/components/schemas/stream_width" } } }, "stream_webhook_request": { "type": "object", "properties": { "notificationUrl": { "$ref": "#/components/schemas/stream_notificationUrl" }, "notification_url": { "description": "The URL where webhooks will be sent.", "type": "string", "format": "uri", "example": "https://example.com", "x-auditable": true } }, "anyOf": [ { "required": [ "notificationUrl" ], "type": "object" }, { "required": [ "notification_url" ], "type": "object" } ] }, "stream_webhook_response_single": { "allOf": [ { "$ref": "#/components/schemas/stream_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "modified": { "description": "The date and time the webhook was last modified.", "type": "string", "format": "date-time", "example": "2014-01-02T02:20:00Z" }, "notificationUrl": { "description": "The URL where webhooks will be sent.", "type": "string", "format": "uri", "example": "https://example.com" }, "notification_url": { "description": "The URL where webhooks will be sent.", "type": "string", "format": "uri", "example": "https://example.com" }, "secret": { "description": "The secret used to verify webhook signatures.", "type": "string", "x-sensitive": true } } } }, "type": "object" } ] }, "stream_width": { "description": "The width of the image in pixels.", "type": "integer", "x-auditable": true }, "teams-devices_access_serial_number_list_input_request": { "type": "object", "properties": { "id": { "description": "UUID of Access List.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "x-auditable": true } }, "required": [ "id" ], "title": "Serial Number" }, "teams-devices_account": { "type": "object", "properties": { "account_type": { "type": "string", "deprecated": true }, "id": { "type": "string", "deprecated": true }, "name": { "description": "The name of the enrolled account.", "type": "string", "example": "Company", "x-auditable": true } } }, "teams-devices_allow_mode_switch": { "description": "Whether to allow the user to switch WARP between modes.", "type": "boolean", "example": true, "default": false }, "teams-devices_allow_updates": { "description": "Whether to receive update notifications when a new version of the client is available.", "type": "boolean", "example": true, "default": false }, "teams-devices_allowed_to_leave": { "description": "Whether to allow devices to leave the organization.", "type": "boolean", "example": true, "default": true }, "teams-devices_antivirus_input_request": { "type": "object", "properties": { "update_window_days": { "description": "Number of days that the antivirus should be updated within.", "type": "number", "example": 7 } }, "title": "Antivirus" }, "teams-devices_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "type": "object" }, "nullable": true }, "result_info": { "$ref": "#/components/schemas/teams-devices_result_info" } }, "type": "object" } ] }, "teams-devices_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/teams-devices_messages" }, "messages": { "$ref": "#/components/schemas/teams-devices_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": { "type": "object" }, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "teams-devices_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/teams-devices_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/teams-devices_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "teams-devices_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-common" }, { "properties": { "result": { "type": "object", "anyOf": [ { "type": "object" }, { "type": "string" } ], "nullable": true } }, "type": "object" } ] }, "teams-devices_application_input_request": { "type": "object", "properties": { "operating_system": { "description": "Operating system.", "type": "string", "example": "mac", "enum": [ "windows", "linux", "mac" ], "x-auditable": true }, "path": { "description": "Path for the application.", "type": "string", "example": "/bin/cat", "x-auditable": true }, "sha256": { "description": "SHA-256.", "type": "string", "example": "b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c", "x-auditable": true }, "thumbprint": { "description": "Signing certificate thumbprint.", "type": "string", "example": "0aabab210bdb998e9cf45da2c9ce352977ab531c681b74cf1e487be1bbe9fe6e", "x-auditable": true } }, "required": [ "path", "operating_system" ], "title": "Application" }, "teams-devices_auto_connect": { "description": "The amount of time in seconds to reconnect after having been disabled.", "type": "number", "example": 0, "default": 0 }, "teams-devices_captive_portal": { "description": "Turn on the captive portal after the specified amount of time.", "type": "number", "example": 180, "default": 180 }, "teams-devices_carbonblack_input_request": { "type": "object", "properties": { "operating_system": { "description": "Operating system.", "type": "string", "example": "mac", "enum": [ "windows", "linux", "mac" ], "x-auditable": true }, "path": { "description": "File path.", "type": "string", "example": "/bin/cat", "x-auditable": true }, "sha256": { "description": "SHA-256.", "type": "string", "example": "b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c", "x-auditable": true }, "thumbprint": { "description": "Signing certificate thumbprint.", "type": "string", "example": "0aabab210bdb998e9cf45da2c9ce352977ab531c681b74cf1e487be1bbe9fe6e", "x-auditable": true } }, "required": [ "path", "operating_system" ], "title": "Carbonblack" }, "teams-devices_checkDisks": { "description": "List of volume names to be checked for encryption.", "type": "array", "items": { "type": "string" }, "example": [ "C", "D", "G" ] }, "teams-devices_client_certificate_input_request": { "type": "object", "properties": { "certificate_id": { "description": "UUID of Cloudflare managed certificate.", "type": "string", "example": "b14ddcc4-bcd2-4df4-bd4f-eb27d5a50c30", "maxLength": 36 }, "cn": { "description": "Common Name that is protected by the certificate.", "type": "string", "example": "example.com" } }, "required": [ "certificate_id", "cn" ], "title": "Client Certificate" }, "teams-devices_client_certificate_v2_input_request": { "type": "object", "properties": { "certificate_id": { "description": "UUID of Cloudflare managed certificate.", "type": "string", "example": "b14ddcc4-bcd2-4df4-bd4f-eb27d5a50c30", "maxLength": 36 }, "check_private_key": { "description": "Confirm the certificate was not imported from another device. We recommend keeping this enabled unless the certificate was deployed without a private key.", "type": "boolean", "example": true }, "cn": { "description": "Certificate Common Name. This may include one or more variables in the ${ } notation. Only ${serial_number} and ${hostname} are valid variables.", "type": "string", "example": "${hostname}.com.${serial_number}" }, "extended_key_usage": { "description": "List of values indicating purposes for which the certificate public key can be used.", "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_extended_key_usage_enum" }, "example": [ "clientAuth", "emailProtection" ] }, "locations": { "type": "object", "properties": { "paths": { "$ref": "#/components/schemas/teams-devices_paths" }, "trust_stores": { "$ref": "#/components/schemas/teams-devices_trust_stores" } } }, "operating_system": { "description": "Operating System.", "type": "string", "example": "windows", "enum": [ "windows", "mac", "linux" ] }, "subject_alternative_names": { "description": "List of certificate Subject Alternative Names.", "type": "array", "items": { "type": "string" }, "example": [ "example.com", "sample.com" ] } }, "required": [ "certificate_id", "check_private_key", "operating_system" ], "title": "Client Certificate V2" }, "teams-devices_client_version": { "type": "object", "properties": { "package_size": { "description": "Size of the package in bytes.", "type": "integer", "format": "int64", "example": 123125760 }, "package_url": { "description": "URL to download the package.", "type": "string", "example": "https://downloads.cloudflareclient.com/v1/download/windows/version/2024.11.309.0" }, "release_date": { "description": "The release date timestamp.", "type": "string", "example": "2024-11-18T21:57:58.478Z" }, "release_notes": { "description": "Release notes for this version.", "type": "string", "example": "This release contains minor fixes and improvements." }, "version": { "description": "The client version string.", "type": "string", "example": "2024.11.309.0" } }, "required": [ "version", "release_date" ] }, "teams-devices_components-schemas-name": { "description": "The name of the device posture integration.", "type": "string", "example": "My Workspace One Integration", "x-auditable": true }, "teams-devices_components-schemas-response_collection": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_device-managed-networks" } } }, "type": "object" } ] }, "teams-devices_components-schemas-single_response": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/teams-devices_device-managed-networks" } }, "type": "object" } ] }, "teams-devices_components-schemas-type": { "description": "The type of device managed network.", "type": "string", "example": "tls", "enum": [ "tls" ], "x-auditable": true }, "teams-devices_components-schemas-uuid": { "description": "UUID.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "readOnly": true, "x-auditable": true }, "teams-devices_config_request": { "description": "The configuration object containing third-party integration information.", "type": "object", "example": { "api_url": "https://as123.awmdm.com/API", "auth_url": "https://na.uemauth.workspaceone.com/connect/token", "client_id": "example client id", "client_secret": "example client secret" }, "oneOf": [ { "$ref": "#/components/schemas/teams-devices_workspace_one_config_request" }, { "$ref": "#/components/schemas/teams-devices_crowdstrike_config_request" }, { "$ref": "#/components/schemas/teams-devices_uptycs_config_request" }, { "$ref": "#/components/schemas/teams-devices_intune_config_request" }, { "$ref": "#/components/schemas/teams-devices_kolide_config_request" }, { "$ref": "#/components/schemas/teams-devices_tanium_config_request" }, { "$ref": "#/components/schemas/teams-devices_sentinelone_s2s_config_request" }, { "$ref": "#/components/schemas/teams-devices_custom_s2s_config_request" } ] }, "teams-devices_config_response": { "description": "The configuration object containing third-party integration information.", "type": "object", "example": { "api_url": "https://as123.awmdm.com/API", "auth_url": "https://na.uemauth.workspaceone.com/connect/token", "client_id": "example client id" }, "oneOf": [ { "$ref": "#/components/schemas/teams-devices_workspace_one_config_response" } ] }, "teams-devices_created": { "description": "When the device was created.", "type": "string", "format": "date-time", "example": "2017-06-14T00:00:00Z", "x-auditable": true }, "teams-devices_crowdstrike_config_request": { "type": "object", "properties": { "api_url": { "description": "The Crowdstrike API URL.", "type": "string", "example": "https://api.us-2.crowdstrike.com", "x-auditable": true }, "client_id": { "description": "The Crowdstrike client ID.", "type": "string", "example": "example client id" }, "client_secret": { "description": "The Crowdstrike client secret.", "type": "string", "example": "example client secret", "x-sensitive": true }, "customer_id": { "description": "The Crowdstrike customer ID.", "type": "string", "example": "example customer id", "x-auditable": true } }, "required": [ "api_url", "customer_id", "client_id", "client_secret" ], "title": "Crowdstrike Config" }, "teams-devices_crowdstrike_input_request": { "type": "object", "properties": { "connection_id": { "description": "Posture Integration ID.", "type": "string", "example": "bc7cbfbb-600a-42e4-8a23-45b5e85f804f", "x-auditable": true }, "last_seen": { "description": "For more details on last seen, please refer to the Crowdstrike documentation.", "type": "string", "example": "15d3h20m4s", "x-auditable": true }, "operator": { "description": "Operator.", "type": "string", "example": ">", "enum": [ "<", "<=", ">", ">=", "==" ], "x-auditable": true }, "os": { "description": "Os Version.", "type": "string", "example": "13.3.0", "x-auditable": true }, "overall": { "description": "Overall.", "type": "string", "example": 90, "x-auditable": true }, "sensor_config": { "description": "SensorConfig.", "type": "string", "example": 90, "x-auditable": true }, "state": { "description": "For more details on state, please refer to the Crowdstrike documentation.", "type": "string", "example": "online", "enum": [ "online", "offline", "unknown" ], "x-auditable": true }, "version": { "description": "Version.", "type": "string", "example": "13.3.0", "x-auditable": true }, "versionOperator": { "description": "Version Operator.", "type": "string", "example": ">", "enum": [ "<", "<=", ">", ">=", "==" ], "x-auditable": true } }, "required": [ "connection_id" ], "title": "Crowdstrike S2S Input" }, "teams-devices_cursor_result_info": { "description": "V4 public API Pagination/Cursor info.", "type": "object", "properties": { "count": { "description": "Number of records in the response.", "type": "integer" }, "cursor": { "description": "Opaque token to request the next set of records.", "type": "string" }, "per_page": { "description": "The limit for the number of records in the response.", "type": "integer" }, "total_count": { "description": "Total number of records available.", "type": "integer", "nullable": true } }, "example": { "count": 1, "cursor": "ais86dftf.asdf7ba8", "per_page": 10, "total_count": null }, "required": [ "per_page", "count", "cursor" ] }, "teams-devices_custom_s2s_config_request": { "type": "object", "properties": { "access_client_id": { "description": "This id will be passed in the `CF-Access-Client-ID` header when hitting the `api_url`.", "type": "string", "example": "88bf3b6d86161464f6509f7219099e57.access" }, "access_client_secret": { "description": "This secret will be passed in the `CF-Access-Client-Secret` header when hitting the `api_url`.", "type": "string", "example": "bdd31cbc4dec990953e39163fbbb194c93313ca9f0a6e420346af9d326b1d2a5", "x-sensitive": true }, "api_url": { "description": "The Custom Device Posture Integration API URL.", "type": "string", "example": "https://example.custom-s2s.com", "x-auditable": true } }, "required": [ "api_url", "access_client_id", "access_client_secret" ], "title": "Custom Device Posture Integration Config" }, "teams-devices_custom_s2s_input_request": { "type": "object", "properties": { "connection_id": { "description": "Posture Integration ID.", "type": "string", "example": "bc7cbfbb-600a-42e4-8a23-45b5e85f804f" }, "operator": { "description": "Operator.", "type": "string", "example": ">", "enum": [ "<", "<=", ">", ">=", "==" ] }, "score": { "description": "A value between 0-100 assigned to devices set by the 3rd party posture provider.", "type": "number", "example": 100 } }, "required": [ "connection_id", "score", "operator" ], "title": "Custom Device Posture Integration Input" }, "teams-devices_default": { "description": "Whether the policy is the default policy for an account.", "type": "boolean", "example": false }, "teams-devices_default_device_settings_policy": { "type": "object", "properties": { "allow_mode_switch": { "$ref": "#/components/schemas/teams-devices_allow_mode_switch" }, "allow_updates": { "$ref": "#/components/schemas/teams-devices_allow_updates" }, "allowed_to_leave": { "$ref": "#/components/schemas/teams-devices_allowed_to_leave" }, "auto_connect": { "$ref": "#/components/schemas/teams-devices_auto_connect" }, "captive_portal": { "$ref": "#/components/schemas/teams-devices_captive_portal" }, "default": { "description": "Whether the policy will be applied to matching devices.", "type": "boolean", "example": true }, "disable_auto_fallback": { "$ref": "#/components/schemas/teams-devices_disable_auto_fallback" }, "dns_search_suffixes": { "$ref": "#/components/schemas/teams-devices_dns_search_suffixes" }, "enabled": { "description": "Whether the policy will be applied to matching devices.", "type": "boolean", "example": true, "default": true }, "exclude": { "$ref": "#/components/schemas/teams-devices_exclude" }, "exclude_office_ips": { "$ref": "#/components/schemas/teams-devices_exclude_office_ips" }, "fallback_domains": { "$ref": "#/components/schemas/teams-devices_fallback_domains" }, "gateway_unique_id": { "$ref": "#/components/schemas/teams-devices_gateway_unique_id" }, "global_acceleration": { "$ref": "#/components/schemas/teams-devices_global_acceleration" }, "include": { "$ref": "#/components/schemas/teams-devices_include" }, "policy_id": { "$ref": "#/components/schemas/teams-devices_schemas-uuid" }, "register_interface_ip_with_dns": { "$ref": "#/components/schemas/teams-devices_register_interface_ip_with_dns" }, "sccm_vpn_boundary_support": { "$ref": "#/components/schemas/teams-devices_sccm_vpn_boundary_support" }, "service_mode_v2": { "$ref": "#/components/schemas/teams-devices_service_mode_v2" }, "support_url": { "$ref": "#/components/schemas/teams-devices_support_url" }, "switch_locked": { "$ref": "#/components/schemas/teams-devices_switch_locked" }, "tunnel_protocol": { "$ref": "#/components/schemas/teams-devices_tunnel_protocol" }, "uninstall_protection": { "$ref": "#/components/schemas/teams-devices_uninstall_protection" }, "virtual_networks": { "$ref": "#/components/schemas/teams-devices_virtual_networks" } } }, "teams-devices_default_device_settings_response": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/teams-devices_default_device_settings_policy" } }, "type": "object" } ] }, "teams-devices_deleted": { "description": "True if the device was deleted.", "type": "boolean", "example": true }, "teams-devices_deployment_group": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/teams-devices_deployment_group_created_at" }, "id": { "$ref": "#/components/schemas/teams-devices_deployment_group_id" }, "name": { "$ref": "#/components/schemas/teams-devices_deployment_group_name" }, "policy_ids": { "$ref": "#/components/schemas/teams-devices_deployment_group_policy_ids" }, "updated_at": { "$ref": "#/components/schemas/teams-devices_deployment_group_updated_at" }, "version_config": { "description": "Contains version configurations for different target environments.", "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_version_config" } } }, "required": [ "id", "name", "version_config", "created_at", "updated_at" ] }, "teams-devices_deployment_group_create_request": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/teams-devices_deployment_group_name" }, "policy_ids": { "description": "Contains an optional list of policy IDs assigned to a group.", "type": "array", "items": { "type": "string" } }, "version_config": { "description": "Contains at least one version configuration.", "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_version_config" }, "minItems": 1 } }, "required": [ "name", "version_config" ] }, "teams-devices_deployment_group_created_at": { "description": "The RFC3339Nano timestamp when the deployment group was created.", "type": "string", "example": "2026-02-14T13:17:00.123456789Z" }, "teams-devices_deployment_group_id": { "description": "The ID of the deployment group.", "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000", "x-auditable": true }, "teams-devices_deployment_group_name": { "description": "A user-friendly name for the deployment group.", "type": "string", "example": "Engineering Ring 0", "maxLength": 255, "minLength": 1, "x-auditable": true }, "teams-devices_deployment_group_policy_ids": { "description": "Contains a list of policy IDs assigned to this deployment group.", "type": "array", "items": { "type": "string" }, "example": [ "policy-uuid-1", "policy-uuid-2" ], "nullable": true, "x-auditable": true }, "teams-devices_deployment_group_update_request": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/teams-devices_deployment_group_name" }, "policy_ids": { "description": "Replaces the entire list of policy IDs.", "type": "array", "items": { "type": "string" } }, "version_config": { "description": "Replaces the entire version_config array.", "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_version_config" } } } }, "teams-devices_deployment_group_updated_at": { "description": "The RFC3339Nano timestamp when the deployment group was last updated.", "type": "string", "example": "2026-02-14T13:17:00.123456789Z" }, "teams-devices_description": { "description": "The description of the device posture rule.", "type": "string", "example": "The rule for admin serial numbers", "x-auditable": true }, "teams-devices_device": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/teams-devices_account" }, "created": { "$ref": "#/components/schemas/teams-devices_created" }, "deleted": { "$ref": "#/components/schemas/teams-devices_deleted" }, "device_type": { "$ref": "#/components/schemas/teams-devices_device_type" }, "gateway_device_id": { "$ref": "#/components/schemas/teams-devices_gateway_device_id" }, "id": { "$ref": "#/components/schemas/teams-devices_registration_id" }, "ip": { "$ref": "#/components/schemas/teams-devices_ip" }, "key": { "$ref": "#/components/schemas/teams-devices_key" }, "key_type": { "$ref": "#/components/schemas/teams-devices_key_type" }, "last_seen": { "$ref": "#/components/schemas/teams-devices_last_seen" }, "mac_address": { "$ref": "#/components/schemas/teams-devices_mac_address" }, "model": { "$ref": "#/components/schemas/teams-devices_model" }, "name": { "$ref": "#/components/schemas/teams-devices_schemas-name" }, "os_version": { "$ref": "#/components/schemas/teams-devices_os_version" }, "serial_number": { "$ref": "#/components/schemas/teams-devices_serial_number" }, "tunnel_type": { "$ref": "#/components/schemas/teams-devices_tunnel_type" }, "updated": { "$ref": "#/components/schemas/teams-devices_updated" }, "user": { "$ref": "#/components/schemas/teams-devices_user" }, "version": { "$ref": "#/components/schemas/teams-devices_version" } } }, "teams-devices_device-managed-networks": { "type": "object", "properties": { "config": { "$ref": "#/components/schemas/teams-devices_schemas-config_response" }, "name": { "$ref": "#/components/schemas/teams-devices_device-managed-networks_components-schemas-name" }, "network_id": { "$ref": "#/components/schemas/teams-devices_uuid" }, "type": { "$ref": "#/components/schemas/teams-devices_components-schemas-type" } } }, "teams-devices_device-managed-networks_components-schemas-name": { "description": "The name of the device managed network. This name must be unique.", "type": "string", "example": "managed-network-1", "x-auditable": true }, "teams-devices_device-posture-integrations": { "type": "object", "properties": { "config": { "$ref": "#/components/schemas/teams-devices_config_response" }, "id": { "$ref": "#/components/schemas/teams-devices_uuid" }, "interval": { "$ref": "#/components/schemas/teams-devices_interval" }, "name": { "$ref": "#/components/schemas/teams-devices_components-schemas-name" }, "type": { "$ref": "#/components/schemas/teams-devices_schemas-type" } } }, "teams-devices_device-posture-rules": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/teams-devices_description" }, "enabled": { "description": "Whether the rule is enabled. This is a computed, read-only value. It is false for deprecated Kolide posture rules that still use the issue_count input, and true otherwise.", "type": "boolean", "example": true, "readOnly": true }, "expiration": { "$ref": "#/components/schemas/teams-devices_expiration" }, "id": { "$ref": "#/components/schemas/teams-devices_uuid" }, "input": { "$ref": "#/components/schemas/teams-devices_input" }, "match": { "$ref": "#/components/schemas/teams-devices_match" }, "name": { "$ref": "#/components/schemas/teams-devices_name" }, "schedule": { "$ref": "#/components/schemas/teams-devices_schedule" }, "type": { "$ref": "#/components/schemas/teams-devices_type" } } }, "teams-devices_device_response": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/teams-devices_device" } }, "type": "object" } ] }, "teams-devices_device_settings_policy": { "type": "object", "properties": { "allow_mode_switch": { "$ref": "#/components/schemas/teams-devices_allow_mode_switch" }, "allow_updates": { "$ref": "#/components/schemas/teams-devices_allow_updates" }, "allowed_to_leave": { "$ref": "#/components/schemas/teams-devices_allowed_to_leave" }, "auto_connect": { "$ref": "#/components/schemas/teams-devices_auto_connect" }, "captive_portal": { "$ref": "#/components/schemas/teams-devices_captive_portal" }, "default": { "$ref": "#/components/schemas/teams-devices_default" }, "description": { "$ref": "#/components/schemas/teams-devices_schemas-description" }, "disable_auto_fallback": { "$ref": "#/components/schemas/teams-devices_disable_auto_fallback" }, "dns_search_suffixes": { "$ref": "#/components/schemas/teams-devices_dns_search_suffixes" }, "enabled": { "description": "Whether the policy will be applied to matching devices.", "type": "boolean", "example": true, "default": true }, "exclude": { "$ref": "#/components/schemas/teams-devices_exclude" }, "exclude_office_ips": { "$ref": "#/components/schemas/teams-devices_exclude_office_ips" }, "fallback_domains": { "$ref": "#/components/schemas/teams-devices_fallback_domains" }, "gateway_unique_id": { "$ref": "#/components/schemas/teams-devices_gateway_unique_id" }, "global_acceleration": { "$ref": "#/components/schemas/teams-devices_global_acceleration" }, "include": { "$ref": "#/components/schemas/teams-devices_include" }, "lan_allow_minutes": { "$ref": "#/components/schemas/teams-devices_lan_allow_minutes" }, "lan_allow_subnet_size": { "$ref": "#/components/schemas/teams-devices_lan_allow_subnet_size" }, "match": { "$ref": "#/components/schemas/teams-devices_schemas-match" }, "name": { "description": "The name of the device settings profile.", "type": "string", "example": "Allow Developers", "maxLength": 100 }, "policy_id": { "$ref": "#/components/schemas/teams-devices_schemas-uuid" }, "precedence": { "$ref": "#/components/schemas/teams-devices_precedence" }, "register_interface_ip_with_dns": { "$ref": "#/components/schemas/teams-devices_register_interface_ip_with_dns" }, "sccm_vpn_boundary_support": { "$ref": "#/components/schemas/teams-devices_sccm_vpn_boundary_support" }, "service_mode_v2": { "$ref": "#/components/schemas/teams-devices_service_mode_v2" }, "support_url": { "$ref": "#/components/schemas/teams-devices_support_url" }, "switch_locked": { "$ref": "#/components/schemas/teams-devices_switch_locked" }, "target_tests": { "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_target_dex_test" } }, "tunnel_protocol": { "$ref": "#/components/schemas/teams-devices_tunnel_protocol" }, "uninstall_protection": { "$ref": "#/components/schemas/teams-devices_uninstall_protection" }, "virtual_networks": { "$ref": "#/components/schemas/teams-devices_virtual_networks" } } }, "teams-devices_device_settings_response": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/teams-devices_device_settings_policy" } }, "type": "object" } ] }, "teams-devices_device_settings_response_collection": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_device_settings_policy" } } }, "type": "object" } ] }, "teams-devices_device_type": { "type": "string", "example": "windows", "x-auditable": true }, "teams-devices_devices": { "type": "object", "properties": { "created": { "$ref": "#/components/schemas/teams-devices_created" }, "deleted": { "$ref": "#/components/schemas/teams-devices_deleted" }, "device_type": { "$ref": "#/components/schemas/teams-devices_platform" }, "id": { "$ref": "#/components/schemas/teams-devices_registration_id" }, "ip": { "$ref": "#/components/schemas/teams-devices_ip" }, "key": { "$ref": "#/components/schemas/teams-devices_key" }, "last_seen": { "$ref": "#/components/schemas/teams-devices_last_seen" }, "mac_address": { "$ref": "#/components/schemas/teams-devices_mac_address" }, "manufacturer": { "$ref": "#/components/schemas/teams-devices_manufacturer" }, "model": { "$ref": "#/components/schemas/teams-devices_model" }, "name": { "$ref": "#/components/schemas/teams-devices_schemas-name" }, "os_distro_name": { "$ref": "#/components/schemas/teams-devices_os_distro_name" }, "os_distro_revision": { "$ref": "#/components/schemas/teams-devices_os_distro_revision" }, "os_version": { "$ref": "#/components/schemas/teams-devices_os_version" }, "os_version_extra": { "$ref": "#/components/schemas/teams-devices_os_version_extra" }, "revoked_at": { "$ref": "#/components/schemas/teams-devices_revoked_at" }, "serial_number": { "$ref": "#/components/schemas/teams-devices_serial_number" }, "updated": { "$ref": "#/components/schemas/teams-devices_updated" }, "user": { "$ref": "#/components/schemas/teams-devices_user" }, "version": { "$ref": "#/components/schemas/teams-devices_version" } } }, "teams-devices_devices_policy_certificates": { "type": "object", "properties": { "enabled": { "description": "The current status of the device policy certificate provisioning feature for WARP clients.", "type": "boolean", "example": true } }, "required": [ "enabled" ] }, "teams-devices_devices_policy_certificates_single": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/teams-devices_devices_policy_certificates" } }, "type": "object" } ] }, "teams-devices_devices_response": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_devices" } } }, "type": "object" } ] }, "teams-devices_disable_auto_fallback": { "description": "If the `dns_server` field of a fallback domain is not present, the client will fall back to a best guess of the default/system DNS resolvers unless this policy option is set to `true`.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "teams-devices_disable_for_time": { "type": "object", "properties": { "1": { "description": "Override code that is valid for 1 hour.", "type": "string", "example": "9106681" }, "3": { "description": "Override code that is valid for 3 hours.", "type": "string", "example": "5356247" }, "6": { "description": "Override code that is valid for 6 hours.", "type": "string", "example": "9478972" }, "12": { "description": "Override code that is valid for 12 hour2.", "type": "string", "example": "3424359" }, "24": { "description": "Override code that is valid for 24 hour.2.", "type": "string", "example": "2887634" } } }, "teams-devices_disconnect": { "description": "Disconnects all devices on the account using Global WARP override.", "type": "boolean", "example": false, "x-auditable": true }, "teams-devices_disk_encryption_input_request": { "type": "object", "properties": { "checkDisks": { "$ref": "#/components/schemas/teams-devices_checkDisks" }, "requireAll": { "$ref": "#/components/schemas/teams-devices_requireAll" } }, "title": "Disk Encryption" }, "teams-devices_dns_search_suffix": { "type": "object", "properties": { "description": { "description": "A description of the DNS search suffix.", "type": "string", "example": "Example internal domains", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "suffix": { "description": "The DNS search suffix to append when resolving short hostnames.", "type": "string", "example": "internal.corp", "x-auditable": true } }, "required": [ "suffix" ] }, "teams-devices_dns_search_suffixes": { "description": "List of DNS search suffixes to apply to clients. Suffixes are evaluated in order. Use an empty array to clear.", "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_dns_search_suffix" }, "default": [], "x-stainless-terraform-configurability": "computed_optional" }, "teams-devices_domain_joined_input_request": { "type": "object", "properties": { "domain": { "description": "Domain.", "type": "string", "example": "example.com", "x-auditable": true }, "operating_system": { "description": "Operating System.", "type": "string", "example": "windows", "enum": [ "windows" ], "x-auditable": true } }, "required": [ "operating_system" ], "title": "Domain Joined" }, "teams-devices_email": { "description": "The contact email address of the user.", "type": "string", "example": "user@example.com", "maxLength": 90, "x-auditable": true }, "teams-devices_empty_body": { "type": "object", "nullable": true }, "teams-devices_exclude": { "description": "List of routes excluded in the WARP client's tunnel.", "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_split_tunnel" }, "default": [ { "address": "10.0.0.0/8" }, { "address": "100.64.0.0/10" }, { "address": "169.254.0.0/16", "description": "DHCP Unspecified" }, { "address": "172.16.0.0/12" }, { "address": "192.0.0.0/24" }, { "address": "192.168.0.0/16" }, { "address": "224.0.0.0/24" }, { "address": "240.0.0.0/4" }, { "address": "255.255.255.255/32", "description": "DHCP Broadcast" }, { "address": "fe80::/10", "description": "IPv6 Link Local" }, { "address": "fd00::/8" }, { "address": "ff01::/16" }, { "address": "ff02::/16" }, { "address": "ff03::/16" }, { "address": "ff04::/16" }, { "address": "ff05::/16" } ] }, "teams-devices_exclude_office_ips": { "description": "Whether to add Microsoft IPs to Split Tunnel exclusions.", "type": "boolean", "example": true, "default": false }, "teams-devices_exclude_request": { "description": "List of routes excluded in the WARP client's tunnel. Both 'exclude' and 'include' cannot be set in the same request.", "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_split_tunnel" }, "x-stainless-terraform-configurability": "computed_optional" }, "teams-devices_exclude_split_tunnel_with_address": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/teams-devices_split_tunnel_address" }, "description": { "$ref": "#/components/schemas/teams-devices_split_tunnel_description" } }, "required": [ "address" ] }, "teams-devices_exclude_split_tunnel_with_host": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/teams-devices_split_tunnel_description" }, "host": { "$ref": "#/components/schemas/teams-devices_split_tunnel_host" } }, "required": [ "host" ] }, "teams-devices_expiration": { "description": "Sets the expiration time for a posture check result. If empty, the result remains valid until it is overwritten by new data from the WARP client.", "type": "string", "example": "1h" }, "teams-devices_extended_key_usage_enum": { "type": "string", "enum": [ "clientAuth", "emailProtection" ], "x-auditable": true }, "teams-devices_fallback_domain": { "type": "object", "properties": { "description": { "description": "A description of the fallback domain, displayed in the client UI.", "type": "string", "example": "Domain bypass for local development", "maxLength": 100, "x-auditable": true }, "dns_server": { "description": "A list of IP addresses to handle domain resolution.", "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_ip" } }, "suffix": { "description": "The domain suffix to match when resolving locally.", "type": "string", "example": "example.com", "x-auditable": true } }, "required": [ "suffix" ] }, "teams-devices_fallback_domain_response_collection": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_fallback_domain" } } }, "type": "object" } ] }, "teams-devices_fallback_domains": { "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_fallback_domain" }, "default": [ { "suffix": "intranet" }, { "suffix": "internal" }, { "suffix": "private" }, { "suffix": "localdomain" }, { "suffix": "domain" }, { "suffix": "lan" }, { "suffix": "home" }, { "suffix": "host" }, { "suffix": "corp" }, { "suffix": "local" }, { "suffix": "localhost" }, { "suffix": "home.arpa" }, { "suffix": "invalid" }, { "suffix": "test" } ] }, "teams-devices_file_input_request": { "type": "object", "properties": { "exists": { "description": "Whether or not file exists.", "type": "boolean", "example": true, "x-auditable": true }, "operating_system": { "description": "Operating system.", "type": "string", "example": "mac", "enum": [ "windows", "linux", "mac" ], "x-auditable": true }, "path": { "description": "File path.", "type": "string", "example": "/bin/cat", "x-auditable": true }, "sha256": { "description": "SHA-256.", "type": "string", "example": "https://api.us-2.crowdstrike.com" }, "thumbprint": { "description": "Signing certificate thumbprint.", "type": "string", "example": "0aabab210bdb998e9cf45da2c9ce352977ab531c681b74cf1e487be1bbe9fe6e" } }, "required": [ "path", "operating_system" ], "title": "File Check" }, "teams-devices_firewall_input_request": { "type": "object", "properties": { "enabled": { "description": "Enabled.", "type": "boolean", "example": true, "x-auditable": true }, "operating_system": { "description": "Operating System.", "type": "string", "example": "windows", "enum": [ "windows", "mac" ], "x-auditable": true } }, "required": [ "operating_system", "enabled" ], "title": "Firewall" }, "teams-devices_gateway_device_id": { "type": "string", "example": "PD33E90AXfafe14643cbbbc-4a0ed4fc8415Q", "deprecated": true }, "teams-devices_gateway_unique_id": { "type": "string", "example": "699d98642c564d2e855e9661899b7252" }, "teams-devices_global_acceleration": { "description": "Global Acceleration settings for China. When configured, WARP clients connect to the Global Accelerator addresses instead of the default ones. Please contact your account representative to enable this feature on your account. See https://developers.cloudflare.com/china-network/concepts/global-acceleration/.", "type": "object", "properties": { "api_endpoints": { "description": "IP:port entries for the API endpoints.", "type": "array", "items": { "type": "string" }, "example": [ "198.51.100.1:443" ], "maxItems": 5, "x-auditable": true }, "enabled": { "description": "Global acceleration settings are used only when \"enabled\".", "type": "boolean", "example": true, "x-auditable": true }, "masque_endpoints": { "description": "IP:port entries for the MASQUE tunnel endpoints. Either wireguard_endpoints or masque_endpoints must be provided.", "type": "array", "items": { "type": "string" }, "example": [ "198.51.100.1:443" ], "maxItems": 5, "x-auditable": true }, "wireguard_endpoints": { "description": "IP:port entries for the WireGuard tunnel endpoints. Either wireguard_endpoints or masque_endpoints must be provided.", "type": "array", "items": { "type": "string" }, "example": [ "198.51.100.1:2408" ], "maxItems": 5, "x-auditable": true } }, "nullable": true, "required": [ "enabled", "wireguard_endpoints", "masque_endpoints", "api_endpoints" ], "x-auditable": true }, "teams-devices_global_warp_override": { "type": "object", "properties": { "disconnect": { "$ref": "#/components/schemas/teams-devices_disconnect" }, "timestamp": { "$ref": "#/components/schemas/teams-devices_timestamp" } } }, "teams-devices_global_warp_override_request": { "type": "object", "properties": { "disconnect": { "$ref": "#/components/schemas/teams-devices_disconnect" }, "justification": { "$ref": "#/components/schemas/teams-devices_justification" } }, "required": [ "disconnect" ], "title": "Global WARP override request" }, "teams-devices_global_warp_override_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/teams-devices_global_warp_override" } }, "type": "object" } ] }, "teams-devices_id_response": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/teams-devices_uuid" } } } }, "type": "object" } ] }, "teams-devices_identifier": { "type": "string", "example": "699d98642c564d2e855e9661899b7252" }, "teams-devices_include": { "description": "List of routes included in the WARP client's tunnel.", "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_split_tunnel_include" } }, "teams-devices_include_request": { "description": "List of routes included in the WARP client's tunnel. Both 'exclude' and 'include' cannot be set in the same request.", "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_split_tunnel_include" }, "x-stainless-terraform-configurability": "computed_optional" }, "teams-devices_include_split_tunnel_address": { "description": "The address in CIDR format to include in the tunnel. If `address` is present, `host` must not be present.", "type": "string", "example": "192.0.2.0/24", "x-stainless-terraform-configurability": "computed_optional" }, "teams-devices_include_split_tunnel_description": { "description": "A description of the Split Tunnel item, displayed in the client UI.", "type": "string", "example": "Include testing domains in the tunnel", "maxLength": 100, "x-stainless-terraform-configurability": "computed_optional" }, "teams-devices_include_split_tunnel_host": { "description": "The domain name to include in the tunnel. If `host` is present, `address` must not be present.", "type": "string", "example": "*.example.com", "x-stainless-terraform-configurability": "computed_optional" }, "teams-devices_include_split_tunnel_with_address": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/teams-devices_include_split_tunnel_address" }, "description": { "$ref": "#/components/schemas/teams-devices_include_split_tunnel_description" } }, "required": [ "address" ] }, "teams-devices_include_split_tunnel_with_host": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/teams-devices_include_split_tunnel_description" }, "host": { "$ref": "#/components/schemas/teams-devices_include_split_tunnel_host" } }, "required": [ "host" ] }, "teams-devices_input": { "description": "The value to be checked against.", "type": "object", "example": { "operating_system": "linux", "path": "/bin/cat", "thumbprint": "0aabab210bdb998e9cf45da2c9ce352977ab531c681b74cf1e487be1bbe9fe6e" }, "oneOf": [ { "$ref": "#/components/schemas/teams-devices_file_input_request" }, { "$ref": "#/components/schemas/teams-devices_unique_client_id_input_request" }, { "$ref": "#/components/schemas/teams-devices_domain_joined_input_request" }, { "$ref": "#/components/schemas/teams-devices_os_version_input_request" }, { "$ref": "#/components/schemas/teams-devices_firewall_input_request" }, { "$ref": "#/components/schemas/teams-devices_sentinelone_input_request" }, { "$ref": "#/components/schemas/teams-devices_carbonblack_input_request" }, { "$ref": "#/components/schemas/teams-devices_access_serial_number_list_input_request" }, { "$ref": "#/components/schemas/teams-devices_disk_encryption_input_request" }, { "$ref": "#/components/schemas/teams-devices_application_input_request" }, { "$ref": "#/components/schemas/teams-devices_client_certificate_input_request" }, { "$ref": "#/components/schemas/teams-devices_client_certificate_v2_input_request" }, { "$ref": "#/components/schemas/teams-devices_antivirus_input_request" }, { "$ref": "#/components/schemas/teams-devices_workspace_one_input_request" }, { "$ref": "#/components/schemas/teams-devices_crowdstrike_input_request" }, { "$ref": "#/components/schemas/teams-devices_intune_input_request" }, { "$ref": "#/components/schemas/teams-devices_kolide_input_request" }, { "$ref": "#/components/schemas/teams-devices_tanium_input_request" }, { "$ref": "#/components/schemas/teams-devices_sentinelone_s2s_input_request" }, { "$ref": "#/components/schemas/teams-devices_custom_s2s_input_request" } ] }, "teams-devices_interval": { "description": "The interval between each posture check with the third-party API. Use `m` for minutes (e.g. `5m`) and `h` for hours (e.g. `12h`).", "type": "string", "example": "10m", "x-auditable": true }, "teams-devices_intune_config_request": { "type": "object", "properties": { "client_id": { "description": "The Intune client ID.", "type": "string", "example": "example client id" }, "client_secret": { "description": "The Intune client secret.", "type": "string", "example": "example client secret", "x-sensitive": true }, "customer_id": { "description": "The Intune customer ID.", "type": "string", "example": "example customer id" } }, "required": [ "customer_id", "client_id", "client_secret" ], "title": "Intune Config" }, "teams-devices_intune_input_request": { "type": "object", "properties": { "compliance_status": { "description": "Compliance Status.", "type": "string", "example": "compliant", "enum": [ "compliant", "noncompliant", "unknown", "notapplicable", "ingraceperiod", "error" ], "x-auditable": true }, "connection_id": { "description": "Posture Integration ID.", "type": "string", "example": "bc7cbfbb-600a-42e4-8a23-45b5e85f804f", "x-auditable": true } }, "required": [ "connection_id", "compliance_status" ], "title": "Intune S2S Input" }, "teams-devices_ip": { "description": "IPv4 or IPv6 address.", "type": "string", "example": "1.1.1.1", "x-auditable": true }, "teams-devices_ip_profile": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/teams-devices_ip_profile_created_at" }, "description": { "$ref": "#/components/schemas/teams-devices_ip_profile_description" }, "enabled": { "$ref": "#/components/schemas/teams-devices_ip_profile_enabled" }, "id": { "$ref": "#/components/schemas/teams-devices_ip_profile_id" }, "match": { "$ref": "#/components/schemas/teams-devices_ip_profile_match" }, "name": { "$ref": "#/components/schemas/teams-devices_ip_profile_name" }, "precedence": { "$ref": "#/components/schemas/teams-devices_ip_profile_precedence" }, "subnet_id": { "$ref": "#/components/schemas/teams-devices_ip_profile_subnet_id" }, "updated_at": { "$ref": "#/components/schemas/teams-devices_ip_profile_updated_at" } }, "required": [ "id", "name", "match", "description", "precedence", "subnet_id", "created_at", "updated_at", "enabled" ] }, "teams-devices_ip_profile_create_request": { "type": "object", "properties": { "description": { "description": "An optional description of the Device IP profile.", "type": "string", "example": "example comment", "nullable": true, "x-auditable": true }, "enabled": { "description": "Whether the Device IP profile will be applied to matching devices.", "type": "boolean", "example": true, "default": true, "x-auditable": true }, "match": { "$ref": "#/components/schemas/teams-devices_ip_profile_match" }, "name": { "$ref": "#/components/schemas/teams-devices_ip_profile_name" }, "precedence": { "$ref": "#/components/schemas/teams-devices_ip_profile_precedence" }, "subnet_id": { "$ref": "#/components/schemas/teams-devices_ip_profile_subnet_id" } }, "required": [ "name", "subnet_id", "precedence", "match" ] }, "teams-devices_ip_profile_created_at": { "description": "The RFC3339Nano timestamp when the Device IP profile was created.", "type": "string", "example": "2025-02-14T13:17:00.123456789Z" }, "teams-devices_ip_profile_description": { "description": "An optional description of the Device IP profile.", "type": "string", "example": "example comment", "nullable": true, "x-auditable": true }, "teams-devices_ip_profile_enabled": { "description": "Whether the Device IP profile is enabled.", "type": "boolean", "example": true, "x-auditable": true }, "teams-devices_ip_profile_id": { "description": "The ID of the Device IP profile.", "type": "string", "example": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415", "x-auditable": true }, "teams-devices_ip_profile_match": { "description": "The wirefilter expression to match registrations. Available values: \"identity.name\", \"identity.email\", \"identity.groups.id\", \"identity.groups.name\", \"identity.groups.email\", \"identity.saml_attributes\".", "type": "string", "example": "identity.email == \"test@cloudflare.com\"", "maxLength": 10000, "x-auditable": true }, "teams-devices_ip_profile_name": { "description": "A user-friendly name for the Device IP profile.", "type": "string", "example": "IPv4 Cloudflare Source IPs", "x-auditable": true }, "teams-devices_ip_profile_precedence": { "description": "The precedence of the Device IP profile. Lower values indicate higher precedence. Device IP profile will be evaluated in ascending order of this field.", "type": "integer", "example": 100, "x-auditable": true }, "teams-devices_ip_profile_subnet_id": { "description": "The ID of the Subnet.", "type": "string", "example": "b70ff985-a4ef-4643-bbbc-4a0ed4fc8415", "x-auditable": true }, "teams-devices_ip_profile_update_request": { "type": "object", "properties": { "description": { "description": "An optional description of the Device IP profile.", "type": "string", "example": "example comment", "x-auditable": true }, "enabled": { "$ref": "#/components/schemas/teams-devices_ip_profile_enabled" }, "match": { "$ref": "#/components/schemas/teams-devices_ip_profile_match" }, "name": { "$ref": "#/components/schemas/teams-devices_ip_profile_name" }, "precedence": { "$ref": "#/components/schemas/teams-devices_ip_profile_precedence" }, "subnet_id": { "$ref": "#/components/schemas/teams-devices_ip_profile_subnet_id" } } }, "teams-devices_ip_profile_updated_at": { "description": "The RFC3339Nano timestamp when the Device IP profile was last updated.", "type": "string", "example": "2025-02-14T13:17:00.123456789Z" }, "teams-devices_justification": { "description": "Reasoning for setting the Global WARP override state. This will be surfaced in the audit log.", "type": "string", "example": "Turning off WARP for testing purposes.", "x-auditable": true }, "teams-devices_key": { "description": "The device's public key.", "type": "string", "example": "yek0SUYoOQ10vMGsIYAevozXUQpQtNFJFfFGqER/BGc=" }, "teams-devices_key_type": { "description": "Type of the key.", "type": "string", "example": "curve25519", "x-auditable": true }, "teams-devices_kolide_config_request": { "type": "object", "properties": { "client_id": { "description": "The Kolide client ID.", "type": "string", "example": "example client id" }, "client_secret": { "description": "The Kolide client secret.", "type": "string", "example": "example client secret", "x-sensitive": true } }, "required": [ "client_id", "client_secret" ], "title": "Kolide Config" }, "teams-devices_kolide_input_request": { "type": "object", "properties": { "auth_state": { "description": "The set of Kolide device authentication states that pass the posture check. Device must match one of the specified states.", "type": "array", "items": { "enum": [ "Good", "Notified", "Will Block", "Blocked" ], "type": "string" }, "example": [ "Good", "Notified" ], "minItems": 1, "uniqueItems": true, "x-auditable": true }, "connection_id": { "description": "Posture Integration ID.", "type": "string", "example": "bc7cbfbb-600a-42e4-8a23-45b5e85f804f", "x-auditable": true }, "countOperator": { "description": "Count Operator.", "type": "string", "example": ">", "enum": [ "<", "<=", ">", ">=", "==" ], "x-auditable": true }, "issue_count": { "description": "The Number of Issues.", "type": "string", "example": "1", "x-auditable": true } }, "required": [ "connection_id" ], "title": "Kolide S2S Input" }, "teams-devices_lan_allow_minutes": { "description": "The amount of time in minutes a user is allowed access to their LAN. A value of 0 will allow LAN access until the next WARP reconnection, such as a reboot or a laptop waking from sleep. Note that this field is omitted from the response if null or unset.", "type": "number", "example": 30 }, "teams-devices_lan_allow_subnet_size": { "description": "The size of the subnet for the local access network. Note that this field is omitted from the response if null or unset.", "type": "number", "example": 24 }, "teams-devices_last_seen": { "description": "When the device last connected to Cloudflare services.", "type": "string", "format": "date-time", "example": "2017-06-14T00:00:00Z", "x-auditable": true }, "teams-devices_mac_address": { "description": "The device mac address.", "type": "string", "example": "00-00-5E-00-53-00", "x-auditable": true }, "teams-devices_manufacturer": { "description": "The device manufacturer name.", "type": "string", "example": "My phone corp" }, "teams-devices_match": { "description": "The conditions that the client must match to run the rule.", "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_match_item" } }, "teams-devices_match_item": { "type": "object", "properties": { "platform": { "$ref": "#/components/schemas/teams-devices_platform" } } }, "teams-devices_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "teams-devices_model": { "description": "The device model name.", "type": "string", "example": "MyPhone(pro-X)" }, "teams-devices_name": { "description": "The name of the device posture rule.", "type": "string", "example": "Admin Serial Numbers", "x-auditable": true }, "teams-devices_os_distro_name": { "description": "The Linux distro name.", "type": "string", "example": "ubuntu", "x-auditable": true }, "teams-devices_os_distro_revision": { "description": "The Linux distro revision.", "type": "string", "example": "1.0.0", "x-auditable": true }, "teams-devices_os_version": { "description": "The operating system version.", "type": "string", "example": "10.0.0" }, "teams-devices_os_version_extra": { "description": "Additional operating system version details. For Windows, the UBR (Update Build Revision). For Mac or iOS, the Product Version Extra. For Linux, the distribution name and version.", "type": "string", "example": "(a) or 6889 or Ubuntu 24.04" }, "teams-devices_os_version_input_request": { "type": "object", "properties": { "operating_system": { "description": "Operating System.", "type": "string", "example": "windows", "enum": [ "windows" ], "x-auditable": true }, "operator": { "description": "Operator.", "type": "string", "example": "13.3.0", "enum": [ "<", "<=", ">", ">=", "==" ], "x-auditable": true }, "os_distro_name": { "description": "Operating System Distribution Name (linux only).", "type": "string", "example": "ubuntu", "x-auditable": true }, "os_distro_revision": { "description": "Version of OS Distribution (linux only).", "type": "string", "example": "11.3.1", "x-auditable": true }, "os_version_extra": { "description": "Additional operating system version details. For Windows, the UBR (Update Build Revision). For Mac or iOS, the Product Version Extra. For Linux, the distribution name and version.", "type": "string", "example": "(a) or 6889 or Ubuntu 24.04", "x-auditable": true }, "version": { "description": "Version of OS.", "type": "string", "example": "13.3.0", "x-auditable": true } }, "required": [ "operating_system", "version", "operator" ], "title": "OS Version" }, "teams-devices_override_codes": { "properties": { "disable_for_time": { "type": "object", "additionalProperties": { "type": "string" } } } }, "teams-devices_override_codes_response": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-collection" }, { "properties": { "result": { "type": "object", "properties": { "disable_for_time": { "$ref": "#/components/schemas/teams-devices_disable_for_time" } } } }, "type": "object" } ] }, "teams-devices_pagination_info": { "type": "object", "properties": { "count": { "description": "Number of records in the response.", "type": "integer" }, "page": { "description": "The page size number of the response.", "type": "integer" }, "per_page": { "description": "The limit for the number of records in the response.", "type": "integer" }, "total_count": { "description": "Total number of records available.", "type": "integer" }, "total_pages": { "description": "Total number of pages available.", "type": "integer" } }, "example": { "count": 1, "page": 1, "per_page": 10, "total_count": 10, "total_pages": 1 }, "required": [ "page", "per_page", "count", "total_count" ] }, "teams-devices_paths": { "description": "List of paths to check for client certificate on linux.", "type": "array", "items": { "type": "string" }, "example": [ "/path1", "/path2" ] }, "teams-devices_physical_device": { "description": "A WARP Device.", "type": "object", "properties": { "active_registrations": { "description": "The number of active registrations for the device. Active registrations are those which haven't been revoked or deleted.", "type": "integer", "example": 1, "x-auditable": true }, "client_version": { "description": "Version of the WARP client.", "type": "string", "example": "1.0.0", "nullable": true, "x-auditable": true }, "created_at": { "description": "The RFC3339 timestamp when the device was created.", "type": "string", "example": "2025-02-14T13:17:00Z", "x-auditable": true }, "deleted_at": { "description": "The RFC3339 timestamp when the device was deleted.", "type": "string", "example": "2025-02-14T13:17:00Z", "nullable": true, "x-auditable": true }, "device_type": { "description": "The device operating system.", "type": "string", "example": "linux", "nullable": true, "x-auditable": true }, "hardware_id": { "description": "A string that uniquely identifies the hardware or virtual machine (VM).", "type": "string", "nullable": true, "x-auditable": true }, "id": { "description": "The unique ID of the device.", "type": "string", "example": "fc9ab6ab-3b94-4319-9941-459462b3d73e", "x-auditable": true }, "last_seen_at": { "description": "The RFC3339 timestamp when the device was last seen.", "type": "string", "example": "2025-02-14T13:17:00Z", "nullable": true, "x-auditable": true }, "last_seen_registration": { "description": "The last seen registration for the device.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/teams-devices_registration_details" } ], "nullable": true }, "last_seen_user": { "description": "The last user to use the WARP device.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/teams-devices_user" } ], "nullable": true }, "mac_address": { "description": "The device MAC address.", "type": "string", "example": "f5:01:73:cf:12:23", "nullable": true, "x-auditable": true }, "manufacturer": { "description": "The device manufacturer.", "type": "string", "example": "ACME", "nullable": true, "x-auditable": true }, "model": { "description": "The model name of the device.", "type": "string", "example": "Mark VII", "nullable": true, "x-auditable": true }, "name": { "description": "The name of the device.", "type": "string", "example": "My Device", "x-auditable": true }, "os_version": { "description": "The device operating system version number.", "type": "string", "nullable": true, "x-auditable": true }, "os_version_extra": { "description": "Additional operating system version details. For Windows, the UBR (Update Build Revision). For Mac or iOS, the Product Version Extra. For Linux, the distribution name and version.", "type": "string", "nullable": true, "x-auditable": true }, "public_ip": { "description": "**Deprecated**: IP information is provided by DEX - see https://developers.cloudflare.com/api/resources/zero_trust/subresources/dex/subresources/fleet_status/subresources/devices/methods/list/\n", "type": "string", "example": "1.1.1.1", "deprecated": true, "nullable": true, "x-auditable": true }, "serial_number": { "description": "The device serial number.", "type": "string", "example": "ABS765ASD8A", "nullable": true, "x-auditable": true }, "updated_at": { "description": "The RFC3339 timestamp when the device was last updated.", "type": "string", "example": "2025-02-14T13:17:00Z", "x-auditable": true } }, "required": [ "id", "name", "created_at", "updated_at", "last_seen_at", "active_registrations" ] }, "teams-devices_platform": { "type": "string", "example": "windows", "enum": [ "windows", "mac", "linux", "android", "ios", "chromeos" ], "x-auditable": true }, "teams-devices_policy_summary": { "description": "The device settings profile assigned to this registration.", "type": "object", "properties": { "default": { "description": "Whether the device settings profile is the default profile for the account.", "type": "boolean" }, "deleted": { "description": "Whether the device settings profile was deleted.", "type": "boolean" }, "id": { "description": "The ID of the device settings profile.", "type": "string", "example": "11ffb86f-3f0c-4306-b4a2-e62f872b166a" }, "name": { "description": "The name of the device settings profile.", "type": "string" }, "updated_at": { "description": "The RFC3339 timestamp of when the device settings profile last changed for the registration.", "type": "string", "example": "2025-02-14T13:17:00Z" } }, "required": [ "id", "name", "updated_at", "default", "deleted" ] }, "teams-devices_precedence": { "description": "The precedence of the policy. Lower values indicate higher precedence. Policies will be evaluated in ascending order of this field.", "type": "number", "example": 100 }, "teams-devices_register_interface_ip_with_dns": { "description": "Determines if the operating system will register WARP's local interface IP with your on-premises DNS server.", "type": "boolean", "example": true, "default": true }, "teams-devices_registration": { "description": "A WARP configuration tied to a single user. Multiple registrations can be created from a single WARP device.", "type": "object", "properties": { "created_at": { "description": "The RFC3339 timestamp when the registration was created.", "type": "string", "example": "2025-02-14T13:17:00Z", "x-auditable": true }, "deleted_at": { "description": "The RFC3339 timestamp when the registration was deleted.", "type": "string", "example": "2025-02-14T13:17:00Z", "nullable": true, "x-auditable": true }, "device": { "$ref": "#/components/schemas/teams-devices_registration_device_details" }, "id": { "description": "The ID of the registration.", "type": "string", "example": "11ffb86f-3f0c-4306-b4a2-e62f872b166a", "x-auditable": true }, "key": { "description": "The public key used to connect to the Cloudflare network.", "type": "string", "example": "U+QTP50RsWfeLGHF4tlGDnmGeuwtsz46KCHr5OyhWq00Rsdfl45mgnQAuEJ6CO0YrkyTl9FUf5iB0bwYR3g4EEFEHhtu6jFaqfMrBMBSz6itv9HQXkaR9OieKQ==", "x-auditable": true }, "key_type": { "description": "The type of encryption key used by the WARP client for the active key. Currently 'curve25519' for WireGuard and 'secp256r1' for MASQUE.", "type": "string", "example": "secp256r1", "nullable": true, "x-auditable": true }, "last_seen_at": { "description": "The RFC3339 timestamp when the registration was last seen.", "type": "string", "example": "2025-02-14T13:17:00Z", "x-auditable": true }, "policy": { "$ref": "#/components/schemas/teams-devices_policy_summary" }, "revoked_at": { "description": "The RFC3339 timestamp when the registration was revoked.", "type": "string", "example": "2025-02-14T13:17:00Z", "nullable": true, "x-auditable": true }, "tunnel_type": { "description": "Type of the tunnel - wireguard or masque.", "type": "string", "example": "masque", "nullable": true, "x-auditable": true }, "updated_at": { "description": "The RFC3339 timestamp when the registration was last updated.", "type": "string", "example": "2025-02-14T13:17:00Z", "x-auditable": true }, "user": { "$ref": "#/components/schemas/teams-devices_user" }, "virtual_ipv4": { "description": "The virtual IPv4 address assigned to the network interface of the tunnel for this registration.", "type": "string", "example": "100.96.0.1", "nullable": true, "x-auditable": true }, "virtual_ipv6": { "description": "The virtual IPv6 address assigned to the network interface of the tunnel for this registration.", "type": "string", "example": "2606:4700:0cf1:1000::1", "nullable": true, "x-auditable": true } }, "required": [ "id", "key", "device", "created_at", "updated_at", "last_seen_at" ] }, "teams-devices_registration_details": { "description": "The summary of a registration.", "type": "object", "properties": { "policy": { "description": "A summary of the device profile evaluated for the registration.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/teams-devices_policy_summary" } ], "nullable": true } } }, "teams-devices_registration_device_details": { "description": "Device details embedded inside of a registration.", "type": "object", "properties": { "client_version": { "description": "Version of the WARP client.", "type": "string", "example": "1.0.0", "x-auditable": true }, "id": { "description": "The ID of the device.", "type": "string", "example": "32aa0404-78f1-49a4-99e0-97f575081356", "x-auditable": true }, "name": { "description": "The name of the device.", "type": "string", "example": "My Device", "x-auditable": true } }, "required": [ "id", "name" ] }, "teams-devices_registration_id": { "description": "Registration ID. Equal to Device ID except for accounts which enabled [multi-user mode](https://developers.cloudflare.com/cloudflare-one/connections/connect-devices/warp/deployment/mdm-deployment/windows-multiuser/).", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "x-auditable": true }, "teams-devices_requireAll": { "description": "Whether to check all disks for encryption.", "type": "boolean", "example": true, "x-auditable": true }, "teams-devices_response_collection": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_device-posture-rules" } } }, "type": "object" } ] }, "teams-devices_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 } } }, "teams-devices_revoke_devices_request": { "description": "A list of Registration IDs to revoke.", "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_registration_id" }, "maxLength": 200 }, "teams-devices_revoked_at": { "description": "When the device was revoked.", "type": "string", "format": "date-time", "example": "2017-06-14T00:00:00Z", "x-auditable": true }, "teams-devices_sccm_vpn_boundary_support": { "description": "Determines whether the WARP client indicates to SCCM that it is inside a VPN boundary. (Windows only).", "type": "boolean", "example": false, "default": false }, "teams-devices_schedule": { "description": "Polling frequency for the WARP client posture check. Default: `5m` (poll every five minutes). Minimum: `1m`.", "type": "string", "example": "1h", "x-auditable": true }, "teams-devices_schemas-config_request": { "description": "The configuration object containing information for the WARP client to detect the managed network.", "type": "object", "example": { "sha256": "b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c", "tls_sockaddr": "foo.bar:1234" }, "oneOf": [ { "$ref": "#/components/schemas/teams-devices_tls_config_request" } ] }, "teams-devices_schemas-config_response": { "description": "The configuration object containing information for the WARP client to detect the managed network.", "type": "object", "example": { "sha256": "b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c", "tls_sockaddr": "foo.bar:1234" }, "oneOf": [ { "$ref": "#/components/schemas/teams-devices_tls_config_response" } ] }, "teams-devices_schemas-description": { "description": "A description of the policy.", "type": "string", "example": "Policy for test teams.", "maxLength": 500 }, "teams-devices_schemas-id_response": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-single" }, { "properties": { "result": { "type": "object", "nullable": true } }, "type": "object" } ] }, "teams-devices_schemas-match": { "description": "The wirefilter expression to match devices. Available values: \"identity.email\", \"identity.groups.id\", \"identity.groups.name\", \"identity.groups.email\", \"identity.service_token_uuid\", \"identity.saml_attributes\", \"network\", \"os.name\", \"os.version\".", "type": "string", "example": "identity.email == \"test@cloudflare.com\"", "maxLength": 500 }, "teams-devices_schemas-name": { "description": "The device name.", "type": "string", "example": "My mobile device" }, "teams-devices_schemas-response_collection": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_device-posture-integrations" } } }, "type": "object" } ] }, "teams-devices_schemas-single_response": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/teams-devices_device-posture-integrations" } }, "type": "object" } ] }, "teams-devices_schemas-type": { "description": "The type of device posture integration.", "type": "string", "example": "workspace_one", "enum": [ "workspace_one", "crowdstrike_s2s", "uptycs", "intune", "kolide", "tanium_s2s", "sentinelone_s2s", "custom_s2s" ], "x-auditable": true }, "teams-devices_schemas-uuid": { "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "x-auditable": true }, "teams-devices_sentinelone_input_request": { "type": "object", "properties": { "operating_system": { "description": "Operating system.", "type": "string", "example": "mac", "enum": [ "windows", "linux", "mac" ], "x-auditable": true }, "path": { "description": "File path.", "type": "string", "example": "/bin/cat", "x-auditable": true }, "sha256": { "description": "SHA-256.", "type": "string", "example": "b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c", "x-auditable": true }, "thumbprint": { "description": "Signing certificate thumbprint.", "type": "string", "example": "0aabab210bdb998e9cf45da2c9ce352977ab531c681b74cf1e487be1bbe9fe6e", "x-auditable": true } }, "required": [ "path", "operating_system" ], "title": "Sentinelone" }, "teams-devices_sentinelone_s2s_config_request": { "type": "object", "properties": { "api_url": { "description": "The SentinelOne S2S API URL.", "type": "string", "example": "https://example.sentinelone.net" }, "client_secret": { "description": "The SentinelOne S2S client secret.", "type": "string", "example": "example client secret", "x-sensitive": true } }, "required": [ "api_url", "client_secret" ], "title": "SentinelOne S2S Config" }, "teams-devices_sentinelone_s2s_input_request": { "type": "object", "properties": { "active_threats": { "description": "The Number of active threats.", "type": "number", "example": 1 }, "connection_id": { "description": "Posture Integration ID.", "type": "string", "example": "bc7cbfbb-600a-42e4-8a23-45b5e85f804f" }, "infected": { "description": "Whether device is infected.", "type": "boolean", "example": true }, "is_active": { "description": "Whether device is active.", "type": "boolean", "example": true }, "network_status": { "description": "Network status of device.", "type": "string", "example": "connected", "enum": [ "connected", "disconnected", "disconnecting", "connecting" ] }, "operational_state": { "description": "Agent operational state.", "type": "string", "enum": [ "na", "partially_disabled", "auto_fully_disabled", "fully_disabled", "auto_partially_disabled", "disabled_error", "db_corruption" ] }, "operator": { "description": "Operator.", "type": "string", "example": ">", "enum": [ "<", "<=", ">", ">=", "==" ] } }, "required": [ "connection_id" ], "title": "SentinelOne S2S Input" }, "teams-devices_serial_number": { "description": "The device serial number.", "type": "string", "example": "EXAMPLEHMD6R" }, "teams-devices_service_mode_v2": { "type": "object", "properties": { "mode": { "description": "The mode to run the WARP client under.", "type": "string", "example": "proxy", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "port": { "description": "The port number when used with proxy mode.", "type": "number", "example": 3000, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "x-stainless-terraform-configurability": "computed_optional" }, "teams-devices_single_response": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/teams-devices_device-posture-rules" } }, "type": "object" } ] }, "teams-devices_split_tunnel": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/teams-devices_exclude_split_tunnel_with_address" }, { "$ref": "#/components/schemas/teams-devices_exclude_split_tunnel_with_host" } ] }, "teams-devices_split_tunnel_address": { "description": "The address in CIDR format to exclude from the tunnel. If `address` is present, `host` must not be present.", "type": "string", "example": "192.0.2.0/24", "x-stainless-terraform-configurability": "computed_optional" }, "teams-devices_split_tunnel_description": { "description": "A description of the Split Tunnel item, displayed in the client UI.", "type": "string", "example": "Exclude testing domains from the tunnel", "maxLength": 100, "x-stainless-terraform-configurability": "computed_optional" }, "teams-devices_split_tunnel_host": { "description": "The domain name to exclude from the tunnel. If `host` is present, `address` must not be present.", "type": "string", "example": "*.example.com", "x-stainless-terraform-configurability": "computed_optional" }, "teams-devices_split_tunnel_include": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/teams-devices_include_split_tunnel_with_address" }, { "$ref": "#/components/schemas/teams-devices_include_split_tunnel_with_host" } ] }, "teams-devices_split_tunnel_include_response_collection": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_split_tunnel_include" } } }, "type": "object" } ] }, "teams-devices_split_tunnel_response_collection": { "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_split_tunnel" } } }, "type": "object" } ] }, "teams-devices_support_url": { "description": "The URL to launch when the Send Feedback button is clicked.", "type": "string", "example": "https://1.1.1.1/help", "default": "" }, "teams-devices_switch_locked": { "description": "Whether to allow the user to turn off the WARP switch and disconnect the client.", "type": "boolean", "example": true, "default": false }, "teams-devices_tanium_config_request": { "type": "object", "properties": { "access_client_id": { "description": "If present, this id will be passed in the `CF-Access-Client-ID` header when hitting the `api_url`.", "type": "string", "example": "88bf3b6d86161464f6509f7219099e57.access" }, "access_client_secret": { "description": "If present, this secret will be passed in the `CF-Access-Client-Secret` header when hitting the `api_url`.", "type": "string", "example": "bdd31cbc4dec990953e39163fbbb194c93313ca9f0a6e420346af9d326b1d2a5", "x-sensitive": true }, "api_url": { "description": "The Tanium API URL.", "type": "string", "example": "https://dummy-tanium-api.cloudflare.com/plugin/products/gateway/graphql", "x-auditable": true }, "client_secret": { "description": "The Tanium client secret.", "type": "string", "example": "example client secret", "x-sensitive": true } }, "required": [ "api_url", "client_secret" ], "title": "Tanium Config" }, "teams-devices_tanium_input_request": { "type": "object", "properties": { "connection_id": { "description": "Posture Integration ID.", "type": "string", "example": "bc7cbfbb-600a-42e4-8a23-45b5e85f804f", "x-auditable": true }, "eid_last_seen": { "description": "For more details on eid last seen, refer to the Tanium documentation.", "type": "string", "example": "2023-07-20T23:16:32Z", "x-auditable": true }, "operator": { "description": "Operator to evaluate risk_level or eid_last_seen.", "type": "string", "example": ">", "enum": [ "<", "<=", ">", ">=", "==" ], "x-auditable": true }, "risk_level": { "description": "For more details on risk level, refer to the Tanium documentation.", "type": "string", "example": "low", "enum": [ "low", "medium", "high", "critical" ], "x-auditable": true }, "scoreOperator": { "description": "Score Operator.", "type": "string", "example": ">", "enum": [ "<", "<=", ">", ">=", "==" ], "x-auditable": true }, "total_score": { "description": "For more details on total score, refer to the Tanium documentation.", "type": "number", "example": 1, "x-auditable": true } }, "required": [ "connection_id" ], "title": "Tanium S2S Input" }, "teams-devices_target_dex_test": { "type": "object", "properties": { "id": { "description": "The id of the DEX test targeting this policy.", "type": "string" }, "name": { "description": "The name of the DEX test targeting this policy.", "type": "string" } } }, "teams-devices_target_environment_info": { "type": "object", "properties": { "display_name": { "description": "A human-readable name for the target environment.", "type": "string", "example": "Windows" }, "target_environment": { "description": "The target environment identifier.", "type": "string", "example": "windows" } }, "required": [ "target_environment", "display_name" ] }, "teams-devices_timestamp": { "description": "When the Global WARP override state was updated.", "type": "string", "format": "date-time", "example": "1970-01-01T00:00:00Z", "x-auditable": true }, "teams-devices_tls_config_request": { "type": "object", "properties": { "sha256": { "description": "The SHA-256 hash of the TLS certificate presented by the host found at tls_sockaddr. If absent, regular certificate verification (trusted roots, valid timestamp, etc) will be used to validate the certificate.", "type": "string", "example": "b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c" }, "tls_sockaddr": { "description": "A network address of the form \"host:port\" that the WARP client will use to detect the presence of a TLS host.", "type": "string", "example": "foobar:1234" } }, "required": [ "tls_sockaddr" ] }, "teams-devices_tls_config_response": { "description": "The Managed Network TLS Config Response.", "type": "object", "properties": { "sha256": { "description": "The SHA-256 hash of the TLS certificate presented by the host found at tls_sockaddr. If absent, regular certificate verification (trusted roots, valid timestamp, etc) will be used to validate the certificate.", "type": "string", "example": "b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c" }, "tls_sockaddr": { "description": "A network address of the form \"host:port\" that the WARP client will use to detect the presence of a TLS host.", "type": "string", "example": "foobar:1234", "x-auditable": true } }, "required": [ "tls_sockaddr" ] }, "teams-devices_trust_stores": { "description": "List of trust stores to check for client certificate.", "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_trust_stores_enum" }, "example": [ "system", "user" ] }, "teams-devices_trust_stores_enum": { "type": "string", "enum": [ "system", "user" ], "x-auditable": true }, "teams-devices_tunnel_protocol": { "description": "Determines which tunnel protocol to use.", "type": "string", "example": "wireguard", "default": "" }, "teams-devices_tunnel_type": { "description": "Type of the tunnel connection used.", "type": "string", "example": "masque", "x-auditable": true }, "teams-devices_type": { "description": "The type of device posture rule.", "type": "string", "example": "file", "enum": [ "file", "application", "tanium", "gateway", "warp", "disk_encryption", "serial_number", "sentinelone", "carbonblack", "firewall", "os_version", "domain_joined", "client_certificate", "client_certificate_v2", "antivirus", "unique_client_id", "kolide", "tanium_s2s", "crowdstrike_s2s", "intune", "workspace_one", "sentinelone_s2s", "custom_s2s" ], "x-auditable": true }, "teams-devices_uninstall_protection": { "description": "Determines whether uninstalling the WARP client requires an override code. (Windows only).", "type": "boolean", "example": false, "default": false }, "teams-devices_unique_client_id_input_request": { "type": "object", "properties": { "id": { "description": "List ID.", "type": "string", "example": "da3de859-8f6e-47ea-a2b5-b2433858471f", "x-auditable": true }, "operating_system": { "description": "Operating System.", "type": "string", "example": "android", "enum": [ "android", "ios", "chromeos" ], "x-auditable": true } }, "required": [ "operating_system", "id" ], "title": "Unique Client ID" }, "teams-devices_unrevoke_devices_request": { "description": "A list of Registration IDs to unrevoke.", "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_registration_id" }, "maxLength": 200 }, "teams-devices_updated": { "description": "When the device was updated.", "type": "string", "format": "date-time", "example": "2017-06-14T00:00:00Z", "x-auditable": true }, "teams-devices_uptycs_config_request": { "type": "object", "properties": { "api_url": { "description": "The Uptycs API URL.", "type": "string", "example": "rnd.uptycs.io", "x-auditable": true }, "client_key": { "description": "The Uptycs client secret.", "type": "string", "example": "example client key", "x-sensitive": true }, "client_secret": { "description": "The Uptycs client secret.", "type": "string", "example": "example client secret", "x-sensitive": true }, "customer_id": { "description": "The Uptycs customer ID.", "type": "string", "example": "example customer id" } }, "required": [ "api_url", "client_key", "customer_id", "client_secret" ], "title": "Uptycs Config" }, "teams-devices_user": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/teams-devices_email" }, "id": { "$ref": "#/components/schemas/teams-devices_components-schemas-uuid" }, "name": { "description": "The enrolled device user's name.", "type": "string", "example": "John Appleseed" } } }, "teams-devices_uuid": { "description": "API UUID.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "x-auditable": true }, "teams-devices_v4_error_response": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_v4_response_message" }, "minItems": 1 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/teams-devices_v4_response_message" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "required": [ "result", "success", "errors", "messages" ] }, "teams-devices_v4_response_message": { "description": "A message which can be returned in either the 'errors' or 'messages' fields in a v4 API response.", "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "teams-devices_version": { "description": "The WARP client version.", "type": "string", "example": "1.0.0" }, "teams-devices_version_config": { "type": "object", "properties": { "target_environment": { "description": "The target environment for the client version (e.g., windows, macos).", "type": "string", "example": "windows", "nullable": true, "x-auditable": true }, "version": { "description": "The specific client version to deploy.", "type": "string", "example": "2026.6.234.0", "x-auditable": true } }, "required": [ "version", "target_environment" ] }, "teams-devices_virtual_networks": { "description": "Virtual network access settings for the device.", "type": "object", "properties": { "allowed": { "description": "List of virtual network IDs the device is allowed to access. When virtual_networks is set, at least one entry is required.", "type": "array", "items": { "format": "uuid", "type": "string" }, "example": [ "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" ], "minItems": 1, "uniqueItems": true }, "default": { "description": "The default virtual network ID. Must be included in the `allowed` list.", "type": "string", "format": "uuid", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415" } }, "nullable": true, "required": [ "allowed", "default" ] }, "teams-devices_workspace_one_config_request": { "type": "object", "properties": { "api_url": { "description": "The Workspace One API URL provided in the Workspace One Admin Dashboard.", "type": "string", "example": "https://as123.awmdm.com/API" }, "auth_url": { "description": "The Workspace One Authorization URL depending on your region.", "type": "string", "example": "https://na.uemauth.workspaceone.com/connect/token" }, "client_id": { "description": "The Workspace One client ID provided in the Workspace One Admin Dashboard.", "type": "string", "example": "example client id" }, "client_secret": { "description": "The Workspace One client secret provided in the Workspace One Admin Dashboard.", "type": "string", "example": "example client secret", "x-sensitive": true } }, "required": [ "api_url", "auth_url", "client_id", "client_secret" ], "title": "Workspace One Config" }, "teams-devices_workspace_one_config_response": { "description": "The Workspace One Config Response.", "type": "object", "properties": { "api_url": { "description": "The Workspace One API URL provided in the Workspace One Admin Dashboard.", "type": "string", "example": "https://as123.awmdm.com/API" }, "auth_url": { "description": "The Workspace One Authorization URL depending on your region.", "type": "string", "example": "https://na.uemauth.workspaceone.com/connect/token" }, "client_id": { "description": "The Workspace One client ID provided in the Workspace One Admin Dashboard.", "type": "string", "example": "example client id" } }, "required": [ "api_url", "auth_url", "client_id" ] }, "teams-devices_workspace_one_input_request": { "type": "object", "properties": { "compliance_status": { "description": "Compliance Status.", "type": "string", "example": "compliant", "enum": [ "compliant", "noncompliant", "unknown" ], "x-auditable": true }, "connection_id": { "description": "Posture Integration ID.", "type": "string", "example": "bc7cbfbb-600a-42e4-8a23-45b5e85f804f", "x-auditable": true } }, "required": [ "connection_id", "compliance_status" ], "title": "Workspace One S2S Input" }, "teams-devices_zero-trust-account-device-settings": { "type": "object", "properties": { "disable_for_time": { "description": "Sets the time limit, in seconds, that a user can use an override code to bypass WARP.", "type": "number", "x-auditable": true }, "external_emergency_signal_enabled": { "description": "Controls whether the external emergency disconnect feature is enabled.", "type": "boolean", "example": true, "x-auditable": true }, "external_emergency_signal_fingerprint": { "description": "The SHA256 fingerprint (64 hexadecimal characters) of the HTTPS server certificate for the external_emergency_signal_url. If provided, the WARP client will use this value to verify the server's identity. The device will ignore any response if the server's certificate fingerprint does not exactly match this value.", "type": "string", "example": "abcd1234567890abcd1234567890abcd1234567890abcd1234567890abcd1234", "x-auditable": true }, "external_emergency_signal_interval": { "description": "The interval at which the WARP client fetches the emergency disconnect signal, formatted as a duration string (e.g., \"5m\", \"2m30s\", \"1h\"). Minimum 30 seconds.", "type": "string", "example": "5m", "x-auditable": true }, "external_emergency_signal_url": { "description": "The HTTPS URL from which to fetch the emergency disconnect signal. Must use HTTPS and have an IPv4 or IPv6 address as the host.", "type": "string", "example": "https://192.0.2.1/signal", "x-auditable": true }, "gateway_proxy_enabled": { "description": "Enable gateway proxy filtering on TCP.", "type": "boolean", "example": true, "x-auditable": true }, "gateway_udp_proxy_enabled": { "description": "Enable gateway proxy filtering on UDP.", "type": "boolean", "example": true, "x-auditable": true }, "root_certificate_installation_enabled": { "description": "Enable installation of cloudflare managed root certificate.", "type": "boolean", "example": true, "x-auditable": true }, "use_zt_virtual_ip": { "description": "Enable using CGNAT virtual IPv4.", "type": "boolean", "example": true, "x-auditable": true } } }, "teams-devices_zero-trust-account-device-settings-response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/teams-devices_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/teams-devices_zero-trust-account-device-settings" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_advanced_certificate_pack_response_single": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_pack" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_advanced_type": { "description": "Type of certificate pack.", "type": "string", "example": "advanced", "enum": [ "advanced" ], "x-auditable": true }, "tls-certificates-and-hostnames_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_messages" }, "messages": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "tls-certificates-and-hostnames_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "tls-certificates-and-hostnames_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-common" } ] }, "tls-certificates-and-hostnames_associationObject": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_service" }, "status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status-10" } } }, "tls-certificates-and-hostnames_association_response_collection": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_associationObject" } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_base": { "type": "object", "properties": { "created_on": { "description": "When the Keyless SSL was created.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00Z", "readOnly": true, "x-auditable": true }, "enabled": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_enabled" }, "host": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_host" }, "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier-2" }, "modified_on": { "description": "When the Keyless SSL was last modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00Z", "readOnly": true, "x-auditable": true }, "name": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_name" }, "permissions": { "description": "Available permissions for the Keyless SSL for the current user requesting the item.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "#ssl:read", "#ssl:edit" ], "readOnly": true }, "port": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_port" }, "status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status-2" }, "tunnel": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless_tunnel" } }, "required": [ "id", "name", "host", "port", "status", "enabled", "permissions", "created_on", "modified_on" ] }, "tls-certificates-and-hostnames_brand_check": { "description": "Certificate Authority is manually reviewing the order.", "type": "boolean", "example": false, "x-auditable": true }, "tls-certificates-and-hostnames_bundle_method": { "description": "A ubiquitous bundle has the highest probability of being verified everywhere, even by clients using outdated or unusual trust stores. An optimal bundle uses the shortest chain and newest intermediates. And the force bundle verifies the chain, but does not otherwise modify it.", "type": "string", "example": "ubiquitous", "default": "ubiquitous", "enum": [ "ubiquitous", "optimal", "force" ], "x-auditable": true }, "tls-certificates-and-hostnames_ca": { "description": "Indicates whether the certificate is a CA or leaf certificate.", "type": "boolean", "example": true, "x-auditable": true }, "tls-certificates-and-hostnames_cert_id": { "description": "Certificate identifier tag.", "type": "string", "example": "2458ce5a-0c35-4c7f-82c7-8e9487d3ff60", "maxLength": 36, "x-auditable": true }, "tls-certificates-and-hostnames_cert_pack_uuid": { "description": "Certificate Pack UUID.", "type": "string", "example": "a77f8bd7-3b47-46b4-a6f1-75cf98109948", "x-auditable": true }, "tls-certificates-and-hostnames_certificate": { "description": "The zone's SSL certificate or certificate and the intermediate(s).", "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIDtTCCAp2gAwIBAgIJAMHAwfXZ5/PWMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\nBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX\naWRnaXRzIFB0eSBMdGQwHhcNMTYwODI0MTY0MzAxWhcNMTYxMTIyMTY0MzAxWjBF\nMQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmGdtcGbg/1\nCGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKnabIRuGvB\nKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpidtnKX/a+5\n0GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+pyFxIXjbEI\ndZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pEewooaeO2\nizNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABo4GnMIGkMB0GA1UdDgQWBBT/LbE4\n9rWf288N6sJA5BRb6FJIGDB1BgNVHSMEbjBsgBT/LbE49rWf288N6sJA5BRb6FJI\nGKFJpEcwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV\nBAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAMHAwfXZ5/PWMAwGA1UdEwQF\nMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHHFwl0tH0quUYZYO0dZYt4R7SJ0pCm2\n2satiyzHl4OnXcHDpekAo7/a09c6Lz6AU83cKy/+x3/djYHXWba7HpEu0dR3ugQP\nMlr4zrhd9xKZ0KZKiYmtJH+ak4OM4L3FbT0owUZPyjLSlhMtJVcoRp5CJsjAMBUG\nSvD8RX+T01wzox/Qb+lnnNnOlaWpqu8eoOenybxKp1a9ULzIVvN/LAcc+14vioFq\n2swRWtmocBAs8QR9n4uvbpiYvS8eYueDCWMM4fvFfBhaDZ3N9IbtySh3SpFdQDhw\nYbjM2rxXiyLGxB4Bol7QTv4zHif7Zt89FReT/NBy4rzaskDJY5L6xmY=\n-----END CERTIFICATE-----\n" }, "tls-certificates-and-hostnames_certificate-2": { "description": "The zone's SSL certificate or SSL certificate and intermediate(s).", "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIDtTCCAp2gAwIBAgIJAM15n7fdxhRtMA0GCSqGSIb3DQEBBQUAMEUxCzAJBgNV\nBAYTAlVTMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX\naWRnaXRzIFB0eSBMdGQwHhcNMTQwMzExMTkyMTU5WhcNMTQwNDEwMTkyMTU5WjBF\nMQswCQYDVQQGEwJVUzETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAvq3sKsHpeduJHimOK+fvQdKsI8z8A05MZyyLp2/R/GE8FjNv+hkVY1WQ\nLIyTNNQH7CJecE1nbTfo8Y56S7x/rhxC6/DJ8MIulapFPnorq46KU6yRxiM0MQ3N\nnTJHlHA2ozZta6YBBfVfhHWl1F0IfNbXCLKvGwWWMbCx43OfW6KTkbRnE6gFWKuO\nfSO5h2u5TaWVuSIzBvYs7Vza6m+gtYAvKAJV2nSZ+eSEFPDo29corOy8+huEOUL8\n5FAw4BFPsr1TlrlGPFitduQUHGrSL7skk1ESGza0to3bOtrodKei2s9bk5MXm7lZ\nqI+WZJX4Zu9+mzZhc9pCVi8r/qlXuQIDAQABo4GnMIGkMB0GA1UdDgQWBBRvavf+\nsWM4IwKiH9X9w1vl6nUVRDB1BgNVHSMEbjBsgBRvavf+sWM4IwKiH9X9w1vl6nUV\nRKFJpEcwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV\nBAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAM15n7fdxhRtMAwGA1UdEwQF\nMAMBAf8wDQYJKoZIhvcNAQEFBQADggEBABY2ZzBaW0dMsAAT7tPJzrVWVzQx6KU4\nUEBLudIlWPlkAwTnINCWR/8eNjCCmGA4heUdHmazdpPa8RzwOmc0NT1NQqzSyktt\nvTqb4iHD7+8f9MqJ9/FssCfTtqr/Qst/hGH4Wmdf1EJ/6FqYAAb5iRlPgshFZxU8\nuXtA8hWn6fK6eISD9HBdcAFToUvKNZ1BIDPvh9f95Ine8ar6yGd56TUNrHR8eHBs\nESxz5ddVR/oWRysNJ+aGAyYqHS8S/ttmC7r4XCAHqXptkHPCGRqkAhsterYhd4I8\n/cBzejUobNCjjHFbtkAL/SjxZOLW+pNkZwfeYdM8iPkD54Uua1v2tdw=\n-----END CERTIFICATE-----" }, "tls-certificates-and-hostnames_certificate-3": { "description": "The root CA certificate in PEM format. Only root CA certificates are accepted; intermediate and leaf certificates are not supported.", "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIDdjCCAl6gAwIBAgIJAPnMg0Fs+/B0MA0GCSqGSIb3DQEBCwUAMFsx...\n-----END CERTIFICATE-----\n" }, "tls-certificates-and-hostnames_certificate-4": { "description": "The Origin CA certificate. Will be newline-encoded.", "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCVVMxDTALBgNVBAgMBFV0YWgxDzANBgNV\nBAcMBkxpbmRvbjEWMBQGA1UECgwNRGlnaUNlcnQgSW5jLjERMA8GA1UECwwIRGln\naUNlcnQxHTAbBgNVBAMMFGV4YW1wbGUuZGlnaWNlcnQuY29tMIIBIjANBgkqhkiG\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEA8+To7d+2kPWeBv/orU3LVbJwDrSQbeKamCmo\nwp5bqDxIwV20zqRb7APUOKYoVEFFOEQs6T6gImnIolhbiH6m4zgZ/CPvWBOkZc+c\n1Po2EmvBz+AD5sBdT5kzGQA6NbWyZGldxRthNLOs1efOhdnWFuhI162qmcflgpiI\nWDuwq4C9f+YkeJhNn9dF5+owm8cOQmDrV8NNdiTqin8q3qYAHHJRW28glJUCZkTZ\nwIaSR6crBQ8TbYNE0dc+Caa3DOIkz1EOsHWzTx+n0zKfqcbgXi4DJx+C1bjptYPR\nBPZL8DAeWuA8ebudVT44yEp82G96/Ggcf7F33xMxe0yc+Xa6owIDAQABoAAwDQYJ\nKoZIhvcNAQEFBQADggEBAB0kcrFccSmFDmxox0Ne01UIqSsDqHgL+XmHTXJwre6D\nhJSZwbvEtOK0G3+dr4Fs11WuUNt5qcLsx5a8uk4G6AKHMzuhLsJ7XZjgmQXGECpY\nQ4mC3yT3ZoCGpIXbw+iP3lmEEXgaQL0Tx5LFl/okKbKYwIqNiyKWOMj7ZR/wxWg/\nZDGRs55xuoeLDJ/ZRFf9bI+IaCUd1YrfYcHIl3G87Av+r49YVwqRDT0VDV7uLgqn\n29XI1PpVUNCPQGn9p/eX6Qo7vpDaPybRtA2R7XLKjQaF9oXWeCUqy1hvJac9QFO2\n97Ob1alpHPoZ7mWiEuJwjBPii6a9M9G30nUo39lBi1w=\n-----END CERTIFICATE-----", "readOnly": true }, "tls-certificates-and-hostnames_certificate-5": { "description": "The zone's leaf certificate.", "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIDtTCCAp2gAwIBAgIJAMHAwfXZ5/PWMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\nBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX\naWRnaXRzIFB0eSBMdGQwHhcNMTYwODI0MTY0MzAxWhcNMTYxMTIyMTY0MzAxWjBF\nMQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmGdtcGbg/1\nCGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKnabIRuGvB\nKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpidtnKX/a+5\n0GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+pyFxIXjbEI\ndZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pEewooaeO2\nizNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABo4GnMIGkMB0GA1UdDgQWBBT/LbE4\n9rWf288N6sJA5BRb6FJIGDB1BgNVHSMEbjBsgBT/LbE49rWf288N6sJA5BRb6FJI\nGKFJpEcwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV\nBAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAMHAwfXZ5/PWMAwGA1UdEwQF\nMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHHFwl0tH0quUYZYO0dZYt4R7SJ0pCm2\n2satiyzHl4OnXcHDpekAo7/a09c6Lz6AU83cKy/+x3/djYHXWba7HpEu0dR3ugQP\nMlr4zrhd9xKZ0KZKiYmtJH+ak4OM4L3FbT0owUZPyjLSlhMtJVcoRp5CJsjAMBUG\nSvD8RX+T01wzox/Qb+lnnNnOlaWpqu8eoOenybxKp1a9ULzIVvN/LAcc+14vioFq\n2swRWtmocBAs8QR9n4uvbpiYvS8eYueDCWMM4fvFfBhaDZ3N9IbtySh3SpFdQDhw\nYbjM2rxXiyLGxB4Bol7QTv4zHif7Zt89FReT/NBy4rzaskDJY5L6xmY=\n-----END CERTIFICATE-----\n", "x-stainless-terraform": { "normalize_newlines": true } }, "tls-certificates-and-hostnames_certificate-6": { "description": "The hostname certificate.", "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIDtTCCAp2gAwIBAgIJAMHAwfXZ5/PWMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\nBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX\naWRnaXRzIFB0eSBMdGQwHhcNMTYwODI0MTY0MzAxWhcNMTYxMTIyMTY0MzAxWjBF\nMQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmGdtcGbg/1\nCGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKnabIRuGvB\nKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpidtnKX/a+5\n0GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+pyFxIXjbEI\ndZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pEewooaeO2\nizNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABo4GnMIGkMB0GA1UdDgQWBBT/LbE4\n9rWf288N6sJA5BRb6FJIGDB1BgNVHSMEbjBsgBT/LbE49rWf288N6sJA5BRb6FJI\nGKFJpEcwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV\nBAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAMHAwfXZ5/PWMAwGA1UdEwQF\nMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHHFwl0tH0quUYZYO0dZYt4R7SJ0pCm2\n2satiyzHl4OnXcHDpekAo7/a09c6Lz6AU83cKy/+x3/djYHXWba7HpEu0dR3ugQP\nMlr4zrhd9xKZ0KZKiYmtJH+ak4OM4L3FbT0owUZPyjLSlhMtJVcoRp5CJsjAMBUG\nSvD8RX+T01wzox/Qb+lnnNnOlaWpqu8eoOenybxKp1a9ULzIVvN/LAcc+14vioFq\n2swRWtmocBAs8QR9n4uvbpiYvS8eYueDCWMM4fvFfBhaDZ3N9IbtySh3SpFdQDhw\nYbjM2rxXiyLGxB4Bol7QTv4zHif7Zt89FReT/NBy4rzaskDJY5L6xmY=\n-----END CERTIFICATE-----\n", "x-stainless-terraform": { "normalize_newlines": true } }, "tls-certificates-and-hostnames_certificate-7": { "description": "The Client Certificate PEM.", "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIDmDCCAoC...dhDDE\n-----END CERTIFICATE-----", "readOnly": true }, "tls-certificates-and-hostnames_certificateObject": { "type": "object", "properties": { "certificate": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate-5" }, "expires_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_expires_on-4" }, "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "issuer": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_issuer" }, "signature": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_signature" }, "status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status-8" }, "uploaded_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_uploaded_on-2" } } }, "tls-certificates-and-hostnames_certificateObject-2": { "type": "object", "properties": { "certificate": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate-6" }, "expires_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_expires_on-5" }, "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "issuer": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_issuer" }, "serial_number": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_serial_number" }, "signature": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_signature" }, "status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status-9" }, "uploaded_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_uploaded_on-3" } } }, "tls-certificates-and-hostnames_certificateObject-3": { "type": "object", "properties": { "ca": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ca" }, "certificates": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificates-2" }, "expires_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_expires_on-2" }, "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "issuer": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_issuer-2" }, "name": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_name-2" }, "serial_number": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_serial_number-2" }, "signature": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_signature" }, "type": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_type-3" }, "uploaded_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_uploaded_on-4" } } }, "tls-certificates-and-hostnames_certificateObjectPost": { "type": "object", "properties": { "ca": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ca" }, "certificates": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificates-2" }, "expires_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_expires_on-2" }, "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "issuer": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_issuer-2" }, "name": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_name-2" }, "serial_number": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_serial_number-2" }, "signature": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_signature" }, "type": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_type-3" }, "updated_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_updated_at-4" }, "uploaded_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_uploaded_on-4" } } }, "tls-certificates-and-hostnames_certificate_analyze_response": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_authority": { "description": "The Certificate Authority that will issue the certificate.", "type": "string", "example": "google", "enum": [ "digicert", "google", "lets_encrypt", "ssl_com" ], "x-auditable": true }, "tls-certificates-and-hostnames_certificate_authority-2": { "description": "Certificate Authority selected for the order. For information on any certificate authority specific details or restrictions [see this page for more details](https://developers.cloudflare.com/ssl/reference/certificate-authorities).", "type": "string", "example": "lets_encrypt", "enum": [ "google", "lets_encrypt", "ssl_com" ], "x-auditable": true }, "tls-certificates-and-hostnames_certificate_authority-3": { "description": "The Certificate Authority that Total TLS certificates will be issued through.", "type": "string", "example": "google", "enum": [ "google", "lets_encrypt", "ssl_com" ], "x-auditable": true }, "tls-certificates-and-hostnames_certificate_authority-4": { "description": "Certificate Authority used to issue the Client Certificate.", "type": "object", "properties": { "id": { "type": "string", "example": "568b6b74-7b0c-4755-8840-4e3b8c24adeb", "x-auditable": true }, "name": { "type": "string", "example": "Cloudflare Managed CA for account", "x-auditable": true } } }, "tls-certificates-and-hostnames_certificate_pack": { "description": "A certificate pack with all its properties.", "type": "object", "properties": { "certificate_authority": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_authority-2" }, "certificates": { "description": "Array of certificates in this pack.", "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_pack_certificate" } }, "cloudflare_branding": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_cloudflare_branding" }, "dcv_delegation_records": { "description": "DCV Delegation records for domain validation.", "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_validation_record" }, "readOnly": true }, "hosts": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hosts-2" }, "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "primary_certificate": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_primary" }, "status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status-5" }, "type": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_type-2" }, "validation_errors": { "description": "Domain validation errors that have been received by the certificate authority (CA).", "type": "array", "items": { "properties": { "message": { "description": "A domain validation error.", "type": "string", "example": "SERVFAIL looking up CAA for app.example.com", "x-auditable": true } }, "type": "object" } }, "validation_method": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_validation_method" }, "validation_records": { "description": "Certificates' validation records.", "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_validation_record" } }, "validity_days": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_validity_days" } }, "required": [ "id", "type", "hosts", "certificates", "status" ] }, "tls-certificates-and-hostnames_certificate_pack_certificate": { "description": "An individual certificate within a certificate pack.", "type": "object", "properties": { "bundle_method": { "description": "Certificate bundle method.", "type": "string", "example": "ubiquitous", "x-auditable": true }, "expires_on": { "description": "When the certificate from the authority expires.", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z", "x-auditable": true }, "geo_restrictions": { "description": "Specify the region where your private key can be held locally.", "type": "object", "properties": { "label": { "type": "string", "example": "us", "enum": [ "us", "eu", "highest_security" ], "x-auditable": true } } }, "hosts": { "description": "Hostnames covered by this certificate.", "type": "array", "items": { "type": "string" }, "example": [ "example.com", "*.example.com" ], "x-auditable": true }, "id": { "description": "Certificate identifier.", "type": "string", "example": "7e7b8deba8538af625850b7b2530034c", "x-auditable": true }, "issuer": { "description": "The certificate authority that issued the certificate.", "type": "string", "example": "Let's Encrypt", "x-auditable": true }, "modified_on": { "description": "When the certificate was last modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00Z", "x-auditable": true }, "priority": { "description": "The order/priority in which the certificate will be used.", "type": "number", "x-auditable": true }, "signature": { "description": "The type of hash used for the certificate.", "type": "string", "example": "ECDSAWithSHA256", "x-auditable": true }, "status": { "description": "Certificate status.", "type": "string", "example": "active", "x-auditable": true }, "uploaded_on": { "description": "When the certificate was uploaded to Cloudflare.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00Z", "x-auditable": true }, "zone_id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, "required": [ "id", "hosts", "status" ] }, "tls-certificates-and-hostnames_certificate_pack_quota_response": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "advanced": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_quota" } } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_pack_response_collection": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_pack" } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_pack_response_single": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_pack" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_response_collection": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom-certificate" } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_response_collection-2": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificates" } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_response_collection-3": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_zone-authenticated-origin-pull" } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_response_collection-4": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificateObject-2" } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_response_collection-5": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificateObject-3" } } }, "type": "object" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "type": "number", "example": 1 }, "page": { "type": "number", "example": 1 }, "per_page": { "type": "number", "example": 50 }, "total_count": { "type": "number", "example": 1 }, "total_pages": { "description": "Total pages available of results.", "type": "number", "example": 1 } } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_response_id_only": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_response_single": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom-certificate" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_response_single-2": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificates" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_response_single-3": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_zone-authenticated-origin-pull" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_response_single-4": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificateObject-2" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_response_single-5": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificateObject-3" } ] } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_response_single_post": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificateObjectPost" } ] } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_revoke_response": { "allOf": [ { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "revoked_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_revoked_at" } } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_certificate_status": { "description": "Current status of certificate.", "type": "string", "example": "active", "enum": [ "initializing", "authorizing", "active", "expired", "issuing", "timing_out", "pending_deployment" ], "x-auditable": true }, "tls-certificates-and-hostnames_certificates": { "type": "object", "properties": { "certificate": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate-4" }, "csr": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_csr" }, "expires_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_expires_on-3" }, "hostnames": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostnames" }, "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "request_type": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_request_type" }, "requested_validity": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_requested_validity" } }, "required": [ "hostnames", "csr", "requested_validity", "request_type" ] }, "tls-certificates-and-hostnames_certificates-2": { "description": "The uploaded root CA certificate.", "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIDmDCCAoCgAwIBAgIUKTOAZNjcXVZRj4oQt0SHsl1c1vMwDQYJKoZIhvcNAQEL\nBQAwUTELMAkGA1UEBhMCVVMxFjAUBgNVBAgMDVNhbiBGcmFuY2lzY28xEzARBgNV\nBAcMCkNhbGlmb3JuaWExFTATBgNVBAoMDEV4YW1wbGUgSW5jLjAgFw0yMjExMjIx\nNjU5NDdaGA8yMTIyMTAyOTE2NTk0N1owUTELMAkGA1UEBhMCVVMxFjAUBgNVBAgM\nDVNhbiBGcmFuY2lzY28xEzARBgNVBAcMCkNhbGlmb3JuaWExFTATBgNVBAoMDEV4\nYW1wbGUgSW5jLjCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMRcORwg\nJFTdcG/2GKI+cFYiOBNDKjCZUXEOvXWY42BkH9wxiMT869CO+enA1w5pIrXow6kC\nM1sQspHHaVmJUlotEMJxyoLFfA/8Kt1EKFyobOjuZs2SwyVyJ2sStvQuUQEosULZ\nCNGZEqoH5g6zhMPxaxm7ZLrrsDZ9maNGVqo7EWLWHrZ57Q/5MtTrbxQL+eXjUmJ9\nK3kS+3uEwMdqR6Z3BluU1ivanpPc1CN2GNhdO0/hSY4YkGEnuLsqJyDd3cIiB1Mx\nuCBJ4ZaqOd2viV1WcP3oU3dxVPm4MWyfYIldMWB14FahScxLhWdRnM9YZ/i9IFcL\nypXsuz7DjrJPtPUCAwEAAaNmMGQwHQYDVR0OBBYEFP5JzLUawNF+c3AXsYTEWHh7\nz2czMB8GA1UdIwQYMBaAFP5JzLUawNF+c3AXsYTEWHh7z2czMA4GA1UdDwEB/wQE\nAwIBBjASBgNVHRMBAf8ECDAGAQH/AgEBMA0GCSqGSIb3DQEBCwUAA4IBAQBc+Be7\nNDhpE09y7hLPZGRPl1cSKBw4RI0XIv6rlbSTFs5EebpTGjhx/whNxwEZhB9HZ711\n1Oa1YlT8xkI9DshB78mjAHCKBAJ76moK8tkG0aqdYpJ4ZcJTVBB7l98Rvgc7zfTi\ni7WemTy72deBbSeiEtXavm4EF0mWjHhQ5Nxpnp00Bqn5g1x8CyTDypgmugnep+xG\n+iFzNmTdsz7WI9T/7kDMXqB7M/FPWBORyS98OJqNDswCLF8bIZYwUBEe+bRHFomo\nShMzaC3tvim7WCb16noDkSTMlfKO4pnvKhpcVdSgwcruATV7y+W+Lvmz2OT/Gui4\nJhqeoTewsxndhDDE\n-----END CERTIFICATE-----" }, "tls-certificates-and-hostnames_client_certificate": { "type": "object", "properties": { "certificate": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate-7" }, "certificate_authority": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_authority-4" }, "common_name": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_common_name" }, "country": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_country" }, "csr": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_csr-2" }, "expires_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_expired_on" }, "fingerprint_sha256": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_fingerprint_sha256" }, "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "issued_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_issued_on" }, "location": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_location" }, "organization": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_organization" }, "organizational_unit": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_organizational_unit" }, "serial_number": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_serial_number-3" }, "signature": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_signature-3" }, "ski": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ski" }, "state": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_state" }, "status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status-11" }, "validity_days": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_validity_days-2" } } }, "tls-certificates-and-hostnames_client_certificate_response_collection": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_client_certificate" } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_client_certificate_response_single": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_client_certificate" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_cloudflare_branding": { "description": "Whether or not to add Cloudflare Branding for the order. This will add a subdomain of sni.cloudflaressl.com as the Common Name if set to true.", "type": "boolean", "example": false, "x-auditable": true }, "tls-certificates-and-hostnames_common_name": { "description": "Common Name of the Client Certificate.", "type": "string", "example": "Cloudflare", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_config": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname_certid_input" } }, "tls-certificates-and-hostnames_country": { "description": "Country, provided by the CSR.", "type": "string", "example": "US", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_created_at": { "description": "This is the time the hostname was created.", "type": "string", "format": "date-time", "example": "2020-02-06T18:11:23.531995Z", "x-auditable": true }, "tls-certificates-and-hostnames_created_at-2": { "description": "This is the time the fallback origin was created.", "type": "string", "format": "date-time", "example": "2019-10-28T18:11:23.37411Z", "x-auditable": true }, "tls-certificates-and-hostnames_created_at-3": { "description": "The time when the certificate was created.", "type": "string", "format": "date-time", "example": "2100-01-01T05:20:00Z", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_created_at-4": { "description": "This is the time the tls setting was originally created for this hostname.", "type": "string", "format": "date-time", "example": "2023-07-10T20:01:50.219171Z", "x-auditable": true }, "tls-certificates-and-hostnames_csr": { "description": "The Certificate Signing Request (CSR). Must be newline-encoded.", "type": "string", "example": "-----BEGIN CERTIFICATE REQUEST-----\nMIICxzCCAa8CAQAwSDELMAkGA1UEBhMCVVMxFjAUBgNVBAgTDVNhbiBGcmFuY2lz\nY28xCzAJBgNVBAcTAkNBMRQwEgYDVQQDEwtleGFtcGxlLm5ldDCCASIwDQYJKoZI\nhvcNAQEBBQADggEPADCCAQoCggEBALxejtu4b+jPdFeFi6OUsye8TYJQBm3WfCvL\nHu5EvijMO/4Z2TImwASbwUF7Ir8OLgH+mGlQZeqyNvGoSOMEaZVXcYfpR1hlVak8\n4GGVr+04IGfOCqaBokaBFIwzclGZbzKmLGwIQioNxGfqFm6RGYGA3be2Je2iseBc\nN8GV1wYmvYE0RR+yWweJCTJ157exyRzu7sVxaEW9F87zBQLyOnwXc64rflXslRqi\ng7F7w5IaQYOl8yvmk/jEPCAha7fkiUfEpj4N12+oPRiMvleJF98chxjD4MH39c5I\nuOslULhrWunfh7GB1jwWNA9y44H0snrf+xvoy2TcHmxvma9Eln8CAwEAAaA6MDgG\nCSqGSIb3DQEJDjErMCkwJwYDVR0RBCAwHoILZXhhbXBsZS5uZXSCD3d3dy5leGFt\ncGxlLm5ldDANBgkqhkiG9w0BAQsFAAOCAQEAcBaX6dOnI8ncARrI9ZSF2AJX+8mx\npTHY2+Y2C0VvrVDGMtbBRH8R9yMbqWtlxeeNGf//LeMkSKSFa4kbpdx226lfui8/\nauRDBTJGx2R1ccUxmLZXx4my0W5iIMxunu+kez+BDlu7bTT2io0uXMRHue4i6quH\nyc5ibxvbJMjR7dqbcanVE10/34oprzXQsJ/VmSuZNXtjbtSKDlmcpw6To/eeAJ+J\nhXykcUihvHyG4A1m2R6qpANBjnA0pHexfwM/SgfzvpbvUg0T1ubmer8BgTwCKIWs\ndcWYTthM51JIqRBfNqy4QcBnX+GY05yltEEswQI55wdiS3CjTTA67sdbcQ==\n-----END CERTIFICATE REQUEST-----" }, "tls-certificates-and-hostnames_csr-2": { "description": "The Certificate Signing Request (CSR). Must be newline-encoded.", "type": "string", "example": "-----BEGIN CERTIFICATE REQUEST-----\nMIICY....\n-----END CERTIFICATE REQUEST-----", "x-auditable": true }, "tls-certificates-and-hostnames_ct_alerting_emails": { "description": "Email addresses that receive CT alert notifications for the zone. A maximum of 100 addresses may be configured. Each address must be a valid RFC 5322 email address and must not contain a comma.\n", "type": "array", "items": { "format": "email", "type": "string" }, "example": [ "security@example.com", "admin@example.com" ], "maxItems": 100 }, "tls-certificates-and-hostnames_ct_alerting_enabled": { "description": "Whether CT alerting is enabled for the zone.", "type": "boolean", "example": true, "x-auditable": true }, "tls-certificates-and-hostnames_ct_alerting_subscription": { "description": "Certificate Transparency alerting subscription settings for a zone.", "type": "object", "properties": { "emails": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ct_alerting_emails" }, "enabled": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ct_alerting_enabled" } }, "required": [ "enabled" ] }, "tls-certificates-and-hostnames_ct_alerting_subscription_response_single": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ct_alerting_subscription" } ] } }, "type": "object" } ] }, "tls-certificates-and-hostnames_ct_alerting_subscription_update": { "description": "Request body for updating CT alerting subscription settings.", "type": "object", "properties": { "emails": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ct_alerting_emails" }, "enabled": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ct_alerting_enabled" } }, "additionalProperties": false, "required": [ "enabled" ] }, "tls-certificates-and-hostnames_custom-certificate": { "type": "object", "properties": { "bundle_method": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_bundle_method" }, "custom_csr_id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_id" }, "expires_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_expires_on" }, "geo_restrictions": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_geo_restrictions" }, "hosts": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hosts" }, "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "issuer": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_issuer" }, "keyless_server": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless-certificate" }, "modified_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_modified_on" }, "policy_restrictions": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_policy_restrictions" }, "priority": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_priority" }, "signature": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_signature" }, "status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status" }, "uploaded_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_uploaded_on" }, "zone_id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } }, "required": [ "id", "zone_id" ] }, "tls-certificates-and-hostnames_custom-hostname": { "type": "object", "properties": { "hostname": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname" }, "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "ssl": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ssl" } }, "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_customhostname" } ], "required": [ "id", "hostname" ] }, "tls-certificates-and-hostnames_custom-trust-store": { "type": "object", "properties": { "certificate": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate-3" }, "expires_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_expires_on-2" }, "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "issuer": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_issuer" }, "signature": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_signature" }, "status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status-7" }, "updated_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_updated_at-2" }, "uploaded_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_uploaded_on" } }, "required": [ "id", "status", "issuer", "signature", "certificate", "expires_on", "uploaded_on", "updated_at" ] }, "tls-certificates-and-hostnames_custom_cert_and_key": { "type": "object", "properties": { "custom_certificate": { "description": "If a custom uploaded certificate is used.", "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIDdjCCAl6gAwIBAgIJAPnMg0Fs+/B0MA0GCSqGSIb3DQEBCwUAMFsx...\n-----END CERTIFICATE-----\n" }, "custom_key": { "description": "The key for a custom uploaded certificate.", "type": "string", "example": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC/SCB5...\n-----END PRIVATE KEY-----\n", "x-sensitive": true } }, "required": [ "custom_certificate", "custom_key" ] }, "tls-certificates-and-hostnames_custom_cert_bundle": { "description": "Array of custom certificate and key pairs (1 or 2 pairs allowed).", "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_cert_and_key" }, "maxItems": 2, "minItems": 1 }, "tls-certificates-and-hostnames_custom_csr": { "description": "A custom Certificate Signing Request (CSR).", "type": "object", "properties": { "common_name": { "description": "The common name (domain) for the CSR.", "type": "string", "example": "example.com", "maxLength": 64, "x-auditable": true }, "country": { "description": "Two-letter ISO 3166-1 alpha-2 country code.", "type": "string", "example": "US", "x-auditable": true }, "created_at": { "description": "When the CSR was created.", "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z", "readOnly": true, "x-auditable": true }, "csr": { "description": "The PEM-encoded Certificate Signing Request.", "type": "string", "example": "-----BEGIN CERTIFICATE REQUEST-----\nMIICYzCCAUsCAQAwHj...", "readOnly": true, "x-auditable": true }, "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_identifier" }, "key_type": { "description": "The key algorithm used to generate the CSR.", "type": "string", "example": "rsa2048", "enum": [ "rsa2048", "p256v1" ], "x-auditable": true }, "locality": { "description": "City or locality name.", "type": "string", "example": "San Francisco", "x-auditable": true }, "organization": { "description": "Organization name.", "type": "string", "example": "Cloudflare, Inc.", "x-auditable": true }, "organizational_unit": { "description": "Organizational unit for the CSR subject.", "type": "string", "example": "Engineering", "x-auditable": true }, "sans": { "description": "Subject Alternative Names included in the CSR.", "type": "array", "items": { "type": "string" }, "example": [ "example.com", "www.example.com" ], "x-auditable": true }, "state": { "description": "State or province name.", "type": "string", "example": "California", "x-auditable": true } }, "required": [ "id", "key_type", "created_at" ] }, "tls-certificates-and-hostnames_custom_csr-2": { "description": "A custom Certificate Signing Request (CSR).", "type": "object", "properties": { "account_tag": { "description": "Account identifier associated with this CSR.", "type": "string", "example": "23e087bd19bc1d40ae95b6f297263ceb", "readOnly": true, "x-auditable": true }, "common_name": { "description": "The common name (domain) for the CSR.", "type": "string", "example": "example.com", "maxLength": 64, "x-auditable": true }, "country": { "description": "Two-letter ISO 3166-1 alpha-2 country code.", "type": "string", "example": "US", "x-auditable": true }, "created_at": { "description": "When the CSR was created.", "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z", "readOnly": true, "x-auditable": true }, "csr": { "description": "The PEM-encoded Certificate Signing Request.", "type": "string", "example": "-----BEGIN CERTIFICATE REQUEST-----\nMIICYzCCAUsCAQAwHj...", "readOnly": true, "x-auditable": true }, "description": { "description": "Optional description for the CSR.", "type": "string", "example": "CSR for example.com wildcard", "x-auditable": true }, "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_identifier" }, "key_type": { "description": "The key algorithm used to generate the CSR.", "type": "string", "example": "rsa2048", "enum": [ "rsa2048", "p256v1" ], "x-auditable": true }, "locality": { "description": "City or locality name.", "type": "string", "example": "San Francisco", "x-auditable": true }, "name": { "description": "Human-readable name for the CSR.", "type": "string", "example": "My Custom CSR", "x-auditable": true }, "organization": { "description": "Organization name.", "type": "string", "example": "Cloudflare, Inc.", "x-auditable": true }, "organizational_unit": { "description": "Organizational unit name.", "type": "string", "example": "Engineering", "x-auditable": true }, "sans": { "description": "Subject Alternative Names included in the CSR.", "type": "array", "items": { "type": "string" }, "example": [ "example.com", "www.example.com" ], "x-auditable": true }, "state": { "description": "State or province name.", "type": "string", "example": "California", "x-auditable": true } }, "required": [ "id", "key_type", "created_at" ] }, "tls-certificates-and-hostnames_custom_csr_create_request": { "description": "Request body for creating a custom CSR.", "type": "object", "properties": { "common_name": { "description": "The common name (domain) for the CSR. Must be at most 64 characters.", "type": "string", "example": "example.com", "maxLength": 64 }, "country": { "description": "Two-letter ISO 3166-1 alpha-2 country code.", "type": "string", "example": "US" }, "key_type": { "description": "Key algorithm to use for the CSR. Defaults to rsa2048 if not specified.", "type": "string", "example": "rsa2048", "default": "rsa2048", "enum": [ "rsa2048", "p256v1" ] }, "locality": { "description": "City or locality name.", "type": "string", "example": "San Francisco" }, "organization": { "description": "Organization name.", "type": "string", "example": "Cloudflare, Inc." }, "organizational_unit": { "description": "Organizational unit name.", "type": "string", "example": "Engineering" }, "sans": { "description": "Subject Alternative Names for the CSR. At least one SAN is required. The list should include the common name.", "type": "array", "items": { "maxLength": 256, "type": "string" }, "example": [ "example.com", "www.example.com" ], "maxItems": 150, "minItems": 1 }, "state": { "description": "State or province name.", "type": "string", "example": "California" } }, "required": [ "country", "state", "locality", "organization", "common_name", "sans" ] }, "tls-certificates-and-hostnames_custom_csr_create_request-2": { "description": "Request body for creating a custom CSR.", "type": "object", "properties": { "common_name": { "description": "The common name (domain) for the CSR. Must be at most 64 characters.", "type": "string", "example": "example.com", "maxLength": 64 }, "country": { "description": "Two-letter ISO 3166-1 alpha-2 country code.", "type": "string", "example": "US" }, "description": { "description": "Optional description for the CSR.", "type": "string", "example": "CSR for example.com wildcard" }, "key_type": { "description": "Key algorithm to use for the CSR. Defaults to rsa2048 if not specified.", "type": "string", "example": "rsa2048", "default": "rsa2048", "enum": [ "rsa2048", "p256v1" ] }, "locality": { "description": "City or locality name.", "type": "string", "example": "San Francisco" }, "name": { "description": "Human-readable name for the CSR.", "type": "string", "example": "My Custom CSR" }, "organization": { "description": "Organization name.", "type": "string", "example": "Cloudflare, Inc." }, "organizational_unit": { "description": "Organizational unit name.", "type": "string", "example": "Engineering" }, "sans": { "description": "Subject Alternative Names for the CSR. At least one SAN is required.", "type": "array", "items": { "maxLength": 256, "type": "string" }, "example": [ "example.com", "www.example.com" ], "maxItems": 150, "minItems": 1 }, "state": { "description": "State or province name.", "type": "string", "example": "California" } }, "required": [ "country", "state", "locality", "organization", "common_name", "sans" ] }, "tls-certificates-and-hostnames_custom_csr_id": { "description": "The identifier for the Custom CSR that was used.", "type": "string", "example": "7b163417-1d2b-4c84-a38a-2fb7a0cd7752", "x-auditable": true }, "tls-certificates-and-hostnames_custom_csr_identifier": { "description": "Custom CSR identifier tag.", "type": "string", "example": "7b163417-1d2b-4c84-a38a-2fb7a0cd7752", "maxLength": 36, "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_custom_csr_response_collection": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr" } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_custom_csr_response_collection-2": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr-2" } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_custom_csr_response_id_only": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr_identifier" } } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_custom_csr_response_single": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_custom_csr_response_single-2": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_csr-2" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_custom_hostname_api_response_common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_messages" }, "messages": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_response_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "tls-certificates-and-hostnames_custom_hostname_api_response_failure": { "type": "object", "properties": { "errors": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_messages" }, { "example": [ { "code": 7003, "message": "No route for the URI" } ], "items": { "type": "object" }, "minItems": 1, "type": "array" } ] }, "messages": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_response_messages" }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "tls-certificates-and-hostnames_custom_hostname_quota": { "type": "object", "properties": { "allocated": { "description": "The allocated custom hostname quota.", "type": "integer", "format": "int64", "example": 100, "x-auditable": true }, "exceeded": { "description": "Whether the current usage has exceeded the allocated quota.", "type": "boolean", "example": false, "x-auditable": true }, "hard_cap": { "description": "The maximum number of custom hostnames allowed before create requests are rejected.", "type": "integer", "format": "int64", "example": 200, "x-auditable": true }, "used": { "description": "The number of custom hostnames currently in use.", "type": "integer", "format": "int64", "example": 50, "x-auditable": true } }, "required": [ "allocated", "used", "exceeded", "hard_cap" ] }, "tls-certificates-and-hostnames_custom_hostname_quota_response": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_api_response_common" }, { "properties": { "result": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_quota" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_custom_hostname_response_collection": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_api_response_common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom-hostname" } }, "result_info": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_result_info" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_custom_hostname_response_messages": { "description": "Informational messages returned by the custom hostname API.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [] }, "tls-certificates-and-hostnames_custom_hostname_response_single": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_hostname_api_response_common" }, { "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom-hostname" } ] } }, "type": "object" } ] }, "tls-certificates-and-hostnames_custom_metadata": { "description": "Unique key/value metadata for this hostname. These are per-hostname (customer) settings.", "type": "object", "additionalProperties": { "type": "string", "x-auditable": true } }, "tls-certificates-and-hostnames_custom_origin_server": { "description": "a valid hostname that’s been added to your DNS zone as an A, AAAA, or CNAME record.", "type": "string", "example": "origin2.example.com", "x-auditable": true }, "tls-certificates-and-hostnames_custom_origin_sni": { "description": "A hostname that will be sent to your custom origin server as SNI for TLS handshake. This can be a valid subdomain of the zone or custom origin server name or the string ':request_host_header:' which will cause the host header in the request to be used as SNI. Not configurable with default/fallback origin server.", "type": "string", "example": "sni.example.com", "x-auditable": true }, "tls-certificates-and-hostnames_custom_trust_store_response_collection": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom-trust-store" } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_custom_trust_store_response_id_only": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_custom_trust_store_response_single": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom-trust-store" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_customhostname": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_created_at" }, "custom_metadata": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_metadata" }, "custom_origin_server": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_origin_server" }, "custom_origin_sni": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_origin_sni" }, "hostname": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname" }, "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "ownership_verification": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ownership_verification" }, "ownership_verification_http": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ownership_verification_http" }, "ssl": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_ssl" }, "status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status-3" }, "verification_errors": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_verification_errors" } } }, "tls-certificates-and-hostnames_dcv_delegation_response": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_uuidObject" } ] } }, "type": "object" } ] }, "tls-certificates-and-hostnames_delete_advanced_certificate_pack_response_single": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_deploy": { "description": "The environment to deploy the certificate to, defaults to production.", "type": "string", "example": "staging", "default": "production", "enum": [ "staging", "production" ], "x-auditable": true }, "tls-certificates-and-hostnames_enabled": { "description": "Whether or not the Keyless SSL is on or off.", "type": "boolean", "example": false, "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_enabled-2": { "description": "Disabling Universal SSL removes any currently active Universal SSL certificates for your zone from the edge and prevents any future Universal SSL certificates from being ordered. If there are no advanced certificates or custom certificates uploaded for the domain, visitors will be unable to access the domain over HTTPS.\n\nBy disabling Universal SSL, you understand that the following Cloudflare settings and preferences will result in visitors being unable to visit your domain unless you have uploaded a custom certificate or purchased an advanced certificate.\n\n* HSTS\n* Always Use HTTPS\n* Opportunistic Encryption\n* Onion Routing\n* Any Page Rules redirecting traffic to HTTPS\n\nSimilarly, any HTTP redirect to HTTPS at the origin while the Cloudflare proxy is enabled will result in users being unable to visit your site without a valid certificate at Cloudflare's edge.\n\nIf you do not have a valid custom or advanced certificate at Cloudflare's edge and are unsure if any of the above Cloudflare settings are enabled, or if any HTTP redirects exist at your origin, we advise leaving Universal SSL enabled for your domain.", "type": "boolean", "example": true, "x-auditable": true }, "tls-certificates-and-hostnames_enabled-3": { "description": "If enabled, Total TLS will order a hostname specific TLS certificate for any proxied A, AAAA, or CNAME record in your zone.", "type": "boolean", "example": true, "x-auditable": true }, "tls-certificates-and-hostnames_enabled-4": { "description": "Indicates whether zone-level authenticated origin pulls is enabled.", "type": "boolean", "example": true, "x-auditable": true }, "tls-certificates-and-hostnames_enabled-5": { "description": "Indicates whether hostname-level authenticated origin pulls is enabled. A null value voids the association.", "type": "boolean", "example": true, "nullable": true, "x-auditable": true }, "tls-certificates-and-hostnames_enabled_response": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "enabled": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_enabled-4" } } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_enabled_write": { "description": "Whether or not the Keyless SSL is on or off.", "type": "boolean", "example": false, "deprecated": true, "x-auditable": true }, "tls-certificates-and-hostnames_errors": { "description": "These are errors that were encountered while trying to activate a fallback origin.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "DNS records are not setup correctly. Origin should be a proxied A/AAAA/CNAME dns record" ] }, "tls-certificates-and-hostnames_expired_on": { "description": "Date that the Client Certificate expires.", "type": "string", "example": "2033-02-20T23:18:00Z", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_expires_on": { "description": "When the certificate from the authority expires.", "type": "string", "format": "date-time", "example": "2016-01-01T05:20:00Z", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_expires_on-2": { "description": "When the certificate expires.", "type": "string", "format": "date-time", "example": "2122-10-29T16:59:47Z", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_expires_on-3": { "description": "When the certificate will expire.", "type": "string", "example": "2014-01-01 05:20:00 +0000 UTC", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_expires_on-4": { "description": "When the certificate from the authority expires.", "type": "string", "format": "date-time", "example": "2100-01-01T05:20:00Z", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_expires_on-5": { "description": "The date when the certificate expires.", "type": "string", "format": "date-time", "example": "2100-01-01T05:20:00Z", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_fallback_origin_response": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_fallbackorigin" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_fallbackorigin": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_created_at-2" }, "errors": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_errors" }, "origin": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_origin" }, "status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status-4" }, "updated_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_updated_at" } } }, "tls-certificates-and-hostnames_fingerprint_sha256": { "description": "Unique identifier of the Client Certificate.", "type": "string", "example": "256c24690243359fb8cf139a125bd05ebf1d968b71e4caf330718e9f5c8a89ea", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_geo_restrictions": { "description": "Specify the region where your private key can be held locally for optimal TLS performance. HTTPS connections to any excluded data center will still be fully encrypted, but will incur some latency while Keyless SSL is used to complete the handshake with the nearest allowed data center. Options allow distribution to only to U.S. data centers, only to E.U. data centers, or only to highest security data centers. Default distribution is to all Cloudflare datacenters, for optimal performance.", "type": "object", "properties": { "label": { "type": "string", "example": "us", "enum": [ "us", "eu", "highest_security" ], "x-auditable": true } } }, "tls-certificates-and-hostnames_host": { "description": "The keyless SSL name.", "type": "string", "format": "hostname", "example": "example.com", "maxLength": 253, "x-auditable": true }, "tls-certificates-and-hostnames_hostname": { "description": "The custom hostname that will point to your hostname via CNAME.", "type": "string", "example": "app.example.com", "maxLength": 255, "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_hostname-2": { "description": "The hostname on the origin for which the client certificate uploaded will be used.", "type": "string", "example": "app.example.com", "maxLength": 255, "x-auditable": true }, "tls-certificates-and-hostnames_hostname-3": { "description": "The hostname for which the tls settings are set.", "type": "string", "example": "app.example.com", "x-auditable": true }, "tls-certificates-and-hostnames_hostname-authenticated-origin-pull": { "type": "object", "properties": { "cert_id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "certificate": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate-6" }, "enabled": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_enabled-5" }, "hostname": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname-2" }, "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "private_key": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_private_key-3" } }, "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname_certid_object" } ] }, "tls-certificates-and-hostnames_hostname_aop_response_collection": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname-authenticated-origin-pull" } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_hostname_aop_single_response": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname_certid_object" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_hostname_assoc_object": { "type": "object", "properties": { "cert_id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_cert_id" }, "created_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_created_at-3" }, "enabled": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_enabled-5" }, "hostname": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname-2" }, "status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status-9" }, "updated_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_updated_at-3" } } }, "tls-certificates-and-hostnames_hostname_assoc_response_collection": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname_assoc_object" } }, "result_info": { "type": "object", "properties": { "count": { "description": "Total results returned based on your search parameters.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 50 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 1 }, "total_pages": { "description": "Total pages available of results.", "type": "number", "example": 1 } } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_hostname_association": { "type": "object", "properties": { "hostnames": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostnames-2" }, "mtls_certificate_id": { "description": "The UUID for a certificate that was uploaded to the mTLS Certificate Management endpoint. If no mtls_certificate_id is given, the hostnames will be associated to your active Cloudflare Managed CA.", "type": "string", "maxLength": 36, "minLength": 36, "x-auditable": true } } }, "tls-certificates-and-hostnames_hostname_associations_response": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "hostnames": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostnames-2" } } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_hostname_certid_input": { "type": "object", "properties": { "cert_id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_cert_id" }, "enabled": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_enabled-5" }, "hostname": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname-2" } } }, "tls-certificates-and-hostnames_hostname_certid_object": { "type": "object", "properties": { "cert_id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "cert_status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status-9" }, "cert_updated_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_updated_at-3" }, "cert_uploaded_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_uploaded_on-3" }, "certificate": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate-6" }, "created_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_created_at-3" }, "enabled": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_enabled-5" }, "expires_on": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_expires_on-5" }, "hostname": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname-2" }, "issuer": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_issuer" }, "serial_number": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_serial_number" }, "signature": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_signature" }, "status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status-9" }, "updated_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_updated_at-3" } } }, "tls-certificates-and-hostnames_hostname_post": { "description": "The custom hostname that will point to your hostname via CNAME.", "type": "string", "example": "app.example.com", "maxLength": 255, "x-auditable": true }, "tls-certificates-and-hostnames_hostnames": { "description": "Array of hostnames or wildcard names bound to the certificate.\nHostnames must be fully qualified domain names (FQDNs) belonging to zones on your account (e.g., `example.com` or `sub.example.com`). Wildcards are supported only as a `*.` prefix for a single level (e.g., `*.example.com`). Double wildcards (`*.*.example.com`) and interior wildcards (`foo.*.example.com`) are not allowed. The wildcard suffix must be a multi-label domain (`*.example.com` is valid, but `*.com` is not). Unicode/IDN hostnames are accepted and automatically converted to punycode.", "type": "array", "items": { "minLength": 1, "type": "string", "x-auditable": true }, "example": [ "example.com", "*.example.com", "sub.example.com" ], "maxItems": 100, "minItems": 1 }, "tls-certificates-and-hostnames_hostnames-2": { "type": "array", "items": { "example": "api.example.com", "type": "string", "x-auditable": true } }, "tls-certificates-and-hostnames_hosts": { "type": "array", "items": { "description": "The valid hosts for the certificates.", "example": "example.com", "maxLength": 253, "readOnly": true, "type": "string", "x-auditable": true } }, "tls-certificates-and-hostnames_hosts-2": { "description": "Comma separated list of valid host names for the certificate packs. Must contain the zone apex, may not contain more than 50 hosts, and may not be empty.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "example.com", "*.example.com", "www.example.com" ], "x-stainless-collection-type": "set", "x-stainless-terraform-configurability": "computed_optional" }, "tls-certificates-and-hostnames_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "tls-certificates-and-hostnames_identifier-2": { "description": "Keyless certificate identifier tag.", "type": "string", "example": "4d2844d2ce78891c34d0b6c0535a291e", "maxLength": 32, "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_issued_on": { "description": "Date that the Client Certificate was issued by the Certificate Authority.", "type": "string", "example": "2023-02-23T23:18:00Z", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_issuer": { "description": "The certificate authority that issued the certificate.", "type": "string", "example": "GlobalSign", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_issuer-2": { "description": "The certificate authority that issued the certificate.", "type": "string", "example": "O=Example Inc.,L=California,ST=San Francisco,C=US", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_keyless-certificate": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_base" } ] }, "tls-certificates-and-hostnames_keyless_private_ip": { "description": "Private IP of the Key Server Host.", "type": "string", "example": "10.0.0.1", "x-auditable": true }, "tls-certificates-and-hostnames_keyless_response_collection": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless-certificate" } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_keyless_response_single": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_base" } ] } }, "type": "object" } ] }, "tls-certificates-and-hostnames_keyless_response_single_id": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" } } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_keyless_tunnel": { "description": "Configuration for using Keyless SSL through a Cloudflare Tunnel.", "type": "object", "properties": { "private_ip": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless_private_ip" }, "vnet_id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_keyless_vnet_id" } }, "required": [ "private_ip", "vnet_id" ] }, "tls-certificates-and-hostnames_keyless_vnet_id": { "description": "Cloudflare Tunnel Virtual Network ID.", "type": "string", "example": "7365377a-85a4-4390-9480-531ef7dc7a3c", "x-auditable": true }, "tls-certificates-and-hostnames_location": { "description": "Location, provided by the CSR.", "type": "string", "example": "Somewhere", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "tls-certificates-and-hostnames_modified_on": { "description": "When the certificate was last modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00Z", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_name": { "description": "The keyless SSL name.", "type": "string", "example": "example.com Keyless SSL", "maxLength": 180, "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_name-2": { "description": "Optional unique name for the certificate. Only used for human readability.", "type": "string", "example": "example_ca_cert", "x-auditable": true }, "tls-certificates-and-hostnames_name_write": { "description": "The keyless SSL name.", "type": "string", "example": "example.com Keyless SSL", "maxLength": 180, "x-auditable": true }, "tls-certificates-and-hostnames_organization": { "description": "Organization, provided by the CSR.", "type": "string", "example": "Organization", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_organizational_unit": { "description": "Organizational Unit, provided by the CSR.", "type": "string", "example": "Organizational Unit", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_origin": { "description": "Your origin hostname that requests to your custom hostnames will be sent to.", "type": "string", "example": "fallback.example.com", "maxLength": 255, "x-auditable": true }, "tls-certificates-and-hostnames_ownership_verification": { "description": "This is a record which can be placed to activate a hostname.", "type": "object", "oneOf": [ { "properties": { "name": { "description": "DNS Name for record.", "type": "string", "example": "_cf-custom-hostname.app.example.com", "x-auditable": true }, "type": { "description": "DNS Record type.", "type": "string", "example": "txt", "enum": [ "txt" ], "x-auditable": true }, "value": { "description": "Content for the record.", "type": "string", "example": "5cc07c04-ea62-4a5a-95f0-419334a875a4" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_ownership_verification_http": { "description": "This presents the token to be served by the given http url to activate a hostname.", "type": "object", "oneOf": [ { "properties": { "http_body": { "description": "Token to be served.", "type": "string", "example": "5cc07c04-ea62-4a5a-95f0-419334a875a4" }, "http_url": { "description": "The HTTP URL that will be checked during custom hostname verification and where the customer should host the token.", "type": "string", "example": "http://custom.test.com/.well-known/cf-custom-hostname-challenge/0d89c70d-ad9f-4843-b99f-6cc0252067e9" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_per_hostname_settings_response": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_settingObject" } ] } }, "type": "object" } ] }, "tls-certificates-and-hostnames_per_hostname_settings_response_collection": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "properties": { "created_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_created_at-4" }, "hostname": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname-3" }, "status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status-12" }, "updated_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_updated_at-5" }, "value": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_value" } }, "type": "object" } } }, "type": "object" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "type": "number", "example": 1 }, "page": { "type": "number", "example": 1 }, "per_page": { "type": "number", "example": 50 }, "total_count": { "type": "number", "example": 1 }, "total_pages": { "description": "Total pages available of results.", "type": "number", "example": 1 } } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_per_hostname_settings_response_delete": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_settingObjectDelete" } ] } }, "type": "object" } ] }, "tls-certificates-and-hostnames_policy": { "description": "Specify the policy that determines the region where your private key will be held locally. HTTPS connections to any excluded data center will still be fully encrypted, but will incur some latency while Keyless SSL is used to complete the handshake with the nearest allowed data center. Any combination of countries, specified by their two letter country code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) can be chosen, such as 'country: IN', as well as 'region: EU' which refers to the EU region. If there are too few data centers satisfying the policy, it will be rejected.\nNote: The API accepts this field as either \"policy\" or \"policy_restrictions\" in requests. Responses return this field as \"policy_restrictions\".", "type": "string", "example": "(country: US) or (region: EU)", "x-auditable": true }, "tls-certificates-and-hostnames_policy_restrictions": { "description": "The policy restrictions returned by the API. This field is returned in responses\nwhen a policy has been set. The API accepts the \"policy\" field in requests but\nreturns this field as \"policy_restrictions\" in responses.\n\nSpecifies the region(s) where your private key can be held locally for optimal\nTLS performance. Format is a boolean expression, for example:\n\"(country: US) or (region: EU)\"\n", "type": "string", "example": "(country: US) or (region: EU)", "readOnly": true }, "tls-certificates-and-hostnames_port": { "description": "The keyless SSL port used to communicate between Cloudflare and the client's Keyless SSL server.", "type": "number", "example": 24008, "default": 24008, "maxLength": 65535, "x-auditable": true }, "tls-certificates-and-hostnames_primary": { "description": "Identifier of the primary certificate in a pack.", "type": "string", "example": "7e7b8deba8538af625850b7b2530034c", "x-auditable": true }, "tls-certificates-and-hostnames_priority": { "description": "The order/priority in which the certificate will be used in a request. The higher priority will break ties across overlapping 'legacy_custom' certificates, but 'legacy_custom' certificates will always supercede 'sni_custom' certificates.", "type": "number", "example": 1, "default": 0, "x-auditable": true }, "tls-certificates-and-hostnames_private_key": { "description": "The zone's private key. Not required if custom_csr_id is provided, in which case the private key is retrieved from the CSR record held by Cloudflare.", "type": "string", "example": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG\ndtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn\nabIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid\ntnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py\nFxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE\newooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb\nHBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/\naxiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb\n+ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g\n+j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv\nKLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7\n9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo\n/WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu\niacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9\nN2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe\nVAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB\nvULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U\nlySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR\n9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7\nmEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX\ndFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe\nPG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS\nfhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W\nqu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T\nlv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi\n-----END RSA PRIVATE KEY-----\n", "x-sensitive": true }, "tls-certificates-and-hostnames_private_key-2": { "description": "The zone's private key.", "type": "string", "example": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG\ndtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn\nabIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid\ntnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py\nFxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE\newooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb\nHBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/\naxiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb\n+ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g\n+j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv\nKLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7\n9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo\n/WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu\niacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9\nN2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe\nVAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB\nvULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U\nlySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR\n9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7\nmEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX\ndFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe\nPG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS\nfhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W\nqu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T\nlv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi\n-----END RSA PRIVATE KEY-----\n", "x-sensitive": true }, "tls-certificates-and-hostnames_private_key-3": { "description": "The hostname certificate's private key.", "type": "string", "example": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG\ndtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn\nabIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid\ntnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py\nFxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE\newooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb\nHBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/\naxiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb\n+ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g\n+j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv\nKLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7\n9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo\n/WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu\niacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9\nN2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe\nVAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB\nvULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U\nlySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR\n9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7\nmEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX\ndFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe\nPG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS\nfhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W\nqu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T\nlv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi\n-----END RSA PRIVATE KEY-----\n", "x-sensitive": true }, "tls-certificates-and-hostnames_private_key-4": { "description": "The private key for the certificate. This field is only needed for specific use cases such as using a custom certificate with Zero Trust's block page.", "type": "string", "example": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDEXDkcICRU3XBv\n9hiiPnBWIjgTQyowmVFxDr11mONgZB/cMYjE/OvQjvnpwNcOaSK16MOpAjNbELKR\nx2lZiVJaLRDCccqCxXwP/CrdRChcqGzo7mbNksMlcidrErb0LlEBKLFC2QjRmRKq\nB+YOs4TD8WsZu2S667A2fZmjRlaqOxFi1h62ee0P+TLU628UC/nl41JifSt5Evt7\nhMDHakemdwZblNYr2p6T3NQjdhjYXTtP4UmOGJBhJ7i7Kicg3d3CIgdTMbggSeGW\nqjndr4ldVnD96FN3cVT5uDFsn2CJXTFgdeBWoUnMS4VnUZzPWGf4vSBXC8qV7Ls+\nw46yT7T1AgMBAAECggEAQZnp/oqCeNPOR6l5S2L+1tfx0gWjZ78hJVteUpZ0iHSK\n7F6kKeOxyOird7vUXV0kmo+cJq+0hp0Ke4eam640FCpwKfYoSQ4/R3vgujGWJnai\nhCN5tv5sMet0XeJPuz5qE7ALoKCvwI6aXLHs20aAeZIDTQJ9QbGSGnJVzOWn+JDT\nidIgZpN57RpXfSAwnJPTQK/PN8i5z108hsaDOdEgGmxYZ7kYqMqzX20KXmth58LD\nfPixs5JGtS60iiKC/wOcGzkB2/AdTSojR76oEU77cANP/3zO25NG//whUdYlW0t0\nd7PgXxIeJe+xgYnamDQJx3qonVyt4H77ha0ObRAj9QKBgQDicZr+VTwFMnELP3a+\nFXGnjehRiuS1i7MXGKxNweCD+dFlML0FplSQS8Ro2n+d8lu8BBXGx0qm6VXu8Rhn\n7TAUL6q+PCgfarzxfIhacb/TZCqfieIHsMlVBfhV5HCXnk+kis0tuC/PRArcWTwD\nHJUJXkBhvkUsNswvQzavDPI7KwKBgQDd/WgLkj7A3X5fgIHZH/GbDSBiXwzKb+rF\n4ZCT2XFgG/OAW7vapfcX/w+v+5lBLyrocmOAS3PGGAhM5T3HLnUCQfnK4qgps1Lq\nibkc9Tmnsn60LanUjuUMsYv/zSw70tozbzhJ0pioEpWfRxRZBztO2Rr8Ntm7h6Fk\n701EXGNAXwKBgQCD1xsjy2J3sCerIdcz0u5qXLAPkeuZW+34m4/ucdwTWwc0gEz9\nlhsULFj9p4G351zLuiEnq+7mAWLcDJlmIO3mQt6JhiLiL9Y0T4pgBmxmWqKKYtAs\nJB0EmMY+1BNN44mBRqMxZFTJu1cLdhT/xstrOeoIPqytknYNanfTMZlzIwKBgHrL\nXe5oq0XMP8dcMneEcAUwsaU4pr6kQd3L9EmUkl5zl7J9C+DaxWAEuwzBw/iGutlx\nzRB+rD/7szu14wJ29EqXbDGKRzMp+se5/yfBjm7xEZ1hVPw7PwBShfqt57X/4Ktq\n7lwHnmH6RcGhc+P7WBc5iO/S94YAdIp8xOT3pf9JAoGAE0QkqJUY+5Mgr+fBO0VN\nV72ZoPveGpW+De59uhKAOnu1zljQCUtk59m6+DXfm0tNYKtawa5n8iN71Zh+s62x\nXSt3pYi1Y5CCCmv8Y4BhwIcPwXKk3zEvLgSHVTpC0bayA9aSO4bbZgVXa5w+Z0w/\nvvfp9DWo1IS3EnQRrz6WMYA=\n-----END PRIVATE KEY-----", "x-sensitive": true }, "tls-certificates-and-hostnames_quota": { "type": "object", "properties": { "allocated": { "description": "Quantity Allocated.", "type": "integer", "x-auditable": true }, "used": { "description": "Quantity Used.", "type": "integer", "x-auditable": true } } }, "tls-certificates-and-hostnames_request_type": { "description": "Signature type desired on certificate (\"origin-rsa\" (rsa), \"origin-ecc\" (ecdsa), or \"keyless-certificate\" (for Keyless SSL servers).", "type": "string", "example": "origin-rsa", "enum": [ "origin-rsa", "origin-ecc", "keyless-certificate" ], "x-auditable": true }, "tls-certificates-and-hostnames_requested_validity": { "description": "The number of days for which the certificate should be valid.", "type": "number", "example": 5475, "default": 5475, "enum": [ 7, 30, 90, 365, 730, 1095, 5475 ], "x-auditable": true }, "tls-certificates-and-hostnames_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } }, "tls-certificates-and-hostnames_revoked_at": { "description": "When the certificate was revoked.", "type": "string", "format": "date-time", "example": "2024-09-06T18:43:47.928893Z", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_serial_number": { "description": "The serial number on the uploaded certificate.", "type": "string", "example": "6743787633689793699141714808227354901", "x-auditable": true }, "tls-certificates-and-hostnames_serial_number-2": { "description": "The certificate serial number.", "type": "string", "example": "235217144297995885180570755458463043449861756659", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_serial_number-3": { "description": "The serial number on the created Client Certificate.", "type": "string", "example": "3bb94ff144ac567b9f75ad664b6c55f8d5e48182", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_service": { "description": "The service using the certificate.", "type": "string", "example": "gateway", "x-auditable": true }, "tls-certificates-and-hostnames_settingObject": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_created_at-4" }, "hostname": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname-3" }, "status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status-12" }, "updated_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_updated_at-5" }, "value": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_value" } } }, "tls-certificates-and-hostnames_settingObjectDelete": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_created_at-4" }, "hostname": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_hostname-3" }, "status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status-12" }, "updated_at": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_updated_at-5" }, "value": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_value" } } }, "tls-certificates-and-hostnames_setting_id": { "description": "The TLS Setting name.\nThe value type depends on the setting:\n- `ciphers`: value is an array of cipher suite strings (e.g., `[\"ECDHE-RSA-AES128-GCM-SHA256\", \"AES128-GCM-SHA256\"]`).\n- `min_tls_version`: value is a TLS version string (`\"1.0\"`, `\"1.1\"`, `\"1.2\"`, or `\"1.3\"`).\n- `http2`: value is `\"on\"` or `\"off\"`.", "type": "string", "enum": [ "ciphers", "min_tls_version", "http2" ], "x-auditable": true }, "tls-certificates-and-hostnames_signature": { "description": "The type of hash used for the certificate.", "type": "string", "example": "SHA256WithRSA", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_signature-2": { "description": "Certificate's signature algorithm.", "type": "string", "enum": [ "ECDSAWithSHA256", "SHA1WithRSA", "SHA256WithRSA" ], "x-auditable": true }, "tls-certificates-and-hostnames_signature-3": { "description": "The type of hash used for the Client Certificate..", "type": "string", "example": "SHA256WithRSA", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_ski": { "description": "Subject Key Identifier.", "type": "string", "example": "8e375af1389a069a0f921f8cc8e1eb12d784b949", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_ssl": { "description": "SSL properties for the custom hostname.", "type": "object", "oneOf": [ { "properties": { "bundle_method": { "description": "A ubiquitous bundle has the highest probability of being verified everywhere, even by clients using outdated or unusual trust stores. An optimal bundle uses the shortest chain and newest intermediates. And the force bundle verifies the chain, but does not otherwise modify it.", "type": "string", "example": "ubiquitous", "default": "ubiquitous", "enum": [ "ubiquitous", "optimal", "force" ], "x-auditable": true }, "certificate_authority": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_authority" }, "custom_certificate": { "description": "If a custom uploaded certificate is used.", "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E...SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O\nOeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7\n-----END CERTIFICATE-----\n" }, "custom_csr_id": { "description": "The identifier for the Custom CSR that was used.", "type": "string", "example": "7b163417-1d2b-4c84-a38a-2fb7a0cd7752", "x-auditable": true }, "custom_key": { "description": "The key for a custom uploaded certificate.", "type": "string", "example": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG\ndtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn\nabIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid\ntnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py\nFxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE\newooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb\nHBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/\naxiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb\n+ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g\n+j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv\nKLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7\n9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo\n/WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu\niacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9\nN2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe\nVAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB\nvULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U\nlySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR\n9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7\nmEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX\ndFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe\nPG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS\nfhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W\nqu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T\nlv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi\n-----END RSA PRIVATE KEY-----\n", "x-sensitive": true }, "dcv_delegation_records": { "description": "DCV Delegation records for domain validation.", "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_validation_record" }, "readOnly": true }, "expires_on": { "description": "The time the custom certificate expires on.", "type": "string", "format": "date-time", "example": "2021-02-06T18:11:23.531995Z", "x-auditable": true }, "hosts": { "description": "A list of Hostnames on a custom uploaded certificate.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "app.example.com", "*.app.example.com" ] }, "id": { "description": "Custom hostname SSL identifier tag.", "type": "string", "example": "0d89c70d-ad9f-4843-b99f-6cc0252067e9", "maxLength": 36, "minLength": 36, "x-auditable": true }, "issuer": { "description": "The issuer on a custom uploaded certificate.", "type": "string", "example": "DigiCertInc", "x-auditable": true }, "method": { "description": "Domain control validation (DCV) method used for this hostname.", "type": "string", "example": "txt", "enum": [ "http", "txt", "email" ], "readOnly": true, "x-auditable": true }, "serial_number": { "description": "The serial number on a custom uploaded certificate.", "type": "string", "example": "6743787633689793699141714808227354901", "x-auditable": true }, "settings": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_sslsettings" }, "signature": { "description": "The signature on a custom uploaded certificate.", "type": "string", "example": "SHA256WithRSA", "x-auditable": true }, "status": { "description": "Status of the hostname's SSL certificates.", "type": "string", "example": "pending_validation", "enum": [ "initializing", "pending_validation", "deleted", "pending_issuance", "pending_deployment", "pending_deletion", "pending_expiration", "expired", "active", "initializing_timed_out", "validation_timed_out", "issuance_timed_out", "deployment_timed_out", "deletion_timed_out", "pending_cleanup", "staging_deployment", "staging_active", "deactivating", "inactive", "backup_issued", "holding_deployment" ], "readOnly": true, "x-auditable": true }, "type": { "description": "Level of validation to be used for this hostname. Domain validation (dv) must be used.", "type": "string", "example": "dv", "enum": [ "dv" ], "x-auditable": true }, "uploaded_on": { "description": "The time the custom certificate was uploaded.", "type": "string", "format": "date-time", "example": "2020-02-06T18:11:23.531995Z", "x-auditable": true }, "validation_errors": { "description": "Domain validation errors that have been received by the certificate authority (CA).", "type": "array", "items": { "properties": { "message": { "description": "A domain validation error.", "type": "string", "example": "SERVFAIL looking up CAA for app.example.com", "x-auditable": true } }, "type": "object" } }, "validation_records": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_validation_record" } }, "wildcard": { "description": "Indicates whether the certificate covers a wildcard.", "type": "boolean", "example": false, "x-auditable": true } }, "type": "object" } ] }, "tls-certificates-and-hostnames_ssl_universal_settings_response": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_universal" } }, "type": "object" } ] }, "tls-certificates-and-hostnames_ssl_validation_method_response_collection": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_status-6" }, "validation_method": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_validation_method_definition" } } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_ssl_verification_response_collection": { "allOf": [ { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_verification" } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_sslpost": { "description": "SSL properties used when creating the custom hostname.", "type": "object", "oneOf": [ { "properties": { "bundle_method": { "description": "A ubiquitous bundle has the highest probability of being verified everywhere, even by clients using outdated or unusual trust stores. An optimal bundle uses the shortest chain and newest intermediates. And the force bundle verifies the chain, but does not otherwise modify it.", "type": "string", "example": "ubiquitous", "default": "ubiquitous", "enum": [ "ubiquitous", "optimal", "force" ], "x-auditable": true }, "certificate_authority": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_authority" }, "cloudflare_branding": { "description": "Whether or not to add Cloudflare Branding for the order. This will add a subdomain of sni.cloudflaressl.com as the Common Name if set to true.", "type": "boolean", "example": false, "x-auditable": true }, "custom_cert_bundle": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_custom_cert_bundle" }, "custom_certificate": { "description": "If a custom uploaded certificate is used.", "type": "string", "example": "-----BEGIN CERTIFICATE-----\nMIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E...SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O\nOeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7\n-----END CERTIFICATE-----\n", "x-auditable": true }, "custom_csr_id": { "description": "The identifier for the Custom CSR that was used.", "type": "string", "example": "7b163417-1d2b-4c84-a38a-2fb7a0cd7752", "x-auditable": true }, "custom_key": { "description": "The key for a custom uploaded certificate.", "type": "string", "example": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG\ndtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn\nabIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid\ntnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py\nFxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE\newooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb\nHBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/\naxiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb\n+ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g\n+j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv\nKLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7\n9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo\n/WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu\niacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9\nN2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe\nVAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB\nvULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U\nlySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR\n9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7\nmEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX\ndFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe\nPG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS\nfhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W\nqu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T\nlv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi\n-----END RSA PRIVATE KEY-----\n", "x-sensitive": true }, "method": { "description": "Domain control validation (DCV) method used for this hostname.", "type": "string", "example": "http", "enum": [ "http", "txt", "email" ], "x-auditable": true }, "settings": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_sslsettings" }, "type": { "description": "Level of validation to be used for this hostname. Domain validation (dv) must be used.", "type": "string", "example": "dv", "enum": [ "dv" ], "x-auditable": true }, "wildcard": { "description": "Indicates whether the certificate covers a wildcard.", "type": "boolean", "example": false, "x-auditable": true } }, "type": "object" } ] }, "tls-certificates-and-hostnames_sslsettings": { "description": "SSL specific settings.", "type": "object", "properties": { "ciphers": { "description": "An allowlist of ciphers for TLS termination. These ciphers must be in the BoringSSL format.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "ECDHE-RSA-AES128-GCM-SHA256", "AES128-SHA" ], "uniqueItems": true }, "early_hints": { "description": "Whether or not Early Hints is enabled.", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true }, "http2": { "description": "Whether or not HTTP2 is enabled.", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true }, "min_tls_version": { "description": "The minimum TLS version supported.", "type": "string", "example": "1.2", "enum": [ "1.0", "1.1", "1.2", "1.3" ], "x-auditable": true }, "tls_1_3": { "description": "Whether or not TLS 1.3 is enabled.", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } } }, "tls-certificates-and-hostnames_state": { "description": "State, provided by the CSR.", "type": "string", "example": "CA", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_status": { "description": "Status of the zone's custom SSL.", "type": "string", "example": "active", "enum": [ "active", "expired", "deleted", "pending", "initializing" ], "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_status-10": { "description": "Certificate deployment status for the given service.", "type": "string", "example": "pending_deployment", "x-auditable": true }, "tls-certificates-and-hostnames_status-11": { "description": "Client Certificates may be active or revoked, and the pending_reactivation or pending_revocation represent in-progress asynchronous transitions.", "type": "string", "example": "active", "enum": [ "active", "pending_reactivation", "pending_revocation", "revoked" ], "x-auditable": true }, "tls-certificates-and-hostnames_status-12": { "description": "Deployment status for the given tls setting.", "type": "string", "example": "pending_deployment", "x-auditable": true }, "tls-certificates-and-hostnames_status-2": { "description": "Status of the Keyless SSL.", "type": "string", "example": "active", "enum": [ "active", "deleted" ], "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_status-3": { "description": "Status of the hostname's activation.", "type": "string", "example": "pending", "enum": [ "active", "pending", "active_redeploying", "moved", "pending_deletion", "deleted", "pending_blocked", "pending_migration", "pending_provisioned", "test_pending", "test_active", "test_active_apex", "test_blocked", "test_failed", "provisioned", "blocked" ], "x-auditable": true }, "tls-certificates-and-hostnames_status-4": { "description": "Status of the fallback origin's activation.", "type": "string", "example": "pending_deployment", "enum": [ "initializing", "pending_deployment", "pending_deletion", "active", "deployment_timed_out", "deletion_timed_out" ], "x-auditable": true }, "tls-certificates-and-hostnames_status-5": { "description": "Status of certificate pack.", "type": "string", "example": "initializing", "enum": [ "initializing", "pending_validation", "deleted", "pending_issuance", "pending_deployment", "pending_deletion", "pending_expiration", "expired", "active", "initializing_timed_out", "validation_timed_out", "issuance_timed_out", "deployment_timed_out", "deletion_timed_out", "pending_cleanup", "staging_deployment", "staging_active", "deactivating", "inactive", "backup_issued", "holding_deployment" ], "x-auditable": true }, "tls-certificates-and-hostnames_status-6": { "description": "Result status.", "type": "string", "example": "pending_validation", "x-auditable": true }, "tls-certificates-and-hostnames_status-7": { "description": "Status of the zone's custom SSL.", "type": "string", "example": "active", "enum": [ "initializing", "pending_deployment", "active", "pending_deletion", "deleted", "expired" ], "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_status-8": { "description": "Status of the certificate activation.", "type": "string", "example": "active", "enum": [ "initializing", "pending_deployment", "pending_deletion", "active", "deleted", "deployment_timed_out", "deletion_timed_out" ], "x-auditable": true }, "tls-certificates-and-hostnames_status-9": { "description": "Status of the certificate or the association.", "type": "string", "example": "active", "enum": [ "initializing", "pending_deployment", "pending_deletion", "active", "deleted", "deployment_timed_out", "deletion_timed_out" ], "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_total_tls_settings_response": { "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "certificate_authority": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_authority-3" }, "enabled": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_enabled-3" }, "validity_period": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_validity_period" } } } }, "type": "object" } ] }, "tls-certificates-and-hostnames_type": { "description": "The type 'legacy_custom' enables support for legacy clients which do not include SNI in the TLS handshake.", "type": "string", "example": "sni_custom", "default": "legacy_custom", "enum": [ "legacy_custom", "sni_custom" ], "x-auditable": true }, "tls-certificates-and-hostnames_type-2": { "description": "Type of certificate pack.", "type": "string", "example": "universal", "enum": [ "mh_custom", "managed_hostname", "sni_custom", "universal", "advanced", "total_tls", "keyless", "legacy_custom" ], "x-auditable": true }, "tls-certificates-and-hostnames_type-3": { "description": "The type of the certificate, indicating how it was created and who manages it.", "type": "string", "example": "custom", "enum": [ "custom", "gateway_managed", "access_managed" ], "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_universal": { "type": "object", "properties": { "enabled": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_enabled-2" } } }, "tls-certificates-and-hostnames_updated_at": { "description": "This is the time the fallback origin was updated.", "type": "string", "format": "date-time", "example": "2020-03-16T18:11:23.531995Z", "x-auditable": true }, "tls-certificates-and-hostnames_updated_at-2": { "description": "When the certificate was last modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00Z", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_updated_at-3": { "description": "The time when the certificate was updated.", "type": "string", "format": "date-time", "example": "2100-01-01T05:20:00Z", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_updated_at-4": { "description": "This is the time the certificate was updated.", "type": "string", "format": "date-time", "example": "2022-11-22T17:32:30.467938Z", "x-auditable": true }, "tls-certificates-and-hostnames_updated_at-5": { "description": "This is the time the tls setting was updated.", "type": "string", "format": "date-time", "example": "2023-07-10T20:01:50.219171Z", "x-auditable": true }, "tls-certificates-and-hostnames_uploaded_on": { "description": "When the certificate was uploaded to Cloudflare.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00Z", "readOnly": true, "x-auditable": true }, "tls-certificates-and-hostnames_uploaded_on-2": { "description": "This is the time the certificate was uploaded.", "type": "string", "format": "date-time", "example": "2019-10-28T18:11:23.37411Z", "x-auditable": true }, "tls-certificates-and-hostnames_uploaded_on-3": { "description": "The time when the certificate was uploaded.", "type": "string", "format": "date-time", "example": "2019-10-28T18:11:23.37411Z", "x-auditable": true }, "tls-certificates-and-hostnames_uploaded_on-4": { "description": "This is the time the certificate was uploaded.", "type": "string", "format": "date-time", "example": "2022-11-22T17:32:30.467938Z", "x-auditable": true }, "tls-certificates-and-hostnames_uuid": { "description": "The DCV Delegation unique identifier.", "type": "string", "example": "abc123def456ghi7", "x-auditable": true }, "tls-certificates-and-hostnames_uuidObject": { "type": "object", "properties": { "uuid": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_uuid" } } }, "tls-certificates-and-hostnames_validation_method": { "description": "Validation Method selected for the order.", "type": "string", "example": "txt", "enum": [ "txt", "http", "email" ], "x-auditable": true }, "tls-certificates-and-hostnames_validation_method-2": { "description": "Validation method in use for a certificate pack order.", "type": "string", "example": "txt", "enum": [ "http", "cname", "txt" ], "x-auditable": true }, "tls-certificates-and-hostnames_validation_method-3": { "type": "object", "properties": { "validation_method": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_validation_method_definition" } }, "required": [ "validation_method" ] }, "tls-certificates-and-hostnames_validation_method_definition": { "description": "Desired validation method.", "type": "string", "example": "txt", "enum": [ "http", "cname", "txt", "email" ], "x-auditable": true }, "tls-certificates-and-hostnames_validation_record": { "description": "Certificate's required validation record.", "type": "object", "properties": { "cname": { "description": "The CNAME record hostname for DCV delegation.", "type": "string", "example": "_acme-challenge.example.com", "readOnly": true, "x-auditable": true }, "cname_target": { "description": "The CNAME record target value for DCV delegation.", "type": "string", "example": "dcv.cloudflare.com", "readOnly": true, "x-auditable": true }, "emails": { "description": "The set of email addresses that the certificate authority (CA) will use to complete domain validation.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "administrator@example.com", "webmaster@example.com" ] }, "http_body": { "description": "The content that the certificate authority (CA) will expect to find at the http_url during the domain validation.", "type": "string", "example": "ca3-574923932a82475cb8592200f1a2a23d" }, "http_url": { "description": "The url that will be checked during domain validation.", "type": "string", "example": "http://app.example.com/.well-known/pki-validation/ca3-da12a1c25e7b48cf80408c6c1763b8a2.txt" }, "status": { "description": "Status of the validation record.", "type": "string", "example": "pending", "readOnly": true }, "txt_name": { "description": "The hostname that the certificate authority (CA) will check for a TXT record during domain validation .", "type": "string", "example": "_acme-challenge.app.example.com", "x-auditable": true }, "txt_value": { "description": "The TXT record that the certificate authority (CA) will check during domain validation.", "type": "string", "example": "810b7d5f01154524b961ba0cd578acc2" } } }, "tls-certificates-and-hostnames_validity_days": { "description": "Validity Days selected for the order.", "type": "integer", "enum": [ 14, 30, 90, 365 ], "x-auditable": true }, "tls-certificates-and-hostnames_validity_days-2": { "description": "The number of days the Client Certificate will be valid after the issued_on date.", "type": "integer", "example": 3650, "x-auditable": true }, "tls-certificates-and-hostnames_validity_period": { "description": "The validity period in days for the certificates ordered via Total TLS.", "type": "integer", "enum": [ 90 ], "x-auditable": true }, "tls-certificates-and-hostnames_value": { "description": "The TLS setting value.\nThe type depends on the `setting_id` used in the request path:\n- `ciphers`: an array of allowed cipher suite strings in BoringSSL format (e.g., `[\"ECDHE-RSA-AES128-GCM-SHA256\", \"AES128-GCM-SHA256\"]`).\n- `min_tls_version`: a string indicating the minimum TLS version — one of `\"1.0\"`, `\"1.1\"`, `\"1.2\"`, or `\"1.3\"` (e.g., `\"1.2\"`).\n- `http2`: a string indicating whether HTTP/2 is enabled — `\"on\"` or `\"off\"` (e.g., `\"on\"`).", "oneOf": [ { "description": "Used when `setting_id` is `ciphers`. An array of allowed cipher suite strings.", "example": [ "ECDHE-RSA-AES128-GCM-SHA256", "AES128-GCM-SHA256" ], "items": { "type": "string" }, "type": "array", "x-auditable": true }, { "description": "Used when `setting_id` is `min_tls_version`. The minimum TLS version.", "enum": [ "1.0", "1.1", "1.2", "1.3" ], "example": "1.2", "type": "string", "x-auditable": true }, { "description": "Used when `setting_id` is `http2`. Whether HTTP/2 is enabled.", "enum": [ "on", "off" ], "example": "on", "type": "string", "x-auditable": true } ] }, "tls-certificates-and-hostnames_verification": { "type": "object", "properties": { "brand_check": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_brand_check" }, "cert_pack_uuid": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_cert_pack_uuid" }, "certificate_status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate_status" }, "signature": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_signature-2" }, "validation_method": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_validation_method-2" }, "verification_info": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_verification_info" }, "verification_status": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_verification_status" }, "verification_type": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_verification_type" } }, "required": [ "certificate_status" ] }, "tls-certificates-and-hostnames_verification_errors": { "description": "These are errors that were encountered while trying to activate a hostname.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "None of the A or AAAA records are owned by this account and the pre-generated ownership verification token was not found." ] }, "tls-certificates-and-hostnames_verification_info": { "description": "Certificate's required verification information.", "type": "object", "properties": { "record_name": { "description": "Name of CNAME record.", "type": "string", "format": "hostname", "example": "b3b90cfedd89a3e487d3e383c56c4267.example.com", "enum": [ "record_name", "http_url", "cname", "txt_name" ], "x-auditable": true }, "record_target": { "description": "Target of CNAME record.", "type": "string", "format": "hostname", "example": "6979be7e4cfc9e5c603e31df7efac9cc60fee82d.comodoca.com", "enum": [ "record_value", "http_body", "cname_target", "txt_value" ], "x-auditable": true } } }, "tls-certificates-and-hostnames_verification_status": { "description": "Status of the required verification information, omitted if verification status is unknown.", "type": "boolean", "example": true, "x-auditable": true }, "tls-certificates-and-hostnames_verification_type": { "description": "Method of verification.", "type": "string", "example": "cname", "enum": [ "cname", "meta tag" ], "x-auditable": true }, "tls-certificates-and-hostnames_zone-authenticated-origin-pull": { "type": "object", "properties": { "certificate": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificate-5" }, "enabled": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_enabled-4" }, "id": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_identifier" }, "private_key": { "$ref": "#/components/schemas/tls-certificates-and-hostnames_private_key-2" } }, "allOf": [ { "$ref": "#/components/schemas/tls-certificates-and-hostnames_certificateObject" } ] }, "tunnel_account_id": { "description": "Cloudflare account ID", "type": "string", "example": "699d98642c564d2e855e9661899b7252", "maxLength": 32, "readOnly": true, "x-auditable": true }, "tunnel_address_family": { "description": "IP address family, either `v4` (IPv4) or `v6` (IPv6)", "type": "string", "example": "v4", "enum": [ "v4", "v6" ] }, "tunnel_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-common" }, { "properties": { "result": { "type": "array", "items": {}, "nullable": true }, "result_info": { "$ref": "#/components/schemas/tunnel_result_info" } } } ] }, "tunnel_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/tunnel_messages" }, "messages": { "$ref": "#/components/schemas/tunnel_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": {}, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "tunnel_api-response-common-2": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/tunnel_messages-2" }, "messages": { "$ref": "#/components/schemas/tunnel_messages-2" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "tunnel_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/tunnel_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/tunnel_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "tunnel_api-response-common-failure-2": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/tunnel_messages-2" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/tunnel_messages-2" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "tunnel_api-response-single": { "$ref": "#/components/schemas/tunnel_api-response-common" }, "tunnel_api-response-single-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-common-2" } ] }, "tunnel_arch": { "description": "The cloudflared OS architecture used to establish this connection.", "type": "string", "example": "linux_amd64" }, "tunnel_argo-tunnel": { "type": "object", "properties": { "connections": { "description": "The tunnel connections between your origin and Cloudflare's edge.", "type": "array", "items": { "$ref": "#/components/schemas/tunnel_connection" } }, "created_at": { "$ref": "#/components/schemas/tunnel_created_at" }, "deleted_at": { "$ref": "#/components/schemas/tunnel_deleted_at" }, "id": { "$ref": "#/components/schemas/tunnel_tunnel_id" }, "name": { "$ref": "#/components/schemas/tunnel_tunnel_name" } }, "required": [ "id", "name", "created_at", "connections" ] }, "tunnel_cfd-tunnel-response-collection": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tunnel_cfd_tunnel" } } }, "type": "object" } ] }, "tunnel_cfd-tunnel-response-single": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/tunnel_cfd_tunnel" } }, "type": "object" } ] }, "tunnel_cfd_tunnel": { "description": "A Cloudflare Tunnel that connects your origin to Cloudflare's edge.", "type": "object", "properties": { "account_tag": { "$ref": "#/components/schemas/tunnel_account_id" }, "config_src": { "$ref": "#/components/schemas/tunnel_config_src" }, "connections": { "$ref": "#/components/schemas/tunnel_connections_deprecated" }, "conns_active_at": { "$ref": "#/components/schemas/tunnel_conns_active_at" }, "conns_inactive_at": { "$ref": "#/components/schemas/tunnel_conns_inactive_at" }, "created_at": { "$ref": "#/components/schemas/tunnel_created_at" }, "deleted_at": { "$ref": "#/components/schemas/tunnel_deleted_at" }, "id": { "$ref": "#/components/schemas/tunnel_tunnel_id" }, "metadata": { "$ref": "#/components/schemas/tunnel_metadata" }, "name": { "$ref": "#/components/schemas/tunnel_tunnel_name" }, "remote_config": { "$ref": "#/components/schemas/tunnel_remote_config" }, "status": { "$ref": "#/components/schemas/tunnel_status" }, "tun_type": { "$ref": "#/components/schemas/tunnel_tunnel_type" } } }, "tunnel_client_id": { "description": "UUID of the Cloudflare Tunnel connector.", "type": "string", "format": "uuid", "example": "1bedc50d-42b3-473c-b108-ff3d10c0d925", "maxLength": 36, "readOnly": true, "x-auditable": true }, "tunnel_client_id_input": { "description": "UUID of the Cloudflare Tunnel connector.", "type": "string", "format": "uuid", "example": "1bedc50d-42b3-473c-b108-ff3d10c0d925", "maxLength": 36, "x-auditable": true }, "tunnel_colo_name": { "description": "The Cloudflare data center used for this connection.", "type": "string", "example": "DFW" }, "tunnel_config": { "description": "The tunnel configuration and ingress rules.", "type": "object", "properties": { "ingress": { "description": "List of public hostname definitions. At least one ingress rule needs to be defined for the tunnel.", "type": "array", "items": { "$ref": "#/components/schemas/tunnel_ingressRule" }, "minItems": 1 }, "originRequest": { "$ref": "#/components/schemas/tunnel_originRequest" }, "warp-routing": { "description": "Enable private network access from WARP users to private network routes. This is enabled if the tunnel has an assigned route.", "type": "object", "deprecated": true, "properties": { "enabled": { "type": "boolean" } }, "readOnly": true, "x-stainless-deprecation-message": "This field is ignored by cloudflared since version 2023.10.0.", "x-stainless-skip": true } } }, "tunnel_config_src": { "description": "Indicates if this is a locally or remotely configured tunnel. If `local`, manage the tunnel using a YAML file on the origin machine. If `cloudflare`, manage the tunnel on the Zero Trust dashboard.", "type": "string", "example": "cloudflare", "default": "local", "enum": [ "local", "cloudflare" ] }, "tunnel_config_src-2": { "description": "Indicates if this is a locally or remotely configured tunnel. If `local`, manage the tunnel using a YAML file on the origin machine. If `cloudflare`, manage the tunnel's configuration on the Zero Trust dashboard.", "type": "string", "example": "cloudflare", "enum": [ "local", "cloudflare" ], "x-stainless-terraform-configurability": "computed_optional" }, "tunnel_config_version": { "description": "The version of the remote tunnel configuration. Used internally to sync cloudflared with the Zero Trust dashboard.", "type": "integer" }, "tunnel_config_version-2": { "description": "The version of the Tunnel Configuration.", "type": "integer" }, "tunnel_configuration": { "description": "Cloudflare Tunnel configuration", "type": "object", "properties": { "account_id": { "$ref": "#/components/schemas/tunnel_identifier" }, "config": { "$ref": "#/components/schemas/tunnel_config" }, "created_at": { "$ref": "#/components/schemas/tunnel_timestamp" }, "source": { "$ref": "#/components/schemas/tunnel_config_src-2" }, "tunnel_id": { "$ref": "#/components/schemas/tunnel_tunnel_id-2" }, "version": { "$ref": "#/components/schemas/tunnel_config_version-2" } } }, "tunnel_configuration_response": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-single-2" }, { "properties": { "result": { "$ref": "#/components/schemas/tunnel_configuration" } } } ] }, "tunnel_connection": { "properties": { "colo_name": { "$ref": "#/components/schemas/tunnel_colo_name" }, "is_pending_reconnect": { "$ref": "#/components/schemas/tunnel_is_pending_reconnect" }, "uuid": { "$ref": "#/components/schemas/tunnel_connection_id" } } }, "tunnel_connection_id": { "description": "UUID of the Cloudflare Tunnel connection.", "type": "string", "format": "uuid", "example": "1bedc50d-42b3-473c-b108-ff3d10c0d925", "maxLength": 36, "readOnly": true, "x-auditable": true }, "tunnel_connections": { "description": "The Cloudflare Tunnel connections between your origin and Cloudflare's edge.", "type": "array", "items": { "$ref": "#/components/schemas/tunnel_schemas-connection" } }, "tunnel_connections_deprecated": { "description": "The Cloudflare Tunnel connections between your origin and Cloudflare's edge.", "type": "array", "items": { "$ref": "#/components/schemas/tunnel_schemas-connection" }, "deprecated": true, "x-stainless-deprecation-message": "This field will start returning an empty array. To fetch the connections of a given tunnel, please use the dedicated endpoint `/accounts/{account_id}/{tunnel_type}/{tunnel_id}/connections`" }, "tunnel_conns_active_at": { "description": "Timestamp of when the tunnel established at least one connection to Cloudflare's edge. If `null`, the tunnel is inactive.", "type": "string", "format": "date-time", "example": "2009-11-10T23:00:00Z" }, "tunnel_conns_inactive_at": { "description": "Timestamp of when the tunnel became inactive (no connections to Cloudflare's edge). If `null`, the tunnel is active.", "type": "string", "format": "date-time", "example": "2009-11-10T23:00:00Z" }, "tunnel_created_at": { "description": "Timestamp of when the resource was created.", "type": "string", "format": "date-time", "example": "2021-01-25T18:22:34.317854Z", "readOnly": true }, "tunnel_deleted_at": { "description": "Timestamp of when the resource was deleted. If `null`, the resource has not been deleted.", "type": "string", "format": "date-time", "example": "2009-11-10T23:00:00Z", "readOnly": true }, "tunnel_empty_response": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-common" }, { "properties": { "result": { "type": "object", "enum": [ null ], "nullable": true } }, "type": "object" } ] }, "tunnel_existed_at": { "description": "If provided, include only resources that were created (and not deleted) before this time. URL encoded.", "type": "string", "format": "url-encoded-date-time", "example": "2019-10-12T07%3A20%3A50.52Z" }, "tunnel_features": { "description": "Features enabled for the Cloudflare Tunnel.", "type": "array", "items": { "example": "ha-origin", "type": "string" } }, "tunnel_ha_status": { "description": "The HA status of a WARP Connector client.", "type": "string", "enum": [ "offline", "passive", "active" ], "x-auditable": true }, "tunnel_hostname": { "description": "The hostname of the route.", "type": "string", "example": "office-1.local", "x-auditable": true }, "tunnel_hostname_comment": { "description": "An optional description of the hostname route.", "type": "string", "example": "example comment", "x-auditable": true }, "tunnel_hostname_query_comment": { "description": "If set, only list hostname routes with the given comment.", "type": "string", "example": "example%20comment" }, "tunnel_hostname_route": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/tunnel_hostname_comment" }, "created_at": { "$ref": "#/components/schemas/tunnel_created_at" }, "deleted_at": { "$ref": "#/components/schemas/tunnel_deleted_at" }, "hostname": { "$ref": "#/components/schemas/tunnel_hostname" }, "id": { "$ref": "#/components/schemas/tunnel_hostname_route_id" }, "tun_type": { "allOf": [ { "$ref": "#/components/schemas/tunnel_tunnel_type" }, { "enum": [ "cfd_tunnel", "warp_connector" ], "type": "string" } ] }, "tunnel_id": { "$ref": "#/components/schemas/tunnel_tunnel_id-3" }, "tunnel_name": { "$ref": "#/components/schemas/tunnel_tunnel_name-2" } } }, "tunnel_hostname_route_id": { "description": "The hostname route ID.", "type": "string", "format": "uuid", "example": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415", "x-auditable": true }, "tunnel_hostname_route_response_collection": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tunnel_hostname_route" } } }, "type": "object" } ] }, "tunnel_hostname_route_response_single": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/tunnel_hostname_route" } }, "type": "object" } ] }, "tunnel_icmp_proxy_enabled": { "description": "A flag to enable the ICMP proxy for the account network.", "type": "boolean", "example": true, "x-auditable": true }, "tunnel_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "tunnel_ingressRule": { "description": "Public hostname", "type": "object", "properties": { "hostname": { "description": "Public hostname for this service.", "type": "string", "example": "tunnel.example.com" }, "originRequest": { "$ref": "#/components/schemas/tunnel_originRequest" }, "path": { "description": "Requests with this path route to this public hostname.", "type": "string", "example": "subpath" }, "service": { "description": "Protocol and address of destination server. Supported protocols: http://, https://, unix://, tcp://, ssh://, rdp://, unix+tls://, smb://. Alternatively can return a HTTP status code http_status:[code] e.g. 'http_status:404'.\n", "type": "string", "example": "https://localhost:8001" } }, "required": [ "hostname", "service" ] }, "tunnel_ip": { "type": "string", "example": "10.1.0.137" }, "tunnel_ip_network": { "description": "The private IPv4 or IPv6 range connected by the route, in CIDR notation.", "type": "string", "example": "172.16.0.0/16", "x-auditable": true }, "tunnel_ip_network_encoded": { "description": "IP/CIDR range in URL-encoded format", "type": "string", "example": "172.16.0.0%2F16" }, "tunnel_is_default_network": { "description": "If `true`, this virtual network is the default for the account.", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "tunnel_is_default_network_optional": { "description": "If `true`, this virtual network is the default for the account.", "type": "boolean", "example": false, "default": false, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "tunnel_is_pending_reconnect": { "description": "Cloudflare continues to track connections for several minutes after they disconnect. This is an optimization to improve latency and reliability of reconnecting. If `true`, the connection has disconnected but is still being tracked. If `false`, the connection is actively serving traffic.", "type": "boolean", "example": false, "deprecated": true, "x-fern-ignore": true, "x-stainless-deprecation-message": "This functionality has been removed. The is_pending_reconnect field will now always report false." }, "tunnel_legacy-tunnel-response-collection": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tunnel_argo-tunnel" } } }, "type": "object" } ] }, "tunnel_legacy-tunnel-response-single": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/tunnel_argo-tunnel" } }, "type": "object" } ] }, "tunnel_management-resources": { "description": "Management resources the token will have access to.", "type": "string", "example": "logs", "enum": [ "logs" ] }, "tunnel_mesh_aws_config": { "type": "object", "properties": { "fnr_id": { "description": "Floating Network Resource ID — the secondary ENI that is moved between nodes on failover.", "type": "string", "example": "eni-0123456789abcdef0" } }, "required": [ "fnr_id" ] }, "tunnel_mesh_configuration_request_body": { "type": "object", "properties": { "config": { "description": "Provider-specific configuration. Required shape depends on ha_mode. For `aws`, must contain `fnr_id`. For `local`, must contain `vips`. For `none` and `disabled`, must be empty or omitted.", "type": "object", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/tunnel_mesh_aws_config" }, { "$ref": "#/components/schemas/tunnel_mesh_local_config" }, { "additionalProperties": false, "description": "Empty object for none/disabled modes.", "type": "object" } ] }, "ha_mode": { "$ref": "#/components/schemas/tunnel_mesh_ha_mode" } }, "required": [ "ha_mode" ] }, "tunnel_mesh_configuration_response": { "type": "object", "properties": { "config": { "description": "Provider-specific configuration. Present for `aws` and `local` modes.", "type": "object", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/tunnel_mesh_aws_config" }, { "$ref": "#/components/schemas/tunnel_mesh_local_config" } ] }, "configuration_version": { "description": "Monotonically increasing configuration version, incremented on each PUT.", "type": "integer" }, "created_at": { "$ref": "#/components/schemas/tunnel_created_at" }, "ha_mode": { "$ref": "#/components/schemas/tunnel_mesh_ha_mode" }, "tunnel_id": { "$ref": "#/components/schemas/tunnel_tunnel_id-2" }, "updated_at": { "$ref": "#/components/schemas/tunnel_updated_at" } }, "required": [ "tunnel_id", "configuration_version", "ha_mode", "created_at" ] }, "tunnel_mesh_configuration_response_single": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-single-2" }, { "properties": { "result": { "$ref": "#/components/schemas/tunnel_mesh_configuration_response" } }, "type": "object" } ] }, "tunnel_mesh_ha_mode": { "description": "High-availability mode for the WARP Connector tunnel. `none` means HA is enabled but no provider is configured yet (newly created tunnels default to this). `disabled` means HA is explicitly turned off. `aws` uses AWS ENI move for failover. `local` uses virtual IPs (VIPs) on the local interface.", "type": "string", "example": "aws", "enum": [ "none", "disabled", "aws", "local" ], "x-auditable": true }, "tunnel_mesh_local_config": { "type": "object", "properties": { "vips": { "description": "VIPs to assign on the CloudflareWARP interface.", "type": "array", "items": { "$ref": "#/components/schemas/tunnel_mesh_vip_entry" }, "maxItems": 8, "minItems": 1 }, "vips_previous": { "description": "VIPs to clean up on demotion or version drift.", "type": "array", "items": { "$ref": "#/components/schemas/tunnel_mesh_vip_entry" }, "maxItems": 8 } }, "required": [ "vips" ] }, "tunnel_mesh_vip_entry": { "type": "object", "properties": { "address": { "description": "Virtual IP address (IPv4 or IPv6).", "type": "string", "example": "10.0.0.1" } }, "required": [ "address" ] }, "tunnel_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "tunnel_messages-2": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "tunnel_metadata": { "description": "Metadata associated with the tunnel.", "type": "object", "example": {} }, "tunnel_offramp_warp_enabled": { "description": "A flag to enable WARP to WARP traffic.", "type": "boolean", "example": true, "x-auditable": true }, "tunnel_originRequest": { "description": "Configuration parameters for the public hostname specific connection settings between cloudflared and origin server.", "type": "object", "properties": { "access": { "description": "For all L7 requests to this hostname, cloudflared will validate each request's Cf-Access-Jwt-Assertion request header.", "type": "object", "properties": { "audTag": { "description": "Access applications that are allowed to reach this hostname for this Tunnel. Audience tags can be identified in the dashboard or via the List Access policies API.", "type": "array", "items": { "type": "string" } }, "required": { "description": "Deny traffic that has not fulfilled Access authorization.", "type": "boolean", "example": false }, "teamName": { "type": "string", "example": "zero-trust-organization-name" } }, "required": [ "audTag", "teamName" ] }, "caPool": { "description": "Path to the certificate authority (CA) for the certificate of your origin. This option should be used only if your certificate is not signed by Cloudflare.", "type": "string" }, "connectTimeout": { "description": "Timeout for establishing a new TCP connection to your origin server. This excludes the time taken to establish TLS, which is controlled by tlsTimeout.", "type": "integer", "example": 10 }, "disableChunkedEncoding": { "description": "Disables chunked transfer encoding. Useful if you are running a WSGI server.", "type": "boolean" }, "http2Origin": { "description": "Attempt to connect to origin using HTTP2. Origin must be configured as https.", "type": "boolean" }, "httpHostHeader": { "description": "Sets the HTTP Host header on requests sent to the local service.", "type": "string" }, "keepAliveConnections": { "description": "Maximum number of idle keepalive connections between Tunnel and your origin. This does not restrict the total number of concurrent connections.", "type": "integer", "example": 100 }, "keepAliveTimeout": { "description": "Timeout after which an idle keepalive connection can be discarded.", "type": "integer", "example": 90 }, "matchSNItoHost": { "description": "Auto configure the Hostname on the origin server certificate.", "type": "boolean", "example": false, "x-stainless-naming": { "python": { "name": "match_sni_to_host" } } }, "noHappyEyeballs": { "description": "Disable the “happy eyeballs” algorithm for IPv4/IPv6 fallback if your local network has misconfigured one of the protocols.", "type": "boolean", "example": false }, "noTLSVerify": { "description": "Disables TLS verification of the certificate presented by your origin. Will allow any certificate from the origin to be accepted.", "type": "boolean", "example": false }, "originServerName": { "description": "Hostname that cloudflared should expect from your origin server certificate.", "type": "string" }, "proxyType": { "description": "cloudflared starts a proxy server to translate HTTP traffic into TCP when proxying, for example, SSH or RDP. This configures what type of proxy will be started. Valid options are: \"\" for the regular proxy and \"socks\" for a SOCKS5 proxy.\n", "type": "string" }, "tcpKeepAlive": { "description": "The timeout after which a TCP keepalive packet is sent on a connection between Tunnel and the origin server.", "type": "integer", "example": 30 }, "tlsTimeout": { "description": "Timeout for completing a TLS handshake to your origin server, if you have chosen to connect Tunnel to an HTTPS server.", "type": "integer", "example": 10 } } }, "tunnel_page_number": { "description": "Page number of paginated results.", "type": "number", "default": 1, "minimum": 1 }, "tunnel_per_page": { "description": "Number of results to display.", "type": "number", "maximum": 1000, "minimum": 1 }, "tunnel_remote_config": { "description": "If `true`, the tunnel can be configured remotely from the Zero Trust dashboard. If `false`, the tunnel must be configured locally on the origin machine.", "type": "boolean", "example": true, "deprecated": true, "x-auditable": true, "x-stainless-deprecation-message": "Use the config_src field instead.", "x-stainless-ignore": true }, "tunnel_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters", "type": "number", "example": 2000 } } }, "tunnel_route": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/tunnel_route_comment" }, "created_at": { "$ref": "#/components/schemas/tunnel_created_at" }, "deleted_at": { "$ref": "#/components/schemas/tunnel_deleted_at" }, "id": { "$ref": "#/components/schemas/tunnel_route_id" }, "network": { "$ref": "#/components/schemas/tunnel_ip_network" }, "tunnel_id": { "$ref": "#/components/schemas/tunnel_tunnel_id" }, "virtual_network_id": { "$ref": "#/components/schemas/tunnel_virtual_network_id" } } }, "tunnel_route_comment": { "description": "Optional remark describing the route.", "type": "string", "example": "Example comment for this route.", "default": "", "maxLength": 100, "x-auditable": true }, "tunnel_route_id": { "description": "UUID of the route.", "type": "string", "example": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "readOnly": true }, "tunnel_route_response_single": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/tunnel_route" } }, "type": "object" } ] }, "tunnel_run_at": { "description": "Timestamp of when the tunnel connection was started.", "type": "string", "format": "date-time", "example": "2009-11-10T23:00:00Z" }, "tunnel_schemas-connection": { "properties": { "client_id": { "$ref": "#/components/schemas/tunnel_client_id" }, "client_version": { "$ref": "#/components/schemas/tunnel_version" }, "colo_name": { "$ref": "#/components/schemas/tunnel_colo_name" }, "id": { "$ref": "#/components/schemas/tunnel_connection_id" }, "is_pending_reconnect": { "$ref": "#/components/schemas/tunnel_is_pending_reconnect" }, "opened_at": { "description": "Timestamp of when the connection was established.", "type": "string", "format": "date-time", "example": "2021-01-25T18:22:34.317854Z" }, "origin_ip": { "description": "The public IP address of the host running cloudflared.", "allOf": [ { "$ref": "#/components/schemas/tunnel_ip" } ] }, "uuid": { "$ref": "#/components/schemas/tunnel_connection_id" } } }, "tunnel_schemas-warp-connector-connection": { "properties": { "client_id": { "$ref": "#/components/schemas/tunnel_client_id" }, "client_version": { "$ref": "#/components/schemas/tunnel_version" }, "colo_name": { "$ref": "#/components/schemas/tunnel_colo_name" }, "id": { "$ref": "#/components/schemas/tunnel_connection_id" }, "opened_at": { "description": "Timestamp of when the connection was established.", "type": "string", "format": "date-time", "example": "2021-01-25T18:22:34.317854Z" }, "origin_ip": { "description": "The public IP address of the host running WARP Connector.", "allOf": [ { "$ref": "#/components/schemas/tunnel_ip" } ] } } }, "tunnel_status": { "description": "The status of the tunnel. Valid values are `inactive` (tunnel has never been run), `degraded` (tunnel is active and able to serve traffic but in an unhealthy state), `healthy` (tunnel is active and able to serve traffic), or `down` (tunnel can not serve traffic as it has no connections to the Cloudflare Edge).", "type": "string", "example": "healthy", "enum": [ "inactive", "degraded", "healthy", "down" ] }, "tunnel_subnet": { "type": "object", "properties": { "capacity": { "$ref": "#/components/schemas/tunnel_subnet_capacity" }, "comment": { "$ref": "#/components/schemas/tunnel_subnet_comment" }, "created_at": { "$ref": "#/components/schemas/tunnel_created_at" }, "deleted_at": { "$ref": "#/components/schemas/tunnel_deleted_at" }, "id": { "$ref": "#/components/schemas/tunnel_subnet_id" }, "is_default_network": { "$ref": "#/components/schemas/tunnel_subnet_is_default_network" }, "name": { "$ref": "#/components/schemas/tunnel_subnet_name" }, "network": { "$ref": "#/components/schemas/tunnel_subnet_ip_network" }, "subnet_type": { "$ref": "#/components/schemas/tunnel_subnet_type" } } }, "tunnel_subnet_capacity": { "description": "IP capacity information for the subnet.", "type": "object", "properties": { "total": { "description": "Total number of assignable IPs in the subnet.", "type": "integer", "example": 254 }, "used": { "description": "Number of assigned IPs in the subnet.", "type": "integer", "example": 42 } } }, "tunnel_subnet_comment": { "description": "An optional description of the subnet.", "type": "string", "example": "example comment", "default": "", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "tunnel_subnet_id": { "description": "The UUID of the subnet.", "type": "string", "format": "uuid", "example": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415", "x-auditable": true }, "tunnel_subnet_ip_network": { "description": "The private IPv4 or IPv6 range defining the subnet, in CIDR notation.", "type": "string", "example": "100.64.0.0/12", "x-auditable": true }, "tunnel_subnet_is_default_network": { "description": "If `true`, this is the default subnet for the account. There can only be one default subnet per account.", "type": "boolean", "default": false, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "tunnel_subnet_name": { "description": "A user-friendly name for the subnet.", "type": "string", "example": "IPv4 Cloudflare Source IPs", "x-auditable": true }, "tunnel_subnet_query_comment": { "description": "If set, only list subnets with the given comment.", "type": "string", "example": "example%20comment" }, "tunnel_subnet_query_name": { "description": "If set, only list subnets with the given name", "type": "string", "example": "IPv4%20Cloudflare%20Source%20IPs" }, "tunnel_subnet_response_collection": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tunnel_subnet" } } }, "type": "object" } ] }, "tunnel_subnet_response_single": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/tunnel_subnet" } }, "type": "object" } ] }, "tunnel_subnet_response_single_nullable": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-common" }, { "properties": { "result": { "type": "object", "nullable": true, "properties": { "capacity": { "$ref": "#/components/schemas/tunnel_subnet_capacity" }, "comment": { "$ref": "#/components/schemas/tunnel_subnet_comment" }, "created_at": { "$ref": "#/components/schemas/tunnel_created_at" }, "deleted_at": { "$ref": "#/components/schemas/tunnel_deleted_at" }, "id": { "$ref": "#/components/schemas/tunnel_subnet_id" }, "is_default_network": { "$ref": "#/components/schemas/tunnel_subnet_is_default_network" }, "name": { "$ref": "#/components/schemas/tunnel_subnet_name" }, "network": { "$ref": "#/components/schemas/tunnel_subnet_ip_network" }, "subnet_type": { "$ref": "#/components/schemas/tunnel_subnet_type" } } } }, "type": "object" } ] }, "tunnel_subnet_type": { "description": "The type of subnet.", "type": "string", "example": "cloudflare_source", "enum": [ "cloudflare_source", "initial_resolved_ip", "warp" ], "x-auditable": true }, "tunnel_teamnet": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/tunnel_route_comment" }, "created_at": { "$ref": "#/components/schemas/tunnel_created_at" }, "deleted_at": { "$ref": "#/components/schemas/tunnel_deleted_at" }, "id": { "$ref": "#/components/schemas/tunnel_route_id" }, "network": { "$ref": "#/components/schemas/tunnel_ip_network" }, "tun_type": { "$ref": "#/components/schemas/tunnel_tunnel_type" }, "tunnel_id": { "$ref": "#/components/schemas/tunnel_tunnel_id" }, "tunnel_name": { "$ref": "#/components/schemas/tunnel_tunnel_name" }, "virtual_network_id": { "$ref": "#/components/schemas/tunnel_virtual_network_id_computed_optional" }, "virtual_network_name": { "$ref": "#/components/schemas/tunnel_virtual_network_name" } } }, "tunnel_teamnet_response_collection": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tunnel_teamnet" } } }, "type": "object" } ] }, "tunnel_teamnet_response_single": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/tunnel_teamnet" } }, "type": "object" } ] }, "tunnel_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "x-auditable": true }, "tunnel_tunnel-response-collection": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/tunnel_cfd_tunnel" }, { "$ref": "#/components/schemas/tunnel_warp_connector_tunnel" } ] } } }, "type": "object" } ] }, "tunnel_tunnel_client": { "description": "A client (typically cloudflared) that maintains connections to a Cloudflare data center.", "type": "object", "properties": { "arch": { "$ref": "#/components/schemas/tunnel_arch" }, "config_version": { "$ref": "#/components/schemas/tunnel_config_version" }, "conns": { "$ref": "#/components/schemas/tunnel_connections" }, "features": { "$ref": "#/components/schemas/tunnel_features" }, "id": { "$ref": "#/components/schemas/tunnel_connection_id" }, "run_at": { "$ref": "#/components/schemas/tunnel_run_at" }, "version": { "$ref": "#/components/schemas/tunnel_version" } } }, "tunnel_tunnel_client_response": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/tunnel_tunnel_client" } }, "type": "object" } ] }, "tunnel_tunnel_connections_response": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tunnel_tunnel_client" } } }, "type": "object" } ] }, "tunnel_tunnel_id": { "description": "UUID of the tunnel.", "type": "string", "format": "uuid", "example": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "readOnly": true, "x-auditable": true }, "tunnel_tunnel_id-2": { "description": "UUID of the tunnel.", "type": "string", "format": "uuid", "example": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "readOnly": true }, "tunnel_tunnel_id-3": { "description": "UUID of the tunnel.", "type": "string", "format": "uuid", "example": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "x-auditable": true }, "tunnel_tunnel_link": { "description": "The id of the tunnel linked and the date that link was created.", "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/tunnel_created_at" }, "linked_tunnel_id": { "$ref": "#/components/schemas/tunnel_tunnel_id" } } }, "tunnel_tunnel_links_response": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tunnel_tunnel_link" } } }, "type": "object" } ] }, "tunnel_tunnel_name": { "description": "A user-friendly name for a tunnel.", "type": "string", "example": "blog" }, "tunnel_tunnel_name-2": { "description": "A user-friendly name for a tunnel.", "type": "string", "example": "api-tunnel" }, "tunnel_tunnel_response_token": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/tunnel_tunnel_token" } }, "type": "object" } ] }, "tunnel_tunnel_secret": { "description": "Sets the password required to run a locally-managed tunnel. Must be at least 32 bytes and encoded as a base64 string.", "type": "string", "example": "AQIDBAUGBwgBAgMEBQYHCAECAwQFBgcIAQIDBAUGBwg=", "x-sensitive": true }, "tunnel_tunnel_token": { "description": "The Tunnel Token is used as a mechanism to authenticate the operation of a tunnel.", "type": "string", "example": "eyJhIjoiNWFiNGU5Z...", "readOnly": true, "x-sensitive": true }, "tunnel_tunnel_type": { "description": "The type of tunnel.", "type": "string", "example": "cfd_tunnel", "enum": [ "cfd_tunnel", "warp_connector", "warp", "magic", "ip_sec", "gre", "cni" ], "x-auditable": true }, "tunnel_tunnel_types": { "description": "The types of tunnels to filter by, separated by commas.", "type": "array", "items": { "$ref": "#/components/schemas/tunnel_tunnel_type" }, "example": "cfd_tunnel,warp_connector" }, "tunnel_tunnel_warp_connector_client": { "description": "A WARP Connector client that maintains a connection to a Cloudflare data center.", "type": "object", "properties": { "arch": { "$ref": "#/components/schemas/tunnel_arch" }, "conns": { "$ref": "#/components/schemas/tunnel_warp_connector_connections" }, "features": { "$ref": "#/components/schemas/tunnel_features" }, "ha_status": { "$ref": "#/components/schemas/tunnel_ha_status" }, "id": { "$ref": "#/components/schemas/tunnel_client_id" }, "run_at": { "$ref": "#/components/schemas/tunnel_run_at" }, "version": { "$ref": "#/components/schemas/tunnel_version" } } }, "tunnel_tunnel_warp_connector_client_response": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/tunnel_tunnel_warp_connector_client" } }, "type": "object" } ] }, "tunnel_tunnel_warp_connector_connections_response": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tunnel_tunnel_warp_connector_client" } } }, "type": "object" } ] }, "tunnel_updated_at": { "description": "Timestamp of the last update. Null if never updated.", "type": "string", "format": "date-time", "example": "2021-01-25T18:22:34.317854Z", "nullable": true, "readOnly": true }, "tunnel_version": { "description": "The cloudflared version used to establish this connection.", "type": "string", "example": "2022.7.1" }, "tunnel_virtual-network": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/tunnel_virtual_network_comment" }, "created_at": { "$ref": "#/components/schemas/tunnel_created_at" }, "deleted_at": { "$ref": "#/components/schemas/tunnel_deleted_at" }, "id": { "$ref": "#/components/schemas/tunnel_virtual_network_id" }, "is_default_network": { "$ref": "#/components/schemas/tunnel_is_default_network" }, "name": { "$ref": "#/components/schemas/tunnel_virtual_network_name" } }, "required": [ "id", "name", "is_default_network", "comment", "created_at" ] }, "tunnel_virtual_network_comment": { "description": "Optional remark describing the virtual network.", "type": "string", "example": "Staging VPC for data science", "default": "", "maxLength": 256, "x-auditable": true }, "tunnel_virtual_network_id": { "description": "UUID of the virtual network.", "type": "string", "format": "uuid", "example": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415", "x-auditable": true }, "tunnel_virtual_network_id_computed_optional": { "description": "UUID of the virtual network.", "type": "string", "format": "uuid", "example": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "tunnel_virtual_network_name": { "description": "A user-friendly name for the virtual network.", "type": "string", "example": "us-east-1-vpc", "maxLength": 256, "x-auditable": true }, "tunnel_vnet_response_collection": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tunnel_virtual-network" } } }, "type": "object" } ] }, "tunnel_vnet_response_single": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/tunnel_virtual-network" } }, "type": "object" } ] }, "tunnel_warp-connector-response-collection": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/tunnel_warp_connector_tunnel" } } }, "type": "object" } ] }, "tunnel_warp-connector-response-single": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/tunnel_warp_connector_tunnel" } }, "type": "object" } ] }, "tunnel_warp_connector_connections": { "description": "The WARP Connector Tunnel connections between your origin and Cloudflare's edge.", "type": "array", "items": { "$ref": "#/components/schemas/tunnel_schemas-warp-connector-connection" } }, "tunnel_warp_connector_tunnel": { "description": "A Warp Connector Tunnel that connects your origin to Cloudflare's edge.", "type": "object", "properties": { "account_tag": { "$ref": "#/components/schemas/tunnel_account_id" }, "connections": { "$ref": "#/components/schemas/tunnel_connections_deprecated" }, "conns_active_at": { "$ref": "#/components/schemas/tunnel_conns_active_at" }, "conns_inactive_at": { "$ref": "#/components/schemas/tunnel_conns_inactive_at" }, "created_at": { "$ref": "#/components/schemas/tunnel_created_at" }, "deleted_at": { "$ref": "#/components/schemas/tunnel_deleted_at" }, "id": { "$ref": "#/components/schemas/tunnel_tunnel_id" }, "metadata": { "$ref": "#/components/schemas/tunnel_metadata" }, "name": { "$ref": "#/components/schemas/tunnel_tunnel_name" }, "status": { "$ref": "#/components/schemas/tunnel_status" }, "tun_type": { "$ref": "#/components/schemas/tunnel_tunnel_type" } } }, "tunnel_zero_trust_connectivity_settings_response": { "allOf": [ { "$ref": "#/components/schemas/tunnel_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "icmp_proxy_enabled": { "$ref": "#/components/schemas/tunnel_icmp_proxy_enabled" }, "offramp_warp_enabled": { "$ref": "#/components/schemas/tunnel_offramp_warp_enabled" } } } }, "type": "object" } ] }, "turnstile_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/turnstile_messages" }, "messages": { "$ref": "#/components/schemas/turnstile_messages" }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages" ] }, "turnstile_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/turnstile_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/turnstile_messages" } ] }, "result": { "type": "object", "nullable": true }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": false } }, "required": [ "success", "errors", "messages", "result" ] }, "turnstile_bot_fight_mode": { "description": "If bot_fight_mode is set to `true`, Cloudflare issues computationally\nexpensive challenges in response to malicious bots (ENT only).\n", "type": "boolean", "example": false, "x-auditable": true }, "turnstile_clearance_level": { "description": "If Turnstile is embedded on a Cloudflare site and the widget should grant challenge clearance,\nthis setting can determine the clearance level to be set\n", "type": "string", "example": "interactive", "enum": [ "no_clearance", "jschallenge", "managed", "interactive" ], "x-auditable": true }, "turnstile_created_on": { "description": "When the widget was created.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.123123Z", "readOnly": true }, "turnstile_deployed_via": { "description": "Origin that created this widget, recorded at creation time and\nimmutable afterward. Server-derived from the create request; not\nclient-settable. Omitted from the response for widgets created\nbefore this field existed.\n", "type": "string", "example": "wrangler", "enum": [ "wrangler", "dashboard", "spin", "api", "unknown" ], "readOnly": true, "x-auditable": true }, "turnstile_domains": { "type": "array", "items": { "description": "Hosts as a hostname or IPv4/IPv6 address represented by strings. The\nwidget will only work on these domains, and their subdomains.\n", "example": "203.0.113.1", "type": "string", "x-auditable": true }, "example": [ "203.0.113.1", "cloudflare.com", "blog.example.com" ], "maxLength": 10 }, "turnstile_ephemeral_id": { "description": "Return the Ephemeral ID in /siteverify (ENT only).\n", "type": "boolean", "example": false, "x-auditable": true }, "turnstile_identifier": { "description": "Identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "turnstile_invalidate_immediately": { "description": "If `invalidate_immediately` is set to `false`, the previous secret will\nremain valid for two hours. Otherwise, the secret is immediately\ninvalidated, and requests using it will be rejected.\n", "type": "boolean", "default": false, "x-auditable": true }, "turnstile_last_modified_via": { "description": "Origin of the most recent mutation (create, update, delete, or\nsecret rotation). Server-derived; not client-settable. Omitted for\nwidgets last mutated before this field existed.\n", "type": "string", "example": "dashboard", "enum": [ "wrangler", "dashboard", "spin", "api", "unknown" ], "readOnly": true, "x-auditable": true }, "turnstile_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "turnstile_modified_on": { "description": "When the widget was modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.123123Z", "readOnly": true }, "turnstile_name": { "description": "Human readable widget name. Not unique. Cloudflare suggests that you\nset this to a meaningful string to make it easier to identify your\nwidget, and where it is used.\n", "type": "string", "example": "blog.cloudflare.com login form", "maxLength": 254, "minLength": 1, "x-auditable": true }, "turnstile_offlabel": { "description": "Do not show any Cloudflare branding on the widget (ENT only).\n", "type": "boolean", "example": false, "x-auditable": true }, "turnstile_region": { "description": "Region where this widget can be used. This cannot be changed after creation.\n", "type": "string", "default": "world", "enum": [ "world", "china" ], "x-auditable": true }, "turnstile_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters", "type": "number", "example": 2000 } }, "required": [ "page", "per_page", "count", "total_count" ] }, "turnstile_secret": { "description": "Secret key for this widget.", "type": "string", "example": "0x4AAF00AAAABn0R22HWm098HVBjhdsYUc", "x-sensitive": true }, "turnstile_sitekey": { "description": "Widget item identifier tag.", "type": "string", "example": "0x4AAF00AAAABn0R22HWm-YUc", "maxLength": 32, "x-auditable": true }, "turnstile_widget_detail": { "description": "A Turnstile widget's detailed configuration", "type": "object", "properties": { "bot_fight_mode": { "$ref": "#/components/schemas/turnstile_bot_fight_mode" }, "clearance_level": { "$ref": "#/components/schemas/turnstile_clearance_level" }, "created_on": { "$ref": "#/components/schemas/turnstile_created_on" }, "deployed_via": { "$ref": "#/components/schemas/turnstile_deployed_via" }, "domains": { "$ref": "#/components/schemas/turnstile_domains" }, "ephemeral_id": { "$ref": "#/components/schemas/turnstile_ephemeral_id" }, "last_modified_via": { "$ref": "#/components/schemas/turnstile_last_modified_via" }, "mode": { "$ref": "#/components/schemas/turnstile_widget_mode" }, "modified_on": { "$ref": "#/components/schemas/turnstile_modified_on" }, "name": { "$ref": "#/components/schemas/turnstile_name" }, "offlabel": { "$ref": "#/components/schemas/turnstile_offlabel" }, "region": { "$ref": "#/components/schemas/turnstile_region" }, "secret": { "$ref": "#/components/schemas/turnstile_secret" }, "sitekey": { "$ref": "#/components/schemas/turnstile_sitekey" } }, "required": [ "sitekey", "secret", "created_on", "modified_on", "name", "domains", "mode", "region", "bot_fight_mode", "offlabel", "clearance_level", "ephemeral_id" ] }, "turnstile_widget_list": { "description": "A Turnstile Widgets configuration as it appears in listings", "type": "object", "properties": { "bot_fight_mode": { "$ref": "#/components/schemas/turnstile_bot_fight_mode" }, "clearance_level": { "$ref": "#/components/schemas/turnstile_clearance_level" }, "created_on": { "$ref": "#/components/schemas/turnstile_created_on" }, "deployed_via": { "$ref": "#/components/schemas/turnstile_deployed_via" }, "domains": { "$ref": "#/components/schemas/turnstile_domains" }, "ephemeral_id": { "$ref": "#/components/schemas/turnstile_ephemeral_id" }, "last_modified_via": { "$ref": "#/components/schemas/turnstile_last_modified_via" }, "mode": { "$ref": "#/components/schemas/turnstile_widget_mode" }, "modified_on": { "$ref": "#/components/schemas/turnstile_modified_on" }, "name": { "$ref": "#/components/schemas/turnstile_name" }, "offlabel": { "$ref": "#/components/schemas/turnstile_offlabel" }, "region": { "$ref": "#/components/schemas/turnstile_region" }, "sitekey": { "$ref": "#/components/schemas/turnstile_sitekey" } }, "required": [ "sitekey", "created_on", "modified_on", "name", "domains", "mode", "region", "bot_fight_mode", "offlabel", "clearance_level", "ephemeral_id" ] }, "turnstile_widget_mode": { "description": "Widget Mode", "type": "string", "example": "invisible", "enum": [ "non-interactive", "invisible", "managed" ], "x-auditable": true }, "usage-analytics_api_error": { "type": "object", "properties": { "code": { "description": "Error code.", "type": "integer", "example": 10010 }, "message": { "description": "Human-readable error message.", "type": "string", "example": "Bad Request" } }, "required": [ "code", "message" ] }, "usage-analytics_api_message": { "type": "object", "properties": { "code": { "description": "Message code.", "type": "integer", "example": 0 }, "message": { "description": "Human-readable message.", "type": "string", "example": "" } }, "required": [ "code", "message" ] }, "usage-analytics_billing_usage_data_point": { "description": "A single billing usage data point for a time period, containing metrics for all billable products.\n", "type": "object", "properties": { "argoAcceleratedBytes": { "description": "Number of Argo accelerated bytes in this time period.", "type": "integer", "format": "int64", "example": 5000000 }, "imageResizingRequests": { "description": "Number of Image Resizing requests in this time period.", "type": "integer", "format": "int64", "example": 15000 }, "loadBalancingQueries": { "description": "Number of Load Balancing DNS queries in this time period.", "type": "integer", "format": "int64", "example": 10000 }, "mediaUniqueTransformations": { "description": "Number of Media unique image transformations in this time period.", "type": "integer", "format": "int64", "example": 45000 }, "rateLimitingRequestsAllowed": { "description": "Number of Rate Limiting requests allowed in this time period.", "type": "integer", "format": "int64", "example": 50000 }, "spectrumBytesTransferred": { "description": "Number of Spectrum bytes transferred in this time period.", "type": "integer", "format": "int64", "example": 8000000 }, "streamMinutesViewed": { "description": "Number of Stream billable minutes viewed in this time period.", "type": "integer", "format": "int64", "example": 125000 }, "ts": { "description": "Unix timestamp (epoch seconds) for the start of this time period.", "type": "integer", "format": "int64", "example": 1693526400 }, "workersKVReads": { "description": "Number of Workers KV reads in this time period.", "type": "integer", "format": "int64", "example": 30000 }, "workersRequests": { "description": "Number of Workers requests in this time period.", "type": "integer", "format": "int64", "example": 200000 } } }, "usage-analytics_billing_usage_response": { "description": "Standard Cloudflare v4 API response containing billing usage analytics data.", "type": "object", "properties": { "errors": { "description": "List of errors, empty on success.", "type": "array", "items": { "$ref": "#/components/schemas/usage-analytics_api_error" } }, "messages": { "description": "List of informational messages.", "type": "array", "items": { "$ref": "#/components/schemas/usage-analytics_api_message" } }, "result": { "description": "Array of billing usage data points for the requested time range.", "type": "array", "items": { "$ref": "#/components/schemas/usage-analytics_billing_usage_data_point" } }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true } }, "required": [ "success", "result", "errors" ] }, "usage-analytics_error_response": { "description": "Standard Cloudflare v4 API error response.", "type": "object", "properties": { "errors": { "description": "List of errors.", "type": "array", "items": { "$ref": "#/components/schemas/usage-analytics_api_error" } }, "messages": { "description": "List of informational messages.", "type": "array", "items": { "$ref": "#/components/schemas/usage-analytics_api_message" } }, "result": { "description": "Empty array or null on error.", "type": "array", "items": { "type": "object" }, "example": [], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false } }, "required": [ "success", "errors" ] }, "usage-analytics_identifier": { "description": "Cloudflare resource identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 }, "usage-analytics_stream_usage_data_point": { "description": "A single Stream usage data point for a time period.", "type": "object", "properties": { "streamMinutesViewed": { "description": "Number of Stream billable minutes viewed in this time period.", "type": "integer", "format": "int64", "example": 12500 }, "ts": { "description": "Unix timestamp (epoch seconds) for the start of this time period.", "type": "integer", "format": "int64", "example": 1693526400 } } }, "usage-analytics_stream_usage_response": { "description": "Standard Cloudflare v4 API response containing Stream usage analytics data.", "type": "object", "properties": { "errors": { "description": "List of errors, empty on success.", "type": "array", "items": { "$ref": "#/components/schemas/usage-analytics_api_error" } }, "messages": { "description": "List of informational messages.", "type": "array", "items": { "$ref": "#/components/schemas/usage-analytics_api_message" } }, "result": { "description": "Array of usage data points for the requested time range.", "type": "array", "items": { "$ref": "#/components/schemas/usage-analytics_stream_usage_data_point" } }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true } }, "required": [ "success", "result", "errors" ] }, "vectorize_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-common" }, { "properties": { "result": { "type": "array", "items": {}, "nullable": true }, "result_info": { "$ref": "#/components/schemas/vectorize_result_info" } } } ] }, "vectorize_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/vectorize_messages" }, "messages": { "$ref": "#/components/schemas/vectorize_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": {}, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "vectorize_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/vectorize_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/vectorize_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "vectorize_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/vectorize_api-response-common" }, { "properties": { "result": { "type": "object", "anyOf": [ { "type": "object" }, { "type": "string" } ], "nullable": true } } } ] }, "vectorize_create-index-request": { "type": "object", "properties": { "config": { "allOf": [ { "$ref": "#/components/schemas/vectorize_index-configuration" } ] }, "description": { "$ref": "#/components/schemas/vectorize_index-description" }, "name": { "$ref": "#/components/schemas/vectorize_index-name" } }, "required": [ "name", "config" ] }, "vectorize_create-index-response": { "type": "object", "properties": { "config": { "$ref": "#/components/schemas/vectorize_index-dimension-configuration" }, "created_on": { "description": "Specifies the timestamp the resource was created as an ISO8601 string.", "type": "string", "format": "date-time", "example": "2022-11-15T18:25:44.442097Z", "readOnly": true, "x-auditable": true }, "description": { "$ref": "#/components/schemas/vectorize_index-description" }, "modified_on": { "description": "Specifies the timestamp the resource was modified as an ISO8601 string.", "type": "string", "format": "date-time", "example": "2022-11-15T18:25:44.442097Z", "readOnly": true, "x-auditable": true }, "name": { "$ref": "#/components/schemas/vectorize_index-name" } } }, "vectorize_create-metadata-index-request": { "type": "object", "properties": { "indexType": { "description": "Specifies the type of metadata property to index.", "type": "string", "enum": [ "string", "number", "boolean" ], "x-auditable": true }, "propertyName": { "description": "Specifies the metadata property to index.", "type": "string", "example": "random_metadata_property", "x-auditable": true } }, "required": [ "propertyName", "indexType" ] }, "vectorize_create-metadata-index-response": { "type": "object", "properties": { "mutationId": { "$ref": "#/components/schemas/vectorize_mutation-uuid" } } }, "vectorize_delete-metadata-index-request": { "type": "object", "properties": { "propertyName": { "description": "Specifies the metadata property for which the index must be deleted.", "type": "string", "example": "random_metadata_property", "x-auditable": true } }, "required": [ "propertyName" ] }, "vectorize_delete-metadata-index-response": { "type": "object", "properties": { "mutationId": { "$ref": "#/components/schemas/vectorize_mutation-uuid" } } }, "vectorize_identifier": { "description": "Identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "vectorize_index-configuration": { "description": "Specifies the type of configuration to use for the index.", "oneOf": [ { "$ref": "#/components/schemas/vectorize_index-dimension-configuration" }, { "$ref": "#/components/schemas/vectorize_index-preset-configuration" } ] }, "vectorize_index-delete-vectors-by-id-request": { "type": "object", "properties": { "ids": { "description": "A list of vector identifiers to delete from the index indicated by the path.", "type": "array", "items": { "$ref": "#/components/schemas/vectorize_vector-identifier" }, "example": [ "5121db81354a40c6aedc3fe1ace51c59", "f90eb49c2107486abdfd78c67e853430" ] } } }, "vectorize_index-delete-vectors-by-id-response": { "type": "object", "properties": { "count": { "description": "The count of the vectors successfully deleted.", "type": "integer", "example": 42 }, "ids": { "description": "Array of vector identifiers of the vectors that were successfully processed for deletion.", "type": "array", "items": { "$ref": "#/components/schemas/vectorize_vector-identifier" } } } }, "vectorize_index-delete-vectors-by-id-v2-response": { "type": "object", "properties": { "mutationId": { "$ref": "#/components/schemas/vectorize_mutation-uuid" } } }, "vectorize_index-description": { "description": "Specifies the description of the index.", "type": "string", "example": "This is my example index.", "x-auditable": true }, "vectorize_index-dimension-configuration": { "type": "object", "properties": { "dimensions": { "$ref": "#/components/schemas/vectorize_index-dimensions" }, "metric": { "$ref": "#/components/schemas/vectorize_index-metric" } }, "required": [ "dimensions", "metric" ] }, "vectorize_index-dimensions": { "description": "Specifies the number of dimensions for the index", "type": "integer", "example": 768, "maximum": 1536, "minimum": 1, "x-auditable": true }, "vectorize_index-get-vectors-by-id-request": { "type": "object", "properties": { "ids": { "description": "A list of vector identifiers to retrieve from the index indicated by the path.", "type": "array", "items": { "$ref": "#/components/schemas/vectorize_vector-identifier" }, "example": [ "5121db81354a40c6aedc3fe1ace51c59", "f90eb49c2107486abdfd78c67e853430" ] } } }, "vectorize_index-get-vectors-by-id-response": { "description": "Array of vectors with matching ids.", "type": "array", "items": { "properties": { "id": { "$ref": "#/components/schemas/vectorize_vector-identifier" }, "metadata": { "type": "object" }, "namespace": { "type": "string", "nullable": true }, "values": { "type": "array", "items": { "type": "number" } } }, "type": "object" }, "example": [ { "id": "some-vector-id", "metadata": { "another-key": "another-value", "customer-id": 442 }, "values": [ 0.812, 0.621, 0.261 ] }, { "id": "other-vector-id", "metadata": { "another-key": "with-a-value", "customer-id": 2151 }, "namespace": "namespaced", "values": [ 0.961, 0.751, 0.661 ] } ] }, "vectorize_index-info-response": { "type": "object", "properties": { "dimensions": { "$ref": "#/components/schemas/vectorize_index-dimensions" }, "processedUpToDatetime": { "description": "Specifies the timestamp the last mutation batch was processed as an ISO8601 string.", "type": "string", "format": "date-time", "example": "2024-07-22T18:25:44.442097Z", "nullable": true, "readOnly": true, "x-auditable": true }, "processedUpToMutation": { "$ref": "#/components/schemas/vectorize_mutation-uuid" }, "vectorCount": { "description": "Specifies the number of vectors present in the index", "type": "integer", "example": 300000, "x-auditable": true } } }, "vectorize_index-insert-response": { "type": "object", "properties": { "count": { "description": "Specifies the count of the vectors successfully inserted.", "type": "integer", "example": 768, "x-auditable": true }, "ids": { "description": "Array of vector identifiers of the vectors successfully inserted.", "type": "array", "items": { "$ref": "#/components/schemas/vectorize_vector-identifier" } } } }, "vectorize_index-insert-v2-response": { "type": "object", "properties": { "mutationId": { "$ref": "#/components/schemas/vectorize_mutation-uuid" } } }, "vectorize_index-list-vectors-response": { "type": "object", "properties": { "count": { "description": "Number of vectors returned in this response", "type": "integer", "example": 100 }, "cursorExpirationTimestamp": { "description": "When the cursor expires as an ISO8601 string", "type": "string", "format": "date-time", "example": "2025-08-12T20:32:52.469144957Z", "nullable": true }, "isTruncated": { "description": "Whether there are more vectors available beyond this response", "type": "boolean", "example": true }, "nextCursor": { "description": "Cursor for the next page of results", "type": "string", "example": "suUTaDY5PFUiRweVccnzyt9n75suNPbXHPshvCzue5mHjtj7Letjvzlza9eGj099", "nullable": true }, "totalCount": { "description": "Total number of vectors in the index", "type": "integer", "example": 500 }, "vectors": { "description": "Array of vector items", "type": "array", "items": { "$ref": "#/components/schemas/vectorize_vector-list-item" } } }, "required": [ "count", "totalCount", "isTruncated", "vectors" ] }, "vectorize_index-metric": { "description": "Specifies the type of metric to use calculating distance.", "type": "string", "enum": [ "cosine", "euclidean", "dot-product" ], "x-auditable": true }, "vectorize_index-name": { "type": "string", "example": "example-index", "pattern": "^([a-z]+[a-z0-9_-]*[a-z0-9]+)$", "x-auditable": true }, "vectorize_index-preset": { "description": "Specifies the preset to use for the index.", "type": "string", "example": "@cf/baai/bge-small-en-v1.5", "enum": [ "@cf/baai/bge-small-en-v1.5", "@cf/baai/bge-base-en-v1.5", "@cf/baai/bge-large-en-v1.5", "openai/text-embedding-ada-002", "cohere/embed-multilingual-v2.0" ], "x-auditable": true }, "vectorize_index-preset-configuration": { "type": "object", "properties": { "preset": { "$ref": "#/components/schemas/vectorize_index-preset" } }, "required": [ "preset" ] }, "vectorize_index-query-request": { "type": "object", "properties": { "filter": { "description": "A metadata filter expression used to limit nearest neighbor results.", "type": "object", "example": { "has_viewed": { "$ne": true }, "streaming_platform": "netflix" } }, "returnMetadata": { "description": "Whether to return the metadata associated with the closest vectors.", "type": "boolean", "default": false }, "returnValues": { "description": "Whether to return the values associated with the closest vectors.", "type": "boolean", "default": false }, "topK": { "description": "The number of nearest neighbors to find.", "type": "number", "example": 5, "default": 5 }, "vector": { "description": "The search vector that will be used to find the nearest neighbors.", "type": "array", "items": { "type": "number" }, "example": [ 0.5, 0.5, 0.5 ] } }, "required": [ "vector" ] }, "vectorize_index-query-response": { "type": "object", "properties": { "count": { "description": "Specifies the count of vectors returned by the search", "type": "integer" }, "matches": { "description": "Array of vectors matched by the search", "type": "array", "items": { "properties": { "id": { "$ref": "#/components/schemas/vectorize_vector-identifier" }, "metadata": { "type": "object", "nullable": true }, "score": { "description": "The score of the vector according to the index's distance metric", "type": "number" }, "values": { "type": "array", "items": { "type": "number" }, "nullable": true } }, "type": "object" } } } }, "vectorize_index-query-v2-request": { "type": "object", "properties": { "filter": { "description": "A metadata filter expression used to limit nearest neighbor results.", "type": "object", "example": { "has_viewed": { "$ne": true }, "streaming_platform": "netflix" } }, "returnMetadata": { "description": "Whether to return no metadata, indexed metadata or all metadata associated with the closest vectors.", "type": "string", "default": "none", "enum": [ "none", "indexed", "all" ] }, "returnValues": { "description": "Whether to return the values associated with the closest vectors.", "type": "boolean", "default": false }, "topK": { "description": "The number of nearest neighbors to find.", "type": "number", "example": 5, "default": 5 }, "vector": { "description": "The search vector that will be used to find the nearest neighbors.", "type": "array", "items": { "type": "number" }, "example": [ 0.5, 0.5, 0.5 ] } }, "required": [ "vector" ] }, "vectorize_index-query-v2-response": { "type": "object", "properties": { "count": { "description": "Specifies the count of vectors returned by the search", "type": "integer" }, "matches": { "description": "Array of vectors matched by the search", "type": "array", "items": { "properties": { "id": { "$ref": "#/components/schemas/vectorize_vector-identifier" }, "metadata": { "type": "object", "nullable": true }, "namespace": { "type": "string", "nullable": true }, "score": { "description": "The score of the vector according to the index's distance metric", "type": "number" }, "values": { "type": "array", "items": { "type": "number" }, "nullable": true } }, "type": "object" } } } }, "vectorize_index-upsert-response": { "type": "object", "properties": { "count": { "description": "Specifies the count of the vectors successfully inserted.", "type": "integer", "example": 768, "x-auditable": true }, "ids": { "description": "Array of vector identifiers of the vectors successfully inserted.", "type": "array", "items": { "$ref": "#/components/schemas/vectorize_vector-identifier" } } } }, "vectorize_index-upsert-v2-response": { "type": "object", "properties": { "mutationId": { "$ref": "#/components/schemas/vectorize_mutation-uuid" } } }, "vectorize_list-metadata-index-response": { "type": "object", "properties": { "metadataIndexes": { "description": "Array of indexed metadata properties.", "type": "array", "items": { "properties": { "indexType": { "description": "Specifies the type of indexed metadata property.", "type": "string", "enum": [ "string", "number", "boolean" ], "x-auditable": true }, "propertyName": { "description": "Specifies the indexed metadata property.", "type": "string", "example": "random_metadata_property", "x-auditable": true } }, "type": "object" } } }, "example": { "metadataIndexes": [ { "indexType": "number", "propertyName": "some-num-prop" }, { "indexType": "string", "propertyName": "some-str-prop" }, { "indexType": "boolean", "propertyName": "some-bool-prop" } ] } }, "vectorize_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "vectorize_mutation-uuid": { "description": "The unique identifier for the async mutation operation containing the changeset.", "example": "0000aaaa-11bb-22cc-33dd-444444eeeeee", "maxLength": 36, "x-auditable": true }, "vectorize_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters", "type": "number", "example": 2000 } } }, "vectorize_update-index-request": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/vectorize_index-description" } }, "required": [ "description" ] }, "vectorize_vector-identifier": { "description": "Identifier for a Vector", "type": "string", "example": "some-vector-id-023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 64, "readOnly": true }, "vectorize_vector-list-item": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/vectorize_vector-identifier" } }, "required": [ "id" ] }, "vuln_scanner_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "vuln_scanner_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/vuln_scanner_messages" }, "messages": { "$ref": "#/components/schemas/vuln_scanner_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "vuln_scanner_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "vuln_scanner_bola-assertion-kind": { "description": "The kind of assertion to make.", "oneOf": [ { "description": "Assert that an HTTP status code is within a range, e.g. to assert success for the 2xx range, or expected failure for the 4xx/5xx range.", "properties": { "parameters": { "$ref": "#/components/schemas/vuln_scanner_bola-http-status-range" }, "type": { "type": "string", "enum": [ "http_status_within_range" ] } }, "required": [ "type", "parameters" ], "type": "object" } ] }, "vuln_scanner_bola-body-response": { "description": "HTTP response body preview.", "discriminator": { "mapping": { "bytes": "#/components/schemas/vuln_scanner_bola-body-response-bytes", "json": "#/components/schemas/vuln_scanner_bola-body-response-json", "not_found": "#/components/schemas/vuln_scanner_bola-body-response-not-found", "text": "#/components/schemas/vuln_scanner_bola-body-response-text" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/vuln_scanner_bola-body-response-not-found" }, { "$ref": "#/components/schemas/vuln_scanner_bola-body-response-bytes" }, { "$ref": "#/components/schemas/vuln_scanner_bola-body-response-text" }, { "$ref": "#/components/schemas/vuln_scanner_bola-body-response-json" } ] }, "vuln_scanner_bola-body-response-bytes": { "description": "Body received but unable to read as UTF-8. Raw bytes, base64-encoded.", "type": "object", "properties": { "contents": { "type": "string" }, "kind": { "type": "string", "enum": [ "bytes" ] }, "truncated": { "type": "boolean" } }, "required": [ "kind", "contents", "truncated" ] }, "vuln_scanner_bola-body-response-json": { "description": "Body received as valid JSON.", "type": "object", "properties": { "contents": { "type": "string" }, "kind": { "type": "string", "enum": [ "json" ] }, "truncated": { "type": "boolean" } }, "required": [ "kind", "contents", "truncated" ] }, "vuln_scanner_bola-body-response-not-found": { "description": "No body was received.", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "not_found" ] } }, "required": [ "kind" ] }, "vuln_scanner_bola-body-response-text": { "description": "Body received as valid UTF-8 text but not valid JSON.", "type": "object", "properties": { "contents": { "type": "string" }, "kind": { "type": "string", "enum": [ "text" ] }, "truncated": { "type": "boolean" } }, "required": [ "kind", "contents", "truncated" ] }, "vuln_scanner_bola-credential-role": { "description": "Identifies the role a request was made with. The credential set governs this role. `owner` is the resource owner, `attacker` attempts to access resources.", "type": "string", "enum": [ "owner", "attacker" ] }, "vuln_scanner_bola-credential-sets": { "description": "Credential set references for a BOLA scan. The scanner uses the\n`owner` credentials for legitimate requests and the `attacker`\ncredentials to attempt unauthorized access.\n", "type": "object", "properties": { "attacker": { "description": "Credential set ID for the attacker.", "type": "string", "format": "uuid" }, "owner": { "description": "Credential set ID for the resource owner.", "type": "string", "format": "uuid" } }, "required": [ "owner", "attacker" ] }, "vuln_scanner_bola-http-status-range": { "description": "Range of HTTP status codes.", "type": "object", "properties": { "max": { "description": "Maximum (inclusive) status code of the range.", "type": "integer", "maximum": 65535, "minimum": 0 }, "min": { "description": "Minimum (inclusive) status code of the range.", "type": "integer", "maximum": 65535, "minimum": 0 } }, "required": [ "min", "max" ] }, "vuln_scanner_bola-method": { "description": "HTTP method.", "type": "string", "enum": [ "GET", "DELETE", "PATCH", "POST", "PUT" ] }, "vuln_scanner_bola-outcome": { "description": "Outcome of an assertion. `ok` means the assertion passed, `fail` means the assertion failed, `inconclusive` means the scanner could not evaluate the assertion.", "type": "string", "enum": [ "ok", "fail", "inconclusive" ] }, "vuln_scanner_bola-report": { "description": "A BOLA vulnerability scan report, versioned for future evolution.", "type": "object", "properties": { "report": { "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_bola-report-v1" } ] }, "report_schema_version": { "description": "Version of the report schema.", "type": "string", "enum": [ "v1" ] } }, "required": [ "report_schema_version", "report" ] }, "vuln_scanner_bola-report-summary": { "description": "Overall report summary.", "type": "object", "properties": { "verdict": { "description": "Overall verdict of the vulnerability scan.", "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_bola-verdict" } ] } }, "required": [ "verdict" ] }, "vuln_scanner_bola-report-v1": { "description": "Version 1 of the BOLA vulnerability scan report.", "type": "object", "properties": { "summary": { "description": "Summary of all steps and findings.", "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_bola-report-summary" } ] }, "tests": { "description": "List of tests that were run.", "type": "array", "items": { "$ref": "#/components/schemas/vuln_scanner_bola-test" } } }, "required": [ "summary", "tests" ] }, "vuln_scanner_bola-test": { "description": "Result of a single test.", "type": "object", "properties": { "preflight_errors": { "description": "Errors that prevented step execution.", "type": "array", "items": { "$ref": "#/components/schemas/vuln_scanner_bola-test-error" } }, "steps": { "description": "Steps that were executed.", "type": "array", "items": { "$ref": "#/components/schemas/vuln_scanner_bola-test-step" } }, "verdict": { "description": "Verdict of this single test.", "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_bola-verdict" } ] } }, "required": [ "verdict", "steps" ] }, "vuln_scanner_bola-test-assertion": { "description": "Assertion that was made against the received response.", "type": "object", "properties": { "description": { "description": "Human-readable description of the assertion, explaining what was checked.", "type": "string" }, "kind": { "description": "Kind of assertion.", "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_bola-assertion-kind" } ] }, "observed": { "description": "Observed value on which the assertion was made.", "type": "integer", "nullable": true }, "outcome": { "description": "Outcome of the assertion.", "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_bola-outcome" } ] } }, "required": [ "description", "kind", "observed", "outcome" ] }, "vuln_scanner_bola-test-credential-set": { "description": "Credential set that was used.", "type": "object", "properties": { "id": { "description": "ID of the credential set.", "type": "string", "format": "uuid" }, "role": { "description": "Role of the credential set.", "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_bola-credential-role" } ] } }, "required": [ "id", "role" ] }, "vuln_scanner_bola-test-error": { "description": "Error that occurred during a test.", "type": "object", "properties": { "description": { "description": "Human-readable error description.", "type": "string" }, "error_code": { "description": "Numeric error code identifying the class of error, if available.", "type": "integer", "format": "uint32", "minimum": 0, "nullable": true } }, "required": [ "description" ] }, "vuln_scanner_bola-test-request": { "description": "HTTP request that was made.", "type": "object", "properties": { "body": { "description": "Request body, if any.", "type": "object", "nullable": true }, "credential_set": { "description": "Credential set that was used.", "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_bola-test-credential-set" } ] }, "header_names": { "description": "Names of headers that were sent.", "type": "array", "items": { "type": "string" } }, "method": { "description": "HTTP method.", "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_bola-method" } ] }, "url": { "description": "Exact and full URL (including host, query parameters) that was requested.", "type": "string", "format": "uri" }, "variable_captures": { "description": "Variable captures requested for this step.", "type": "array", "items": { "$ref": "#/components/schemas/vuln_scanner_bola-variable-capture" } } }, "required": [ "method", "url", "credential_set", "header_names", "variable_captures" ] }, "vuln_scanner_bola-test-response": { "description": "HTTP response that was received.", "type": "object", "properties": { "body": { "description": "HTTP response body.", "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_bola-body-response" } ] }, "header_names": { "description": "Names of headers that were received.", "type": "array", "items": { "type": "string" } }, "status": { "description": "HTTP status code.", "type": "integer", "maximum": 65535, "minimum": 0 }, "status_text": { "description": "HTTP status text, if available for the status code.", "type": "string", "nullable": true } }, "required": [ "status", "header_names", "body" ] }, "vuln_scanner_bola-test-step": { "description": "A single step in a test.", "type": "object", "properties": { "assertions": { "description": "Assertions that were made against the received response.", "type": "array", "items": { "$ref": "#/components/schemas/vuln_scanner_bola-test-assertion" } }, "errors": { "description": "Errors the step encountered that may explain absent or incomplete fields.", "type": "array", "items": { "$ref": "#/components/schemas/vuln_scanner_bola-test-error" } }, "request": { "description": "HTTP request that was made, if any.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_bola-test-request" } ], "nullable": true }, "response": { "description": "HTTP response that was received, if any.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_bola-test-response" } ], "nullable": true } }, "required": [ "assertions" ] }, "vuln_scanner_bola-variable-capture": { "description": "A variable to capture from the response body.", "type": "object", "properties": { "json_path": { "description": "JSONPath expression used for capture, e.g. `\"$.id\"`.", "type": "string" }, "name": { "description": "Variable name, e.g. `\"resource_id\"`.", "type": "string" } }, "required": [ "name", "json_path" ] }, "vuln_scanner_bola-verdict": { "description": "A verdict. `ok` means the scan passed, `warning` means the scan detected issues, `inconclusive` means errors prevented the scanner from reaching an accurate verdict.", "type": "string", "enum": [ "ok", "warning", "inconclusive" ] }, "vuln_scanner_create-bola-scan-request": { "type": "object", "properties": { "credential_sets": { "$ref": "#/components/schemas/vuln_scanner_bola-credential-sets" }, "open_api": { "description": "OpenAPI schema definition for the API under test. The scanner\nuses this to discover endpoints and construct requests.\n", "type": "string" }, "scan_type": { "type": "string", "enum": [ "bola" ] }, "target_environment_id": { "description": "The target environment to scan.", "type": "string", "format": "uuid" } }, "required": [ "target_environment_id", "scan_type", "open_api", "credential_sets" ] }, "vuln_scanner_create-credential-request": { "type": "object", "properties": { "location": { "$ref": "#/components/schemas/vuln_scanner_credential-location" }, "location_name": { "description": "Name of the header or cookie where the credential is attached.\n", "type": "string", "example": "Authorization" }, "name": { "description": "Human-readable name.", "type": "string", "example": "Admin API key" }, "value": { "description": "The credential value (e.g. API key, session token). Write-only.\nNever returned in responses.\n", "type": "string", "example": "Bearer EXAMPLE_TOKEN", "writeOnly": true, "x-sensitive": true } }, "required": [ "name", "location", "location_name", "value" ] }, "vuln_scanner_create-credential-set-request": { "type": "object", "properties": { "name": { "description": "Human-readable name.", "type": "string", "example": "Production API credentials" } }, "required": [ "name" ] }, "vuln_scanner_create-scan-request": { "description": "Create a new vulnerability scan. The `scan_type` discriminator\nselects the scan variant and its required context fields.\n", "discriminator": { "mapping": { "bola": "#/components/schemas/vuln_scanner_create-bola-scan-request" }, "propertyName": "scan_type" }, "oneOf": [ { "$ref": "#/components/schemas/vuln_scanner_create-bola-scan-request" } ] }, "vuln_scanner_create-target-environment-request": { "type": "object", "properties": { "description": { "description": "Optional description.", "type": "string", "example": "Main production environment", "nullable": true }, "name": { "description": "Human-readable name.", "type": "string", "example": "Production Zone" }, "target": { "$ref": "#/components/schemas/vuln_scanner_target-type" } }, "required": [ "name", "target" ] }, "vuln_scanner_credential": { "description": "A credential attached to API requests during scanning. The\ncredential `value` is write-only and never returned in responses.\n", "type": "object", "properties": { "credential_set_id": { "description": "Parent credential set identifier.", "type": "string", "format": "uuid", "x-auditable": true }, "id": { "description": "Credential identifier.", "type": "string", "format": "uuid", "x-auditable": true }, "location": { "$ref": "#/components/schemas/vuln_scanner_credential-location" }, "location_name": { "description": "Name of the header or cookie where the credential is attached.\n", "type": "string", "example": "Authorization", "x-auditable": true }, "name": { "description": "Human-readable name.", "type": "string", "example": "Admin API key", "x-auditable": true } }, "required": [ "id", "credential_set_id", "name", "location", "location_name" ] }, "vuln_scanner_credential-location": { "description": "Where the credential is attached in outgoing requests.", "type": "string", "enum": [ "header", "cookie" ], "x-auditable": true }, "vuln_scanner_credential-set": { "type": "object", "properties": { "id": { "description": "Credential set identifier.", "type": "string", "format": "uuid", "x-auditable": true }, "name": { "description": "Human-readable name.", "type": "string", "example": "Production API credentials", "x-auditable": true } }, "required": [ "id", "name" ] }, "vuln_scanner_delete-scan-response": { "description": "Successful scan deletion result.", "type": "object", "properties": { "id": { "description": "ID of the deleted scan.", "type": "string", "format": "uuid", "x-auditable": true } }, "required": [ "id" ] }, "vuln_scanner_empty-response": { "description": "Standard response envelope with a `null` result. Operations\nthat produce no result body return this response.\n", "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_api-response-common" }, { "properties": { "result": { "type": "object", "nullable": true }, "result_info": { "type": "object", "nullable": true } }, "type": "object" } ] }, "vuln_scanner_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "vuln_scanner_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "vuln_scanner_patch-credential-request": { "description": "Applies a partial update. Only the provided fields change; omitted fields remain unchanged.", "type": "object", "properties": { "location": { "$ref": "#/components/schemas/vuln_scanner_credential-location" }, "location_name": { "description": "Name of the header or cookie where the credential is attached.\n", "type": "string", "example": "Authorization" }, "name": { "description": "Human-readable name.", "type": "string", "example": "Admin API key" }, "value": { "description": "The credential value. Write-only. Never returned in responses.\n", "type": "string", "example": "Bearer EXAMPLE_TOKEN", "writeOnly": true, "x-sensitive": true } } }, "vuln_scanner_patch-credential-set-request": { "description": "Applies a partial update. Only the provided fields change; omitted fields remain unchanged.", "type": "object", "properties": { "name": { "description": "Human-readable name.", "type": "string", "example": "Production API credentials" } } }, "vuln_scanner_patch-target-environment-request": { "description": "Applies a partial update. Only the provided fields change; omitted fields remain unchanged.\n\nThe `description` field supports three states:\n- **omitted**: leave unchanged\n- **`null`**: clear the description\n- **`\"value\"`**: set to the given string\n", "type": "object", "properties": { "description": { "description": "Optional description. Omit to leave unchanged, set to `null`\nto clear, or provide a string to update.\n", "type": "string", "example": "Main production environment", "nullable": true }, "name": { "description": "Human-readable name.", "type": "string", "example": "Production Zone" }, "target": { "$ref": "#/components/schemas/vuln_scanner_target-type" } } }, "vuln_scanner_scan": { "type": "object", "properties": { "id": { "description": "Scan identifier.", "type": "string", "format": "uuid", "x-auditable": true }, "report": { "description": "Vulnerability report produced after the scan completes. The shape depends on the scan type. Present only for finished scans.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/vuln_scanner_bola-report" } ], "nullable": true }, "scan_type": { "description": "The type of vulnerability scan.", "type": "string", "enum": [ "bola" ], "x-auditable": true }, "status": { "description": "Current lifecycle status of the scan.", "type": "string", "enum": [ "created", "scheduled", "planning", "running", "finished", "failed" ], "x-auditable": true }, "target_environment_id": { "description": "The target environment this scan runs against.", "type": "string", "format": "uuid", "x-auditable": true } }, "required": [ "id", "target_environment_id", "scan_type", "status" ] }, "vuln_scanner_target-environment": { "type": "object", "properties": { "description": { "description": "Optional description providing additional context.", "type": "string", "example": "Main production environment", "nullable": true }, "id": { "description": "Target environment identifier.", "type": "string", "format": "uuid", "x-auditable": true }, "name": { "description": "Human-readable name.", "type": "string", "example": "Production Zone", "x-auditable": true }, "target": { "$ref": "#/components/schemas/vuln_scanner_target-type" } }, "required": [ "id", "name", "target" ] }, "vuln_scanner_target-type": { "description": "Identifies the Cloudflare asset to scan. Uses a `type` discriminator.\nCurrently the service supports only `zone` targets.\n", "discriminator": { "mapping": { "zone": "#/components/schemas/vuln_scanner_zone-target" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/vuln_scanner_zone-target" } ], "x-auditable": true }, "vuln_scanner_update-credential-request": { "description": "Full replacement. Provide all fields.", "type": "object", "properties": { "location": { "$ref": "#/components/schemas/vuln_scanner_credential-location" }, "location_name": { "description": "Name of the header or cookie where the credential is attached.\n", "type": "string", "example": "Authorization" }, "name": { "description": "Human-readable name.", "type": "string", "example": "Admin API key" }, "value": { "description": "The credential value. Write-only. Never returned in responses.\n", "type": "string", "example": "Bearer EXAMPLE_TOKEN", "writeOnly": true, "x-sensitive": true } }, "required": [ "name", "location", "location_name", "value" ] }, "vuln_scanner_update-credential-set-request": { "description": "Full replacement. Provide all fields.", "type": "object", "properties": { "name": { "description": "Human-readable name.", "type": "string", "example": "Production API credentials" } }, "required": [ "name" ] }, "vuln_scanner_update-target-environment-request": { "description": "Full replacement.", "type": "object", "properties": { "description": { "description": "Optional description.", "type": "string", "example": "Main production environment", "nullable": true }, "name": { "description": "Human-readable name.", "type": "string", "example": "Production Zone" }, "target": { "$ref": "#/components/schemas/vuln_scanner_target-type" } }, "required": [ "name", "target" ] }, "vuln_scanner_zone-target": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "zone" ] }, "zone_tag": { "description": "Cloudflare zone tag. The zone must belong to the account.\n", "type": "string", "example": "d8e8fca2dc0f896fd7cb4cb0031ba249", "maxLength": 32 } }, "required": [ "type", "zone_tag" ] }, "waf-managed-rules_allowed_modes": { "description": "Defines the available states for the rule group.", "type": "array", "items": { "$ref": "#/components/schemas/waf-managed-rules_mode" }, "example": [ "on", "off" ], "readOnly": true }, "waf-managed-rules_allowed_modes_allow_traditional": { "description": "Defines the available modes for the current WAF rule.", "type": "array", "items": { "$ref": "#/components/schemas/waf-managed-rules_mode_allow_traditional" }, "example": [ "on", "off" ], "readOnly": true }, "waf-managed-rules_allowed_modes_anomaly": { "description": "Defines the available modes for the current WAF rule. Applies to anomaly detection WAF rules.", "type": "array", "items": { "$ref": "#/components/schemas/waf-managed-rules_mode_anomaly" }, "example": [ "on", "off" ], "readOnly": true }, "waf-managed-rules_allowed_modes_deny_traditional": { "description": "Defines the list of possible actions of the WAF rule when it is triggered.", "type": "array", "items": { "$ref": "#/components/schemas/waf-managed-rules_mode_deny_traditional" }, "example": [ "default", "disable", "simulate", "block", "challenge" ], "readOnly": true }, "waf-managed-rules_anomaly_rule": { "description": "When triggered, anomaly detection WAF rules contribute to an overall threat score that will determine if a request is considered malicious. You can configure the total scoring threshold through the 'sensitivity' property of the WAF package.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_schemas-base" }, { "properties": { "allowed_modes": { "$ref": "#/components/schemas/waf-managed-rules_allowed_modes_anomaly" }, "mode": { "$ref": "#/components/schemas/waf-managed-rules_mode_anomaly" } }, "type": "object" } ], "required": [ "id", "description", "priority", "allowed_modes", "mode", "group", "package_id" ], "title": "Anomaly detection WAF rule" }, "waf-managed-rules_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_api-response-common" }, { "properties": { "result_info": { "$ref": "#/components/schemas/waf-managed-rules_result_info" } }, "type": "object" } ] }, "waf-managed-rules_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/waf-managed-rules_messages" }, "messages": { "$ref": "#/components/schemas/waf-managed-rules_messages" }, "success": { "description": "Defines whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "waf-managed-rules_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Defines whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "waf-managed-rules_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_api-response-common" }, { "properties": { "result": { "oneOf": [ { "nullable": true, "type": "object" }, { "nullable": true, "type": "string" } ] } }, "type": "object" } ] }, "waf-managed-rules_base": { "properties": { "description": { "$ref": "#/components/schemas/waf-managed-rules_schemas-description" }, "group": { "description": "Defines the rule group to which the current WAF rule belongs.", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/waf-managed-rules_components-schemas-identifier" }, "name": { "$ref": "#/components/schemas/waf-managed-rules_name" } }, "readOnly": true }, "id": { "$ref": "#/components/schemas/waf-managed-rules_rule_components-schemas-identifier" }, "package_id": { "$ref": "#/components/schemas/waf-managed-rules_identifier" }, "priority": { "$ref": "#/components/schemas/waf-managed-rules_priority" } } }, "waf-managed-rules_components-schemas-identifier": { "description": "Defines the unique identifier of the rule group.", "type": "string", "example": "de677e5818985db1285d0e80225f06e5", "maxLength": 32, "readOnly": true, "x-auditable": true }, "waf-managed-rules_default_mode": { "description": "Defines the default action/mode of a rule.", "example": "block", "enum": [ "disable", "simulate", "block", "challenge" ], "readOnly": true }, "waf-managed-rules_description": { "description": "Defines an informative summary of what the rule group does.", "type": "string", "example": "Group designed to protect against IP addresses that are a threat and typically used to launch DDoS attacks", "nullable": true, "readOnly": true, "x-auditable": true }, "waf-managed-rules_group": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/waf-managed-rules_description" }, "id": { "$ref": "#/components/schemas/waf-managed-rules_components-schemas-identifier" }, "modified_rules_count": { "$ref": "#/components/schemas/waf-managed-rules_modified_rules_count" }, "name": { "$ref": "#/components/schemas/waf-managed-rules_name" }, "package_id": { "$ref": "#/components/schemas/waf-managed-rules_identifier" }, "rules_count": { "$ref": "#/components/schemas/waf-managed-rules_rules_count" } } }, "waf-managed-rules_identifier": { "description": "Defines the unique identifier of a WAF package.", "type": "string", "example": "a25a9a7e9c00afc1fb2e0245519d725b", "maxLength": 32, "readOnly": true, "x-auditable": true }, "waf-managed-rules_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "waf-managed-rules_mode": { "description": "Defines the state of the rules contained in the rule group. When `on`, the rules in the group are configurable/usable.", "type": "string", "default": "on", "enum": [ "on", "off" ], "x-auditable": true }, "waf-managed-rules_mode_allow_traditional": { "description": "When set to `on`, the current rule will be used when evaluating the request. Applies to traditional (allow) WAF rules.", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true }, "waf-managed-rules_mode_anomaly": { "description": "Defines the mode anomaly. When set to `on`, the current WAF rule will be used when evaluating the request. Applies to anomaly detection WAF rules.", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true }, "waf-managed-rules_mode_deny_traditional": { "description": "Defines the action that the current WAF rule will perform when triggered. Applies to traditional (deny) WAF rules.", "type": "string", "example": "block", "enum": [ "default", "disable", "simulate", "block", "challenge" ], "x-auditable": true }, "waf-managed-rules_modified_rules_count": { "description": "Defines the number of rules within the group that have been modified from their default configuration.", "type": "number", "example": 2, "default": 0, "readOnly": true, "x-auditable": true }, "waf-managed-rules_name": { "description": "Defines the name of the rule group.", "type": "string", "example": "Project Honey Pot", "readOnly": true, "x-auditable": true }, "waf-managed-rules_priority": { "description": "Defines the order in which the individual WAF rule is executed within its rule group.", "type": "string", "readOnly": true, "x-auditable": true }, "waf-managed-rules_result_info": { "type": "object", "properties": { "count": { "description": "Defines the total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Defines the current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Defines the number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Defines the total results available without any search parameters.", "type": "number", "example": 2000 } } }, "waf-managed-rules_rule": { "oneOf": [ { "$ref": "#/components/schemas/waf-managed-rules_anomaly_rule" }, { "$ref": "#/components/schemas/waf-managed-rules_traditional_deny_rule" }, { "$ref": "#/components/schemas/waf-managed-rules_traditional_allow_rule" } ] }, "waf-managed-rules_rule_components-schemas-identifier": { "description": "Defines the unique identifier of the WAF rule.", "type": "string", "example": "f939de3be84e66e757adcdcb87908023", "maxLength": 32, "readOnly": true, "x-auditable": true }, "waf-managed-rules_rule_group_response_collection": { "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/waf-managed-rules_schemas-group" } } }, "type": "object" } ] }, "waf-managed-rules_rule_group_response_single": { "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_api-response-single" }, { "properties": { "result": { "type": "object" } }, "type": "object" } ] }, "waf-managed-rules_rule_response_collection": { "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/waf-managed-rules_rule" } } }, "type": "object" } ] }, "waf-managed-rules_rule_response_single": { "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_api-response-single" }, { "properties": { "result": { "type": "object" } }, "type": "object" } ] }, "waf-managed-rules_rules_count": { "description": "Defines the number of rules in the current rule group.", "type": "number", "example": 10, "default": 0, "readOnly": true, "x-auditable": true }, "waf-managed-rules_schemas-base": { "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_base" } ] }, "waf-managed-rules_schemas-description": { "description": "Defines the public description of the WAF rule.", "type": "string", "example": "SQL injection prevention for SELECT statements", "readOnly": true, "x-auditable": true }, "waf-managed-rules_schemas-group": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_group" }, { "properties": { "allowed_modes": { "$ref": "#/components/schemas/waf-managed-rules_allowed_modes" }, "mode": { "$ref": "#/components/schemas/waf-managed-rules_mode" } }, "type": "object" } ], "required": [ "id", "name", "description", "mode", "rules_count" ] }, "waf-managed-rules_schemas-identifier": { "description": "Defines an identifier of a schema.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "waf-managed-rules_traditional_allow_rule": { "description": "When triggered, traditional WAF rules cause the firewall to immediately act on the request based on the rule configuration. An 'allow' rule will immediately allow the request and no other rules will be processed.", "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_base" }, { "properties": { "allowed_modes": { "$ref": "#/components/schemas/waf-managed-rules_allowed_modes_allow_traditional" }, "mode": { "$ref": "#/components/schemas/waf-managed-rules_mode_allow_traditional" } }, "type": "object" } ], "required": [ "id", "description", "priority", "allowed_modes", "default_mode", "mode", "group", "package_id" ], "title": "Traditional (allow) WAF rule" }, "waf-managed-rules_traditional_deny_rule": { "description": "When triggered, traditional WAF rules cause the firewall to immediately act upon the request based on the configuration of the rule. A 'deny' rule will immediately respond to the request based on the configured rule action/mode (for example, 'block') and no other rules will be processed.", "allOf": [ { "$ref": "#/components/schemas/waf-managed-rules_base" }, { "properties": { "allowed_modes": { "$ref": "#/components/schemas/waf-managed-rules_allowed_modes_deny_traditional" }, "default_mode": { "$ref": "#/components/schemas/waf-managed-rules_default_mode" }, "mode": { "$ref": "#/components/schemas/waf-managed-rules_mode_deny_traditional" } }, "type": "object" } ], "required": [ "id", "description", "priority", "allowed_modes", "default_mode", "mode", "group", "package_id" ], "title": "Traditional (deny) WAF rule" }, "waf-product-api-bundle_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "type": "object" }, "nullable": true } }, "type": "object" } ] }, "waf-product-api-bundle_api-response-collection-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-2" }, { "properties": { "result": { "type": "array", "items": { "type": "object" }, "nullable": true } }, "type": "object" } ] }, "waf-product-api-bundle_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/waf-product-api-bundle_messages" }, "messages": { "$ref": "#/components/schemas/waf-product-api-bundle_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": { "type": "object" }, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Defines whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "waf-product-api-bundle_api-response-common-2": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/waf-product-api-bundle_messages" }, "messages": { "$ref": "#/components/schemas/waf-product-api-bundle_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": { "type": "object" }, "type": "array" }, { "nullable": true, "type": "string" } ] }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "waf-product-api-bundle_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 10100, "message": "Unknown error occured, please try again" } ], "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Defines whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "waf-product-api-bundle_api-response-common-failure-2": { "type": "object", "properties": { "errors": { "example": [ { "code": 10000, "message": "Authentication error" } ], "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "waf-product-api-bundle_api-response-common-failure-3": { "type": "object", "properties": { "errors": { "example": [ { "code": 13900, "message": "internal server error" } ], "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_messages" } ], "minItems": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Defines whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "waf-product-api-bundle_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common" }, { "properties": { "result": { "anyOf": [ { "nullable": true, "type": "object" }, { "nullable": true, "type": "string" } ] } }, "type": "object" } ] }, "waf-product-api-bundle_api-response-single-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-common-2" }, { "properties": { "result": { "anyOf": [ { "nullable": true, "type": "object" }, { "nullable": true, "type": "string" } ] } }, "type": "object" } ] }, "waf-product-api-bundle_custom-detection": { "description": "Defines a custom set of username/password expressions to match Leaked Credential Checks on.", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/waf-product-api-bundle_detection-id" }, "password": { "description": "Defines ehe ruleset expression to use in matching the password in a request.", "type": "string", "example": "lookup_json_string(http.request.body.raw, \"secret\")", "x-auditable": true }, "username": { "description": "Defines the ruleset expression to use in matching the username in a request.", "type": "string", "example": "lookup_json_string(http.request.body.raw, \"user\")", "x-auditable": true } } }, "waf-product-api-bundle_custom-scan": { "description": "Defines a Content Scanning custom expression.", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/waf-product-api-bundle_custom-scan-id" }, "payload": { "$ref": "#/components/schemas/waf-product-api-bundle_custom-scan-payload" } } }, "waf-product-api-bundle_custom-scan-id": { "description": "Defines the unique ID for this Content Scanning custom expression.", "example": "a350a054caa840c9becd89c3b4f0195b", "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } ] }, "waf-product-api-bundle_custom-scan-payload": { "description": "Defines the custom content extraction expression used to reach content objects in the request.", "type": "string", "example": "lookup_json_string(http.request.body.raw, \"file\")", "x-auditable": true }, "waf-product-api-bundle_custom-topic": { "type": "object", "properties": { "label": { "description": "Unique label identifier. Must contain only lowercase letters (a–z), digits (0–9), and hyphens.", "type": "string", "example": "credit-cards", "maxLength": 20, "minLength": 2, "pattern": "^[a-z0-9-]+$" }, "topic": { "description": "Description of the topic category. Must contain only printable ASCII characters.", "type": "string", "example": "credit card numbers", "maxLength": 50, "minLength": 2, "pattern": "^[ -~]+$" } }, "required": [ "label", "topic" ] }, "waf-product-api-bundle_custom-topics": { "type": "object", "properties": { "topics": { "description": "Custom topic categories for AI Security for Apps content detection.", "type": "array", "items": { "$ref": "#/components/schemas/waf-product-api-bundle_custom-topic" }, "maxItems": 20 } } }, "waf-product-api-bundle_detection-id": { "description": "Defines the unique ID for this custom detection.", "example": "18a14bafaa8eb1df04ce683ec18c765e", "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_identifier" } ], "x-auditable": true }, "waf-product-api-bundle_identifier": { "description": "Defines an identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "waf-product-api-bundle_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "waf-product-api-bundle_response-custom-detection": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/waf-product-api-bundle_custom-detection" } }, "type": "object" } ] }, "waf-product-api-bundle_response-custom-detection-collection": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/waf-product-api-bundle_custom-detection" } } }, "type": "object" } ] }, "waf-product-api-bundle_response-custom-scan-collection": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-collection-2" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/waf-product-api-bundle_custom-scan" } } }, "type": "object" } ] }, "waf-product-api-bundle_response-custom-topics": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/waf-product-api-bundle_custom-topics" } }, "type": "object" } ] }, "waf-product-api-bundle_response-settings": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/waf-product-api-bundle_settings" } }, "type": "object" } ] }, "waf-product-api-bundle_response-status": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/waf-product-api-bundle_status" } }, "type": "object" } ] }, "waf-product-api-bundle_response-status-2": { "allOf": [ { "$ref": "#/components/schemas/waf-product-api-bundle_api-response-single-2" }, { "properties": { "result": { "$ref": "#/components/schemas/waf-product-api-bundle_status-2" } }, "type": "object" } ] }, "waf-product-api-bundle_settings": { "description": "AI Security for Apps enablement status for a zone.", "type": "object", "properties": { "enabled": { "description": "Whether AI Security for Apps is enabled on the zone.", "type": "boolean", "example": true } } }, "waf-product-api-bundle_status": { "description": "Defines the overall status for Leaked Credential Checks.", "type": "object", "properties": { "enabled": { "description": "Determines whether or not Leaked Credential Checks are enabled.", "type": "boolean", "example": true, "x-auditable": true } } }, "waf-product-api-bundle_status-2": { "description": "Defines the status for Content Scanning.", "type": "object", "properties": { "modified": { "description": "Defines the last modification date (ISO 8601) of the Content Scanning status.", "type": "string", "example": "2024-12-02T09:57:23.150259Z", "x-auditable": true }, "value": { "description": "Defines the status of Content Scanning.", "type": "string", "example": "enabled", "x-auditable": true } } }, "waf-product-api-bundle_zone_id": { "description": "Defines the zone.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 }, "waitingroom_additional_routes": { "description": "Only available for the Waiting Room Advanced subscription. Additional hostname and path combinations to which this waiting room will be applied. There is an implied wildcard at the end of the path. The hostname and path combination must be unique to this and all other waiting rooms.", "type": "array", "items": { "properties": { "host": { "description": "The hostname to which this waiting room will be applied (no wildcards). The hostname must be the primary domain, subdomain, or custom hostname (if using SSL for SaaS) of this zone. Please do not include the scheme (http:// or https://).", "type": "string", "example": "shop2.example.com", "x-auditable": true }, "path": { "description": "Sets the path within the host to enable the waiting room on. The waiting room will be enabled for all subpaths as well. If there are two waiting rooms on the same subpath, the waiting room for the most specific path will be chosen. Wildcards and query parameters are not supported.", "type": "string", "example": "/shop2/checkout", "default": "/", "x-auditable": true } }, "type": "object" } }, "waitingroom_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_api-response-common-2" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "waitingroom_api-response-common": { "type": "object", "required": [ "success", "errors", "messages", "result" ] }, "waitingroom_api-response-common-2": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/waitingroom_messages" }, "messages": { "$ref": "#/components/schemas/waitingroom_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "waitingroom_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/waitingroom_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/waitingroom_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "waitingroom_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_api-response-common" }, { "properties": { "result": { "type": "object", "oneOf": [ { "type": "object" }, { "type": "string" } ] } }, "type": "object" } ] }, "waitingroom_cookie_attributes": { "description": "Configures cookie attributes for the waiting room cookie. This encrypted cookie stores a user's status in the waiting room, such as queue position.", "type": "object", "properties": { "samesite": { "description": "Configures the SameSite attribute on the waiting room cookie. Value `auto` will be translated to `lax` or `none` depending if **Always Use HTTPS** is enabled. Note that when using value `none`, the secure attribute cannot be set to `never`.", "type": "string", "example": "auto", "default": "auto", "enum": [ "auto", "lax", "none", "strict" ], "x-auditable": true }, "secure": { "description": "Configures the Secure attribute on the waiting room cookie. Value `always` indicates that the Secure attribute will be set in the Set-Cookie header, `never` indicates that the Secure attribute will not be set, and `auto` will set the Secure attribute depending if **Always Use HTTPS** is enabled.", "type": "string", "example": "auto", "default": "auto", "enum": [ "auto", "always", "never" ], "x-auditable": true } } }, "waitingroom_cookie_suffix": { "description": "Appends a '_' + a custom suffix to the end of Cloudflare Waiting Room's cookie name(__cf_waitingroom). If `cookie_suffix` is \"abcd\", the cookie name will be `__cf_waitingroom_abcd`. This field is required if using `additional_routes`.", "type": "string", "example": "abcd", "default": "", "x-auditable": true }, "waitingroom_create_rule": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/waitingroom_rule_action" }, "description": { "$ref": "#/components/schemas/waitingroom_rule_description" }, "enabled": { "$ref": "#/components/schemas/waitingroom_rule_enabled" }, "expression": { "$ref": "#/components/schemas/waitingroom_rule_expression" } }, "required": [ "action", "expression" ] }, "waitingroom_custom_page_html": { "description": "Only available for the Waiting Room Advanced subscription. This is a template html file that will be rendered at the edge. If no custom_page_html is provided, the default waiting room will be used. The template is based on mustache ( https://mustache.github.io/ ). There are several variables that are evaluated by the Cloudflare edge:\n1. {{`waitTimeKnown`}} Acts like a boolean value that indicates the behavior to take when wait time is not available, for instance when queue_all is **true**.\n2. {{`waitTimeFormatted`}} Estimated wait time for the user. For example, five minutes. Alternatively, you can use:\n3. {{`waitTime`}} Number of minutes of estimated wait for a user.\n4. {{`waitTimeHours`}} Number of hours of estimated wait for a user (`Math.floor(waitTime/60)`).\n5. {{`waitTimeHourMinutes`}} Number of minutes above the `waitTimeHours` value (`waitTime%60`).\n6. {{`queueIsFull`}} Changes to **true** when no more people can be added to the queue.\n\nTo view the full list of variables, look at the `cfWaitingRoom` object described under the `json_response_enabled` property in other Waiting Room API calls.", "type": "string", "example": "{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Queue all enabled {{/waitTimeKnown}}", "default": "", "x-auditable": true }, "waitingroom_default_template_language": { "description": "The language of the default page template. If no default_template_language is provided, then `en-US` (English) will be used.", "type": "string", "example": "es-ES", "default": "en-US", "enum": [ "en-US", "es-ES", "de-DE", "fr-FR", "it-IT", "ja-JP", "ko-KR", "pt-BR", "zh-CN", "zh-TW", "nl-NL", "pl-PL", "id-ID", "tr-TR", "ar-EG", "ru-RU", "fa-IR", "bg-BG", "hr-HR", "cs-CZ", "da-DK", "fi-FI", "lt-LT", "ms-MY", "nb-NO", "ro-RO", "el-GR", "he-IL", "hi-IN", "hu-HU", "sr-BA", "sk-SK", "sl-SI", "sv-SE", "tl-PH", "th-TH", "uk-UA", "vi-VN" ], "x-auditable": true }, "waitingroom_description": { "description": "A note that you can use to add more details about the waiting room.", "type": "string", "example": "Production - DO NOT MODIFY", "default": "", "x-auditable": true }, "waitingroom_disable_session_renewal": { "description": "Only available for the Waiting Room Advanced subscription. Disables automatic renewal of session cookies. If `true`, an accepted user will have session_duration minutes to browse the site. After that, they will have to go through the waiting room again. If `false`, a user's session cookie will be automatically renewed on every request.", "type": "boolean", "example": false, "default": false, "x-auditable": true }, "waitingroom_enabled_origin_commands": { "description": "A list of enabled origin commands.", "type": "array", "items": { "enum": [ "revoke" ], "type": "string", "uniqueItems": true, "x-auditable": true }, "default": [] }, "waitingroom_estimated_queued_users": { "type": "integer", "x-auditable": true }, "waitingroom_estimated_total_active_users": { "type": "integer", "x-auditable": true }, "waitingroom_event_custom_page_html": { "description": "If set, the event will override the waiting room's `custom_page_html` property while it is active. If null, the event will inherit it.", "type": "string", "example": "{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Event is prequeueing / Queue all enabled {{/waitTimeKnown}}", "nullable": true, "x-auditable": true }, "waitingroom_event_description": { "description": "A note that you can use to add more details about the event.", "type": "string", "example": "Production event - DO NOT MODIFY", "default": "", "x-auditable": true }, "waitingroom_event_details_custom_page_html": { "type": "string", "example": "{{#waitTimeKnown}} {{waitTime}} mins {{/waitTimeKnown}} {{^waitTimeKnown}} Event is prequeueing / Queue all enabled {{/waitTimeKnown}}", "x-auditable": true }, "waitingroom_event_details_disable_session_renewal": { "type": "boolean", "example": false, "x-auditable": true }, "waitingroom_event_details_new_users_per_minute": { "type": "integer", "x-auditable": true }, "waitingroom_event_details_queueing_method": { "type": "string", "example": "random", "x-auditable": true }, "waitingroom_event_details_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/waitingroom_event_details_result" } }, "type": "object" } ] }, "waitingroom_event_details_result": { "type": "object", "properties": { "created_on": { "$ref": "#/components/schemas/waitingroom_timestamp" }, "custom_page_html": { "$ref": "#/components/schemas/waitingroom_event_details_custom_page_html" }, "description": { "$ref": "#/components/schemas/waitingroom_event_description" }, "disable_session_renewal": { "$ref": "#/components/schemas/waitingroom_event_details_disable_session_renewal" }, "event_end_time": { "$ref": "#/components/schemas/waitingroom_event_end_time" }, "event_start_time": { "$ref": "#/components/schemas/waitingroom_event_start_time" }, "id": { "$ref": "#/components/schemas/waitingroom_event_id" }, "modified_on": { "$ref": "#/components/schemas/waitingroom_timestamp" }, "name": { "$ref": "#/components/schemas/waitingroom_event_name" }, "new_users_per_minute": { "$ref": "#/components/schemas/waitingroom_event_details_new_users_per_minute" }, "prequeue_start_time": { "$ref": "#/components/schemas/waitingroom_event_prequeue_start_time" }, "queueing_method": { "$ref": "#/components/schemas/waitingroom_event_details_queueing_method" }, "session_duration": { "$ref": "#/components/schemas/waitingroom_event_details_session_duration" }, "shuffle_at_event_start": { "$ref": "#/components/schemas/waitingroom_event_shuffle_at_event_start" }, "suspended": { "$ref": "#/components/schemas/waitingroom_event_suspended" }, "total_active_users": { "$ref": "#/components/schemas/waitingroom_event_details_total_active_users" } } }, "waitingroom_event_details_session_duration": { "type": "integer", "x-auditable": true }, "waitingroom_event_details_total_active_users": { "type": "integer", "x-auditable": true }, "waitingroom_event_disable_session_renewal": { "description": "If set, the event will override the waiting room's `disable_session_renewal` property while it is active. If null, the event will inherit it.", "type": "boolean", "nullable": true, "x-auditable": true }, "waitingroom_event_end_time": { "description": "An ISO 8601 timestamp that marks the end of the event.", "type": "string", "example": "2021-09-28T17:00:00Z", "x-auditable": true }, "waitingroom_event_id": { "type": "string", "example": "25756b2dfe6e378a06b033b670413757", "x-auditable": true }, "waitingroom_event_id_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/waitingroom_event_id" } } } }, "type": "object" } ] }, "waitingroom_event_name": { "description": "A unique name to identify the event. Only alphanumeric characters, hyphens and underscores are allowed.", "type": "string", "example": "production_webinar_event", "x-auditable": true }, "waitingroom_event_new_users_per_minute": { "description": "If set, the event will override the waiting room's `new_users_per_minute` property while it is active. If null, the event will inherit it. This can only be set if the event's `total_active_users` property is also set.", "type": "integer", "maximum": 2147483647, "minimum": 200, "nullable": true, "x-auditable": true }, "waitingroom_event_prequeue_start_time": { "description": "An ISO 8601 timestamp that marks when to begin queueing all users before the event starts. The prequeue must start at least five minutes before `event_start_time`.", "type": "string", "example": "2021-09-28T15:00:00Z", "nullable": true, "x-auditable": true }, "waitingroom_event_queueing_method": { "description": "If set, the event will override the waiting room's `queueing_method` property while it is active. If null, the event will inherit it.", "type": "string", "example": "random", "nullable": true, "x-auditable": true }, "waitingroom_event_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/waitingroom_event_result" } }, "type": "object" } ] }, "waitingroom_event_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/waitingroom_event_result" } } }, "type": "object" } ] }, "waitingroom_event_result": { "type": "object", "properties": { "created_on": { "$ref": "#/components/schemas/waitingroom_timestamp" }, "custom_page_html": { "$ref": "#/components/schemas/waitingroom_event_custom_page_html" }, "description": { "$ref": "#/components/schemas/waitingroom_event_description" }, "disable_session_renewal": { "$ref": "#/components/schemas/waitingroom_event_disable_session_renewal" }, "event_end_time": { "$ref": "#/components/schemas/waitingroom_event_end_time" }, "event_start_time": { "$ref": "#/components/schemas/waitingroom_event_start_time" }, "id": { "$ref": "#/components/schemas/waitingroom_event_id" }, "modified_on": { "$ref": "#/components/schemas/waitingroom_timestamp" }, "name": { "$ref": "#/components/schemas/waitingroom_event_name" }, "new_users_per_minute": { "$ref": "#/components/schemas/waitingroom_event_new_users_per_minute" }, "prequeue_start_time": { "$ref": "#/components/schemas/waitingroom_event_prequeue_start_time" }, "queueing_method": { "$ref": "#/components/schemas/waitingroom_event_queueing_method" }, "session_duration": { "$ref": "#/components/schemas/waitingroom_event_session_duration" }, "shuffle_at_event_start": { "$ref": "#/components/schemas/waitingroom_event_shuffle_at_event_start" }, "suspended": { "$ref": "#/components/schemas/waitingroom_event_suspended" }, "total_active_users": { "$ref": "#/components/schemas/waitingroom_event_total_active_users" }, "turnstile_action": { "$ref": "#/components/schemas/waitingroom_event_turnstile_action" }, "turnstile_mode": { "$ref": "#/components/schemas/waitingroom_event_turnstile_mode" } } }, "waitingroom_event_session_duration": { "description": "If set, the event will override the waiting room's `session_duration` property while it is active. If null, the event will inherit it.", "type": "integer", "maximum": 30, "minimum": 1, "nullable": true, "x-auditable": true }, "waitingroom_event_shuffle_at_event_start": { "description": "If enabled, users in the prequeue will be shuffled randomly at the `event_start_time`. Requires that `prequeue_start_time` is not null. This is useful for situations when many users will join the event prequeue at the same time and you want to shuffle them to ensure fairness. Naturally, it makes the most sense to enable this feature when the `queueing_method` during the event respects ordering such as **fifo**, or else the shuffling may be unnecessary.", "type": "boolean", "default": false, "x-auditable": true }, "waitingroom_event_start_time": { "description": "An ISO 8601 timestamp that marks the start of the event. At this time, queued users will be processed with the event's configuration. The start time must be at least one minute before `event_end_time`.", "type": "string", "example": "2021-09-28T15:30:00Z", "x-auditable": true }, "waitingroom_event_suspended": { "description": "Suspends or allows an event. If set to `true`, the event is ignored and traffic will be handled based on the waiting room configuration.", "type": "boolean", "default": false, "x-auditable": true }, "waitingroom_event_total_active_users": { "description": "If set, the event will override the waiting room's `total_active_users` property while it is active. If null, the event will inherit it. This can only be set if the event's `new_users_per_minute` property is also set.", "type": "integer", "maximum": 2147483647, "minimum": 200, "nullable": true, "x-auditable": true }, "waitingroom_event_turnstile_action": { "description": "If set, the event will override the waiting room's `turnstile_action` property while it is active. If null, the event will inherit it.", "type": "string", "enum": [ "log", "infinite_queue" ], "nullable": true, "x-auditable": true }, "waitingroom_event_turnstile_mode": { "description": "If set, the event will override the waiting room's `turnstile_mode` property while it is active. If null, the event will inherit it.", "type": "string", "enum": [ "off", "invisible", "visible_non_interactive", "visible_managed" ], "nullable": true, "x-auditable": true }, "waitingroom_host": { "description": "The host name to which the waiting room will be applied (no wildcards). Please do not include the scheme (http:// or https://). The host and path combination must be unique.", "type": "string", "example": "shop.example.com", "x-auditable": true }, "waitingroom_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "waitingroom_json_response_enabled": { "description": "Only available for the Waiting Room Advanced subscription. If `true`, requests to the waiting room with the header `Accept: application/json` will receive a JSON response object with information on the user's status in the waiting room as opposed to the configured static HTML page. This JSON response object has one property `cfWaitingRoom` which is an object containing the following fields:\n1. `inWaitingRoom`: Boolean indicating if the user is in the waiting room (always **true**).\n2. `waitTimeKnown`: Boolean indicating if the current estimated wait times are accurate. If **false**, they are not available.\n3. `waitTime`: Valid only when `waitTimeKnown` is **true**. Integer indicating the current estimated time in minutes the user will wait in the waiting room. When `queueingMethod` is **random**, this is set to `waitTime50Percentile`.\n4. `waitTime25Percentile`: Valid only when `queueingMethod` is **random** and `waitTimeKnown` is **true**. Integer indicating the current estimated maximum wait time for the 25% of users that gain entry the fastest (25th percentile).\n5. `waitTime50Percentile`: Valid only when `queueingMethod` is **random** and `waitTimeKnown` is **true**. Integer indicating the current estimated maximum wait time for the 50% of users that gain entry the fastest (50th percentile). In other words, half of the queued users are expected to let into the origin website before `waitTime50Percentile` and half are expected to be let in after it.\n6. `waitTime75Percentile`: Valid only when `queueingMethod` is **random** and `waitTimeKnown` is **true**. Integer indicating the current estimated maximum wait time for the 75% of users that gain entry the fastest (75th percentile).\n7. `waitTimeFormatted`: String displaying the `waitTime` formatted in English for users. If `waitTimeKnown` is **false**, `waitTimeFormatted` will display **unavailable**.\n8. `queueIsFull`: Boolean indicating if the waiting room's queue is currently full and not accepting new users at the moment.\n9. `queueAll`: Boolean indicating if all users will be queued in the waiting room and no one will be let into the origin website.\n10. `lastUpdated`: String displaying the timestamp as an ISO 8601 string of the user's last attempt to leave the waiting room and be let into the origin website. The user is able to make another attempt after `refreshIntervalSeconds` past this time. If the user makes a request too soon, it will be ignored and `lastUpdated` will not change.\n11. `refreshIntervalSeconds`: Integer indicating the number of seconds after `lastUpdated` until the user is able to make another attempt to leave the waiting room and be let into the origin website. When the `queueingMethod` is `reject`, there is no specified refresh time —\\_it will always be **zero**.\n12. `queueingMethod`: The queueing method currently used by the waiting room. It is either **fifo**, **random**, **passthrough**, or **reject**.\n13. `isFIFOQueue`: Boolean indicating if the waiting room uses a FIFO (First-In-First-Out) queue.\n14. `isRandomQueue`: Boolean indicating if the waiting room uses a Random queue where users gain access randomly.\n15. `isPassthroughQueue`: Boolean indicating if the waiting room uses a passthrough queue. Keep in mind that when passthrough is enabled, this JSON response will only exist when `queueAll` is **true** or `isEventPrequeueing` is **true** because in all other cases requests will go directly to the origin.\n16. `isRejectQueue`: Boolean indicating if the waiting room uses a reject queue.\n17. `isEventActive`: Boolean indicating if an event is currently occurring. Events are able to change a waiting room's behavior during a specified period of time. For additional information, look at the event properties `prequeue_start_time`, `event_start_time`, and `event_end_time` in the documentation for creating waiting room events. Events are considered active between these start and end times, as well as during the prequeueing period if it exists.\n18. `isEventPrequeueing`: Valid only when `isEventActive` is **true**. Boolean indicating if an event is currently prequeueing users before it starts.\n19. `timeUntilEventStart`: Valid only when `isEventPrequeueing` is **true**. Integer indicating the number of minutes until the event starts.\n20. `timeUntilEventStartFormatted`: String displaying the `timeUntilEventStart` formatted in English for users. If `isEventPrequeueing` is **false**, `timeUntilEventStartFormatted` will display **unavailable**.\n21. `timeUntilEventEnd`: Valid only when `isEventActive` is **true**. Integer indicating the number of minutes until the event ends.\n22. `timeUntilEventEndFormatted`: String displaying the `timeUntilEventEnd` formatted in English for users. If `isEventActive` is **false**, `timeUntilEventEndFormatted` will display **unavailable**.\n23. `shuffleAtEventStart`: Valid only when `isEventActive` is **true**. Boolean indicating if the users in the prequeue are shuffled randomly when the event starts.\n24. `turnstile`: Empty when turnstile isn't enabled. String displaying an html tag to display the Turnstile widget. Please add the `{{{turnstile}}}` tag to the `custom_html` template to ensure the Turnstile widget appears.\n25. `infiniteQueue`: Boolean indicating whether the response is for a user in the infinite queue.\n\nAn example cURL to a waiting room could be:\n\n\tcurl -X GET \"https://example.com/waitingroom\" \\\n\t\t-H \"Accept: application/json\"\n\nIf `json_response_enabled` is **true** and the request hits the waiting room, an example JSON response when `queueingMethod` is **fifo** and no event is active could be:\n\n\t{\n\t\t\"cfWaitingRoom\": {\n\t\t\t\"inWaitingRoom\": true,\n\t\t\t\"waitTimeKnown\": true,\n\t\t\t\"waitTime\": 10,\n\t\t\t\"waitTime25Percentile\": 0,\n\t\t\t\"waitTime50Percentile\": 0,\n\t\t\t\"waitTime75Percentile\": 0,\n\t\t\t\"waitTimeFormatted\": \"10 minutes\",\n\t\t\t\"queueIsFull\": false,\n\t\t\t\"queueAll\": false,\n\t\t\t\"lastUpdated\": \"2020-08-03T23:46:00.000Z\",\n\t\t\t\"refreshIntervalSeconds\": 20,\n\t\t\t\"queueingMethod\": \"fifo\",\n\t\t\t\"isFIFOQueue\": true,\n\t\t\t\"isRandomQueue\": false,\n\t\t\t\"isPassthroughQueue\": false,\n\t\t\t\"isRejectQueue\": false,\n\t\t\t\"isEventActive\": false,\n\t\t\t\"isEventPrequeueing\": false,\n\t\t\t\"timeUntilEventStart\": 0,\n\t\t\t\"timeUntilEventStartFormatted\": \"unavailable\",\n\t\t\t\"timeUntilEventEnd\": 0,\n\t\t\t\"timeUntilEventEndFormatted\": \"unavailable\",\n\t\t\t\"shuffleAtEventStart\": false\n\t\t}\n\t}\n\nIf `json_response_enabled` is **true** and the request hits the waiting room, an example JSON response when `queueingMethod` is **random** and an event is active could be:\n\n\t{\n\t\t\"cfWaitingRoom\": {\n\t\t\t\"inWaitingRoom\": true,\n\t\t\t\"waitTimeKnown\": true,\n\t\t\t\"waitTime\": 10,\n\t\t\t\"waitTime25Percentile\": 5,\n\t\t\t\"waitTime50Percentile\": 10,\n\t\t\t\"waitTime75Percentile\": 15,\n\t\t\t\"waitTimeFormatted\": \"5 minutes to 15 minutes\",\n\t\t\t\"queueIsFull\": false,\n\t\t\t\"queueAll\": false,\n\t\t\t\"lastUpdated\": \"2020-08-03T23:46:00.000Z\",\n\t\t\t\"refreshIntervalSeconds\": 20,\n\t\t\t\"queueingMethod\": \"random\",\n\t\t\t\"isFIFOQueue\": false,\n\t\t\t\"isRandomQueue\": true,\n\t\t\t\"isPassthroughQueue\": false,\n\t\t\t\"isRejectQueue\": false,\n\t\t\t\"isEventActive\": true,\n\t\t\t\"isEventPrequeueing\": false,\n\t\t\t\"timeUntilEventStart\": 0,\n\t\t\t\"timeUntilEventStartFormatted\": \"unavailable\",\n\t\t\t\"timeUntilEventEnd\": 15,\n\t\t\t\"timeUntilEventEndFormatted\": \"15 minutes\",\n\t\t\t\"shuffleAtEventStart\": true\n\t\t}\n\t}", "type": "boolean", "example": false, "default": false, "x-auditable": true }, "waitingroom_max_estimated_time_minutes": { "type": "integer", "x-auditable": true }, "waitingroom_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "waitingroom_name": { "description": "A unique name to identify the waiting room. Only alphanumeric characters, hyphens and underscores are allowed.", "type": "string", "example": "production_webinar", "x-auditable": true }, "waitingroom_new_users_per_minute": { "description": "Sets the number of new users that will be let into the route every minute. This value is used as baseline for the number of users that are let in per minute. So it is possible that there is a little more or little less traffic coming to the route based on the traffic patterns at that time around the world.", "type": "integer", "maximum": 2147483647, "minimum": 200, "x-auditable": true }, "waitingroom_next_event_prequeue_start_time": { "description": "An ISO 8601 timestamp that marks when the next event will begin queueing.", "type": "string", "example": "2021-09-28T15:00:00Z", "nullable": true, "x-auditable": true }, "waitingroom_next_event_start_time": { "description": "An ISO 8601 timestamp that marks when the next event will start.", "type": "string", "example": "2021-09-28T15:00:00Z", "nullable": true, "x-auditable": true }, "waitingroom_patch_rule": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/waitingroom_rule_action" }, "description": { "$ref": "#/components/schemas/waitingroom_rule_description" }, "enabled": { "$ref": "#/components/schemas/waitingroom_rule_enabled" }, "expression": { "$ref": "#/components/schemas/waitingroom_rule_expression" }, "position": { "$ref": "#/components/schemas/waitingroom_rule_position" } }, "required": [ "action", "expression" ] }, "waitingroom_path": { "description": "Sets the path within the host to enable the waiting room on. The waiting room will be enabled for all subpaths as well. If there are two waiting rooms on the same subpath, the waiting room for the most specific path will be chosen. Wildcards and query parameters are not supported.", "type": "string", "example": "/shop/checkout", "default": "/", "x-auditable": true }, "waitingroom_preview_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "preview_url": { "$ref": "#/components/schemas/waitingroom_preview_url" } } } }, "type": "object" } ] }, "waitingroom_preview_url": { "description": "URL where the custom waiting room page can temporarily be previewed.", "type": "string", "example": "http://waitingrooms.dev/preview/35af8c12-6d68-4608-babb-b53435a5ddfb", "x-auditable": true }, "waitingroom_query_event": { "type": "object", "properties": { "custom_page_html": { "$ref": "#/components/schemas/waitingroom_event_custom_page_html" }, "description": { "$ref": "#/components/schemas/waitingroom_event_description" }, "disable_session_renewal": { "$ref": "#/components/schemas/waitingroom_event_disable_session_renewal" }, "event_end_time": { "$ref": "#/components/schemas/waitingroom_event_end_time" }, "event_start_time": { "$ref": "#/components/schemas/waitingroom_event_start_time" }, "name": { "$ref": "#/components/schemas/waitingroom_event_name" }, "new_users_per_minute": { "$ref": "#/components/schemas/waitingroom_event_new_users_per_minute" }, "prequeue_start_time": { "$ref": "#/components/schemas/waitingroom_event_prequeue_start_time" }, "queueing_method": { "$ref": "#/components/schemas/waitingroom_event_queueing_method" }, "session_duration": { "$ref": "#/components/schemas/waitingroom_event_session_duration" }, "shuffle_at_event_start": { "$ref": "#/components/schemas/waitingroom_event_shuffle_at_event_start" }, "suspended": { "$ref": "#/components/schemas/waitingroom_event_suspended" }, "total_active_users": { "$ref": "#/components/schemas/waitingroom_event_total_active_users" }, "turnstile_action": { "$ref": "#/components/schemas/waitingroom_event_turnstile_action" }, "turnstile_mode": { "$ref": "#/components/schemas/waitingroom_event_turnstile_mode" } }, "required": [ "name", "event_start_time", "event_end_time" ] }, "waitingroom_query_preview": { "type": "object", "properties": { "custom_html": { "$ref": "#/components/schemas/waitingroom_custom_page_html" } }, "required": [ "custom_html" ] }, "waitingroom_query_waitingroom": { "type": "object", "properties": { "additional_routes": { "$ref": "#/components/schemas/waitingroom_additional_routes" }, "cookie_attributes": { "$ref": "#/components/schemas/waitingroom_cookie_attributes" }, "cookie_suffix": { "$ref": "#/components/schemas/waitingroom_cookie_suffix" }, "custom_page_html": { "$ref": "#/components/schemas/waitingroom_custom_page_html" }, "default_template_language": { "$ref": "#/components/schemas/waitingroom_default_template_language" }, "description": { "$ref": "#/components/schemas/waitingroom_description" }, "disable_session_renewal": { "$ref": "#/components/schemas/waitingroom_disable_session_renewal" }, "enabled_origin_commands": { "$ref": "#/components/schemas/waitingroom_enabled_origin_commands" }, "host": { "$ref": "#/components/schemas/waitingroom_host" }, "json_response_enabled": { "$ref": "#/components/schemas/waitingroom_json_response_enabled" }, "name": { "$ref": "#/components/schemas/waitingroom_name" }, "new_users_per_minute": { "$ref": "#/components/schemas/waitingroom_new_users_per_minute" }, "path": { "$ref": "#/components/schemas/waitingroom_path" }, "queue_all": { "$ref": "#/components/schemas/waitingroom_queue_all" }, "queueing_method": { "$ref": "#/components/schemas/waitingroom_queueing_method" }, "queueing_status_code": { "$ref": "#/components/schemas/waitingroom_queueing_status_code" }, "session_duration": { "$ref": "#/components/schemas/waitingroom_session_duration" }, "suspended": { "$ref": "#/components/schemas/waitingroom_suspended" }, "total_active_users": { "$ref": "#/components/schemas/waitingroom_total_active_users" }, "turnstile_action": { "$ref": "#/components/schemas/waitingroom_turnstile_action" }, "turnstile_mode": { "$ref": "#/components/schemas/waitingroom_turnstile_mode" } }, "required": [ "name", "host", "new_users_per_minute", "total_active_users" ] }, "waitingroom_queue_all": { "description": "If queue_all is `true`, all the traffic that is coming to a route will be sent to the waiting room. No new traffic can get to the route once this field is set and estimated time will become unavailable.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "waitingroom_queueing_method": { "description": "Sets the queueing method used by the waiting room. Changing this parameter from the **default** queueing method is only available for the Waiting Room Advanced subscription. Regardless of the queueing method, if `queue_all` is enabled or an event is prequeueing, users in the waiting room will not be accepted to the origin. These users will always see a waiting room page that refreshes automatically. The valid queueing methods are:\n1. `fifo` **(default)**: First-In-First-Out queue where customers gain access in the order they arrived.\n2. `random`: Random queue where customers gain access randomly, regardless of arrival time.\n3. `passthrough`: Users will pass directly through the waiting room and into the origin website. As a result, any configured limits will not be respected while this is enabled. This method can be used as an alternative to disabling a waiting room (with `suspended`) so that analytics are still reported. This can be used if you wish to allow all traffic normally, but want to restrict traffic during a waiting room event, or vice versa.\n4. `reject`: Users will be immediately rejected from the waiting room. As a result, no users will reach the origin website while this is enabled. This can be used if you wish to reject all traffic while performing maintenance, block traffic during a specified period of time (an event), or block traffic while events are not occurring. Consider a waiting room used for vaccine distribution that only allows traffic during sign-up events, and otherwise blocks all traffic. For this case, the waiting room uses `reject`, and its events override this with `fifo`, `random`, or `passthrough`. When this queueing method is enabled and neither `queueAll` is enabled nor an event is prequeueing, the waiting room page **will not refresh automatically**.", "type": "string", "example": "fifo", "default": "fifo", "enum": [ "fifo", "random", "passthrough", "reject" ], "x-auditable": true }, "waitingroom_queueing_status_code": { "description": "HTTP status code returned to a user while in the queue.", "type": "integer", "example": 202, "default": 200, "enum": [ 200, 202, 429 ], "x-auditable": true }, "waitingroom_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/waitingroom_waitingroom" } } }, "type": "object" } ] }, "waitingroom_rule_action": { "description": "The action to take when the expression matches.", "type": "string", "example": "bypass_waiting_room", "enum": [ "bypass_waiting_room" ], "x-auditable": true }, "waitingroom_rule_description": { "description": "The description of the rule.", "type": "string", "example": "allow all traffic from 10.20.30.40", "default": "", "x-auditable": true }, "waitingroom_rule_enabled": { "description": "When set to true, the rule is enabled.", "type": "boolean", "example": true, "default": true, "x-auditable": true }, "waitingroom_rule_expression": { "description": "Criteria defining when there is a match for the current rule.", "type": "string", "example": "ip.src in {10.20.30.40}", "x-auditable": true }, "waitingroom_rule_id": { "description": "The ID of the rule.", "type": "string", "example": "25756b2dfe6e378a06b033b670413757", "x-auditable": true }, "waitingroom_rule_position": { "description": "Reorder the position of a rule", "type": "object", "oneOf": [ { "properties": { "index": { "description": "Places the rule in the exact position specified by the integer number . Position numbers start with 1. Existing rules in the ruleset from the specified position number onward are shifted one position (no rule is overwritten).", "type": "integer", "x-auditable": true } }, "type": "object" }, { "properties": { "before": { "description": "Places the rule before rule . Use this argument with an empty rule ID value (\"\") to set the rule as the first rule in the ruleset.", "type": "string", "example": "", "x-auditable": true } }, "type": "object" }, { "properties": { "after": { "description": "Places the rule after rule . Use this argument with an empty rule ID value (\"\") to set the rule as the last rule in the ruleset.", "type": "string", "example": "", "x-auditable": true } }, "type": "object" } ] }, "waitingroom_rule_result": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/waitingroom_rule_action" }, "description": { "$ref": "#/components/schemas/waitingroom_rule_description" }, "enabled": { "$ref": "#/components/schemas/waitingroom_rule_enabled" }, "expression": { "$ref": "#/components/schemas/waitingroom_rule_expression" }, "id": { "$ref": "#/components/schemas/waitingroom_rule_id" }, "last_updated": { "$ref": "#/components/schemas/waitingroom_timestamp" }, "version": { "$ref": "#/components/schemas/waitingroom_rule_version" } } }, "waitingroom_rule_version": { "description": "The version of the rule.", "type": "string", "example": "1", "x-auditable": true }, "waitingroom_rules_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/waitingroom_rule_result" } } }, "type": "object" } ] }, "waitingroom_search_engine_crawler_bypass": { "description": "Whether to allow verified search engine crawlers to bypass all waiting rooms on this zone.\nVerified search engine crawlers will not be tracked or counted by the waiting room system,\nand will not appear in waiting room analytics.\n", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "waitingroom_session_duration": { "description": "Lifetime of a cookie (in minutes) set by Cloudflare for users who get access to the route. If a user is not seen by Cloudflare again in that time period, they will be treated as a new user that visits the route.", "type": "integer", "default": 5, "maximum": 30, "minimum": 1, "x-auditable": true }, "waitingroom_single_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/waitingroom_waitingroom" } }, "type": "object" } ] }, "waitingroom_status": { "type": "string", "example": "queueing", "enum": [ "event_prequeueing", "not_queueing", "queueing", "suspended" ], "x-auditable": true }, "waitingroom_status_event_id": { "type": "string", "example": "25756b2dfe6e378a06b033b670413757", "x-auditable": true }, "waitingroom_status_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "estimated_queued_users": { "$ref": "#/components/schemas/waitingroom_estimated_queued_users" }, "estimated_total_active_users": { "$ref": "#/components/schemas/waitingroom_estimated_total_active_users" }, "event_id": { "$ref": "#/components/schemas/waitingroom_status_event_id" }, "max_estimated_time_minutes": { "$ref": "#/components/schemas/waitingroom_max_estimated_time_minutes" }, "status": { "$ref": "#/components/schemas/waitingroom_status" } } } }, "type": "object" } ] }, "waitingroom_suspended": { "description": "Suspends or allows traffic going to the waiting room. If set to `true`, the traffic will not go to the waiting room.", "type": "boolean", "default": false, "x-auditable": true }, "waitingroom_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true, "x-auditable": true }, "waitingroom_total_active_users": { "description": "Sets the total number of active user sessions on the route at a point in time. A route is a combination of host and path on which a waiting room is available. This value is used as a baseline for the total number of active user sessions on the route. It is possible to have a situation where there are more or less active users sessions on the route based on the traffic patterns at that time around the world.", "type": "integer", "maximum": 2147483647, "minimum": 200, "x-auditable": true }, "waitingroom_turnstile_action": { "description": "Which action to take when a bot is detected using Turnstile. `log` will\nhave no impact on queueing behavior, simply keeping track of how many\nbots are detected in Waiting Room Analytics. `infinite_queue` will send\nbots to a false queueing state, where they will never reach your\norigin. `infinite_queue` requires Advanced Waiting Room.\n", "type": "string", "default": "log", "enum": [ "log", "infinite_queue" ], "x-auditable": true }, "waitingroom_turnstile_mode": { "description": "Which Turnstile widget type to use for detecting bot traffic. See\n[the Turnstile documentation](https://developers.cloudflare.com/turnstile/concepts/widget/#widget-types)\nfor the definitions of these widget types. Set to `off` to disable the\nTurnstile integration entirely. Setting this to anything other than\n`off` or `invisible` requires Advanced Waiting Room.\n", "type": "string", "default": "invisible", "enum": [ "off", "invisible", "visible_non_interactive", "visible_managed" ], "x-auditable": true }, "waitingroom_update_rules": { "type": "array", "items": { "$ref": "#/components/schemas/waitingroom_create_rule" } }, "waitingroom_waiting_room_id": { "type": "string", "example": "699d98642c564d2e855e9661899b7252", "x-auditable": true }, "waitingroom_waiting_room_id_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" } } } }, "type": "object" } ] }, "waitingroom_waitingroom": { "type": "object", "properties": { "additional_routes": { "$ref": "#/components/schemas/waitingroom_additional_routes" }, "cookie_attributes": { "$ref": "#/components/schemas/waitingroom_cookie_attributes" }, "cookie_suffix": { "$ref": "#/components/schemas/waitingroom_cookie_suffix" }, "created_on": { "$ref": "#/components/schemas/waitingroom_timestamp" }, "custom_page_html": { "$ref": "#/components/schemas/waitingroom_custom_page_html" }, "default_template_language": { "$ref": "#/components/schemas/waitingroom_default_template_language" }, "description": { "$ref": "#/components/schemas/waitingroom_description" }, "disable_session_renewal": { "$ref": "#/components/schemas/waitingroom_disable_session_renewal" }, "enabled_origin_commands": { "$ref": "#/components/schemas/waitingroom_enabled_origin_commands" }, "host": { "$ref": "#/components/schemas/waitingroom_host" }, "id": { "$ref": "#/components/schemas/waitingroom_waiting_room_id" }, "json_response_enabled": { "$ref": "#/components/schemas/waitingroom_json_response_enabled" }, "modified_on": { "$ref": "#/components/schemas/waitingroom_timestamp" }, "name": { "$ref": "#/components/schemas/waitingroom_name" }, "new_users_per_minute": { "$ref": "#/components/schemas/waitingroom_new_users_per_minute" }, "next_event_prequeue_start_time": { "$ref": "#/components/schemas/waitingroom_next_event_prequeue_start_time" }, "next_event_start_time": { "$ref": "#/components/schemas/waitingroom_next_event_start_time" }, "path": { "$ref": "#/components/schemas/waitingroom_path" }, "queue_all": { "$ref": "#/components/schemas/waitingroom_queue_all" }, "queueing_method": { "$ref": "#/components/schemas/waitingroom_queueing_method" }, "queueing_status_code": { "$ref": "#/components/schemas/waitingroom_queueing_status_code" }, "session_duration": { "$ref": "#/components/schemas/waitingroom_session_duration" }, "suspended": { "$ref": "#/components/schemas/waitingroom_suspended" }, "total_active_users": { "$ref": "#/components/schemas/waitingroom_total_active_users" }, "turnstile_action": { "$ref": "#/components/schemas/waitingroom_turnstile_action" }, "turnstile_mode": { "$ref": "#/components/schemas/waitingroom_turnstile_mode" } } }, "waitingroom_zone_settings": { "type": "object", "properties": { "search_engine_crawler_bypass": { "$ref": "#/components/schemas/waitingroom_search_engine_crawler_bypass" } } }, "waitingroom_zone_settings_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/waitingroom_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "search_engine_crawler_bypass": { "$ref": "#/components/schemas/waitingroom_search_engine_crawler_bypass" } }, "required": [ "search_engine_crawler_bypass" ] } }, "required": [ "result" ], "type": "object" } ] }, "web3_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/web3_api-response-common" }, { "properties": { "result": { "type": "array", "items": {}, "nullable": true }, "result_info": { "$ref": "#/components/schemas/web3_result_info" } } } ] }, "web3_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/web3_messages" }, "messages": { "$ref": "#/components/schemas/web3_messages" }, "result": { "description": "Provides the API response.", "type": "object", "anyOf": [ { "type": "object" }, { "items": {}, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Specifies whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "web3_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/web3_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/web3_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Specifies whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "web3_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/web3_api-response-common" }, { "properties": { "result_info": { "description": "Provides the API response.", "type": "object", "anyOf": [ { "nullable": true, "type": "object" }, { "nullable": true, "type": "string" } ] } } } ] }, "web3_api-response-single-id": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/web3_api-response-common" }, { "properties": { "result": { "type": "object", "nullable": true, "properties": { "id": { "$ref": "#/components/schemas/web3_identifier" } }, "required": [ "id" ] } } } ] }, "web3_collection_response": { "allOf": [ { "$ref": "#/components/schemas/web3_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/web3_web3-hostname" } } } } ] }, "web3_content_list_action": { "description": "Behavior of the content list.", "type": "string", "example": "block", "enum": [ "block" ] }, "web3_content_list_details": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/web3_content_list_action" } } }, "web3_content_list_details_response": { "allOf": [ { "$ref": "#/components/schemas/web3_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/web3_content_list_details" } } } ] }, "web3_content_list_entries": { "description": "Provides content list entries.", "type": "array", "items": { "$ref": "#/components/schemas/web3_content_list_entry" } }, "web3_content_list_entry": { "description": "Specify a content list entry to block.", "type": "object", "properties": { "content": { "$ref": "#/components/schemas/web3_content_list_entry_content" }, "created_on": { "$ref": "#/components/schemas/web3_timestamp" }, "description": { "$ref": "#/components/schemas/web3_content_list_entry_description" }, "id": { "$ref": "#/components/schemas/web3_identifier" }, "modified_on": { "$ref": "#/components/schemas/web3_timestamp" }, "type": { "$ref": "#/components/schemas/web3_content_list_entry_type" } } }, "web3_content_list_entry_collection_response": { "allOf": [ { "$ref": "#/components/schemas/web3_api-response-collection" }, { "properties": { "result": { "type": "object", "properties": { "entries": { "$ref": "#/components/schemas/web3_content_list_entries" } } } } } ] }, "web3_content_list_entry_content": { "description": "Specify the CID or content path of content to block.", "type": "string", "example": "QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB", "maxLength": 500 }, "web3_content_list_entry_create_request": { "type": "object", "properties": { "content": { "$ref": "#/components/schemas/web3_content_list_entry_content" }, "description": { "$ref": "#/components/schemas/web3_content_list_entry_description" }, "type": { "$ref": "#/components/schemas/web3_content_list_entry_type" } }, "required": [ "type", "content" ] }, "web3_content_list_entry_description": { "description": "Specify an optional description of the content list entry.", "type": "string", "example": "this is my content list entry", "maxLength": 500 }, "web3_content_list_entry_single_response": { "allOf": [ { "$ref": "#/components/schemas/web3_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/web3_content_list_entry" } } } ] }, "web3_content_list_entry_type": { "description": "Specify the type of content list entry to block.", "type": "string", "example": "cid", "enum": [ "cid", "content_path" ] }, "web3_content_list_update_request": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/web3_content_list_action" }, "entries": { "$ref": "#/components/schemas/web3_content_list_entries" } }, "required": [ "action", "entries" ] }, "web3_create_request": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/web3_description" }, "dnslink": { "$ref": "#/components/schemas/web3_dnslink" }, "name": { "$ref": "#/components/schemas/web3_name" }, "target": { "$ref": "#/components/schemas/web3_target" } }, "required": [ "name", "target" ] }, "web3_description": { "description": "Specify an optional description of the hostname.", "type": "string", "example": "This is my IPFS gateway.", "maxLength": 500 }, "web3_dnslink": { "description": "Specify the DNSLink value used if the target is ipfs.", "type": "string", "example": "/ipns/onboarding.ipfs.cloudflare.com" }, "web3_identifier": { "description": "Specify the identifier of the hostname.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "web3_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "web3_modify_request": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/web3_description" }, "dnslink": { "$ref": "#/components/schemas/web3_dnslink" } } }, "web3_name": { "description": "Specify the hostname that points to the target gateway via CNAME.", "type": "string", "example": "gateway.example.com", "maxLength": 255 }, "web3_result_info": { "type": "object", "properties": { "count": { "description": "Specifies the total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Specifies the current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Specifies the number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Specifies the total results available without any search parameters.", "type": "number", "example": 2000 } } }, "web3_single_response": { "allOf": [ { "$ref": "#/components/schemas/web3_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/web3_web3-hostname" } } } ] }, "web3_status": { "description": "Specifies the status of the hostname's activation.", "type": "string", "example": "active", "enum": [ "active", "pending", "deleting", "error" ], "readOnly": true }, "web3_target": { "description": "Specify the target gateway of the hostname.", "type": "string", "example": "ipfs", "enum": [ "ethereum", "ipfs", "ipfs_universal_path" ] }, "web3_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true }, "web3_web3-hostname": { "type": "object", "properties": { "created_on": { "$ref": "#/components/schemas/web3_timestamp" }, "description": { "$ref": "#/components/schemas/web3_description" }, "dnslink": { "$ref": "#/components/schemas/web3_dnslink" }, "id": { "$ref": "#/components/schemas/web3_identifier" }, "modified_on": { "$ref": "#/components/schemas/web3_timestamp" }, "name": { "$ref": "#/components/schemas/web3_name" }, "status": { "$ref": "#/components/schemas/web3_status" }, "target": { "$ref": "#/components/schemas/web3_target" } } }, "workers-kv_any": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "integer" }, { "type": "boolean" }, { "additionalProperties": true, "nullable": true, "type": "object" }, { "items": { "$ref": "#/components/schemas/workers-kv_any" }, "type": "array" } ], "x-stainless-override-schema": { "type": "unknown" } }, "workers-kv_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/workers-kv_api-response-common" }, { "properties": { "result_info": { "$ref": "#/components/schemas/workers-kv_result_info" } }, "type": "object" } ] }, "workers-kv_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/workers-kv_messages" }, "messages": { "$ref": "#/components/schemas/workers-kv_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "workers-kv_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/workers-kv_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/workers-kv_messages" } ] }, "result": { "type": "object", "nullable": true, "x-stainless-empty-object": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "workers-kv_api-response-common-no-result": { "allOf": [ { "$ref": "#/components/schemas/workers-kv_api-response-common" }, { "properties": { "result": { "type": "object", "nullable": true, "x-stainless-empty-object": true } }, "type": "object" } ] }, "workers-kv_bulk-get-result": { "type": "object", "properties": { "values": { "description": "Requested keys are paired with their values in an object.", "type": "object", "example": { "key1": "value1", "key2": "value2" }, "additionalProperties": { "description": "The value associated with the key.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "additionalProperties": true, "type": "object" } ] } } } }, "workers-kv_bulk-get-result-with-metadata": { "type": "object", "properties": { "values": { "description": "Requested keys are paired with their values and metadata in an object.", "type": "object", "example": { "key1": { "expiration": 1577836800, "metadata": { "someMetadataKey": "someMetadataValue" }, "value": "value1" }, "key2": { "metadata": { "anotherKey": "anotherValue" }, "value": "value2" } }, "additionalProperties": { "nullable": true, "properties": { "expiration": { "$ref": "#/components/schemas/workers-kv_expiration" }, "metadata": { "allOf": [ { "$ref": "#/components/schemas/workers-kv_any" }, { "description": "The metadata associated with the key." } ] }, "value": { "allOf": [ { "$ref": "#/components/schemas/workers-kv_any" }, { "description": "The value associated with the key." } ] } }, "required": [ "value", "metadata" ], "type": "object" } } } }, "workers-kv_bulk-result": { "type": "object", "properties": { "successful_key_count": { "description": "Number of keys successfully updated.", "type": "number", "example": 100 }, "unsuccessful_keys": { "description": "Name of the keys that failed to be fully updated. They should be retried.", "type": "array", "items": { "type": "string" } } } }, "workers-kv_bulk_delete": { "type": "array", "items": { "$ref": "#/components/schemas/workers-kv_key_name_bulk" }, "maxItems": 10000 }, "workers-kv_bulk_write": { "type": "array", "items": { "properties": { "base64": { "description": "Indicates whether or not the server should base64 decode the value before storing it. Useful for writing values that wouldn't otherwise be valid JSON strings, such as images.", "type": "boolean", "default": false }, "expiration": { "$ref": "#/components/schemas/workers-kv_expiration" }, "expiration_ttl": { "$ref": "#/components/schemas/workers-kv_expiration_ttl" }, "key": { "$ref": "#/components/schemas/workers-kv_key_name_bulk" }, "metadata": { "$ref": "#/components/schemas/workers-kv_list_metadata" }, "value": { "description": "A UTF-8 encoded string to be stored, up to 25 MiB in length.", "type": "string", "example": "Some string", "maxLength": 26214400 } }, "required": [ "key", "value" ], "type": "object" }, "maxItems": 10000 }, "workers-kv_create_namespace_body": { "type": "object", "properties": { "jurisdiction": { "$ref": "#/components/schemas/workers-kv_jurisdiction" }, "title": { "$ref": "#/components/schemas/workers-kv_namespace_title" } }, "required": [ "title" ] }, "workers-kv_create_rename_namespace_body": { "type": "object", "properties": { "title": { "$ref": "#/components/schemas/workers-kv_namespace_title" } }, "required": [ "title" ] }, "workers-kv_cursor": { "description": "Opaque token indicating the position from which to continue when requesting the next set of records if the amount of list results was limited by the limit parameter. A valid value for the cursor can be obtained from the cursors object in the result_info structure.", "type": "string", "example": "6Ck1la0VxJ0djhidm1MdX2FyDGxLKVeeHZZmORS_8XeSuhz9SjIJRaSa2lnsF01tQOHrfTGAP3R5X1Kv5iVUuMbNKhWNAXHOl6ePB0TUL8nw", "x-stainless-pagination-property": { "purpose": "next_cursor_field" } }, "workers-kv_cursor_result_info": { "type": "object", "properties": { "count": { "description": "Total results returned based on your list parameters.", "type": "number", "example": 1 }, "cursor": { "$ref": "#/components/schemas/workers-kv_cursor" } } }, "workers-kv_expiration": { "description": "Expires the key at a certain time, measured in number of seconds since the UNIX epoch.", "type": "number", "example": 1578435000 }, "workers-kv_expiration_ttl": { "description": "Expires the key after a number of seconds. Must be at least 60.", "type": "number", "example": 300, "minimum": 60 }, "workers-kv_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true, "x-auditable": true }, "workers-kv_jurisdiction": { "description": "Specify the jurisdiction to restrict the KV namespace to durably store data within. Can only be set at namespace creation time.", "type": "string", "example": "eu", "enum": [ "eu", "fedramp", "us" ], "x-auditable": true }, "workers-kv_key": { "description": "A name for a value. A value stored under a given key may be retrieved via the same key.", "type": "object", "properties": { "expiration": { "description": "The time, measured in number of seconds since the UNIX epoch, at which the key will expire. This property is omitted for keys that will not expire.", "type": "number", "example": 1577836800 }, "metadata": { "$ref": "#/components/schemas/workers-kv_list_metadata" }, "name": { "$ref": "#/components/schemas/workers-kv_key_name" } }, "required": [ "name" ] }, "workers-kv_key_name": { "description": "A key's name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid. Use percent-encoding to define key names as part of a URL.", "type": "string", "example": "My-Key", "maxLength": 512 }, "workers-kv_key_name_bulk": { "description": "A key's name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid.", "type": "string", "example": "My-Key", "maxLength": 512 }, "workers-kv_list_metadata": { "allOf": [ { "$ref": "#/components/schemas/workers-kv_any" }, { "description": "Arbitrary JSON that is associated with a key.", "example": { "someMetadataKey": "someMetadataValue" } } ] }, "workers-kv_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "example": [], "uniqueItems": true }, "workers-kv_metadata": { "allOf": [ { "$ref": "#/components/schemas/workers-kv_any" }, { "description": "Associates arbitrary JSON data with a key/value pair.", "example": { "someMetadataKey": "someMetadataValue" } } ] }, "workers-kv_namespace": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/workers-kv_namespace_identifier" }, "jurisdiction": { "$ref": "#/components/schemas/workers-kv_jurisdiction" }, "supports_url_encoding": { "description": "True if keys written on the URL will be URL-decoded before storing. For example, if set to \"true\", a key written on the URL as \"%3F\" will be stored as \"?\".", "type": "boolean", "example": true, "readOnly": true, "x-auditable": true }, "title": { "$ref": "#/components/schemas/workers-kv_namespace_title" } }, "required": [ "id", "title" ] }, "workers-kv_namespace_identifier": { "description": "Namespace identifier tag.", "type": "string", "example": "0f2ac74b498b48028cb68387c421e279", "maxLength": 32, "readOnly": true, "x-auditable": true }, "workers-kv_namespace_title": { "description": "A human-readable string name for a Namespace.", "type": "string", "example": "My Own Namespace", "maxLength": 512, "x-auditable": true }, "workers-kv_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 } } }, "workers-kv_value": { "description": "A byte sequence to be stored, up to 25 MiB in length.", "example": "Some Value", "anyOf": [ { "type": "string" }, { "format": "binary", "type": "string" } ] }, "workers-observability_distribution_result": { "description": "Bucketed 2D histogram of a numeric field over time. Present when chartType is 'distribution'.", "type": "object", "properties": { "bins": { "description": "Time-bucket labels (ISO-8601 strings), one per matrix column.", "type": "array", "items": { "type": "string" } }, "bucketBoundaries": { "description": "Raw bucket edges in the value's native unit, length buckets.length + 1. Used for the colour scale and percentile mapping.", "type": "array", "items": { "type": "number" } }, "bucketMode": { "description": "Bucketing scheme used to derive the boundaries. 'log' produces geometric edges; 'linear' produces fixed-width edges.", "type": "string", "enum": [ "log", "linear" ] }, "buckets": { "description": "Value-range labels, one per matrix row (e.g. '50–100ms').", "type": "array", "items": { "type": "string" } }, "matrix": { "description": "Sampling-corrected counts. matrix[bucketIdx][binIdx] is the estimated number of events in value-bucket 'bucketIdx' during time-bin 'binIdx'.", "type": "array", "items": { "items": { "type": "number" }, "type": "array" } } }, "required": [ "bins", "buckets", "matrix", "bucketBoundaries", "bucketMode" ] }, "workers-observability_filter_leaf": { "description": "A filter condition applied to query results. Use the keys and values endpoints to discover available fields and their values before constructing filters.", "type": "object", "properties": { "key": { "description": "Filter field name. Use verified keys from previous query results or the keys endpoint. Common keys include $metadata.service, $metadata.origin, $metadata.trigger, $metadata.message, and $metadata.error.", "type": "string" }, "kind": { "description": "Discriminator for leaf filter nodes. Always 'filter' when present; may be omitted.", "type": "string", "enum": [ "filter" ] }, "operation": { "description": "Comparison operator. String operators: includes, not_includes, starts_with, ends_with, regex. Existence: exists, is_null. Set membership: in, not_in (comma-separated values). Numeric: eq, neq, gt, gte, lt, lte.", "type": "string", "enum": [ "includes", "not_includes", "starts_with", "ends_with", "regex", "exists", "is_null", "in", "not_in", "eq", "neq", "gt", "gte", "lt", "lte", "=", "!=", ">", ">=", "<", "<=", "INCLUDES", "DOES_NOT_INCLUDE", "MATCH_REGEX", "EXISTS", "DOES_NOT_EXIST", "IN", "NOT_IN", "STARTS_WITH", "ENDS_WITH" ] }, "type": { "description": "Data type of the filter field. Must match the actual type of the key being filtered.", "type": "string", "enum": [ "string", "number", "boolean" ] }, "value": { "description": "Comparison value. Must match actual values in your data — verify with the values endpoint. Ensure the value type (string/number/boolean) matches the field type. String comparisons are case-sensitive. Regex uses RE2 syntax (no lookaheads/lookbehinds).", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "key", "operation", "type" ] }, "workers-observability_filter_node": { "description": "Supports nested groups via kind: 'group'.", "type": "object", "anyOf": [ { "properties": { "filterCombination": { "type": "string", "enum": [ "and", "or", "AND", "OR" ] }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/workers-observability_filter_node" }, "minItems": 1 }, "kind": { "type": "string", "enum": [ "group" ] } }, "required": [ "kind", "filterCombination", "filters" ], "type": "object" }, { "$ref": "#/components/schemas/workers-observability_filter_leaf" } ] }, "workers-observability_performance_information": { "description": "Query performance statistics from the database. Includes execution time, rows scanned, and bytes read. Does not include network latency.", "type": "object", "properties": { "abr_level": { "description": "The level of Adaptive Bit Rate (ABR) sampling used for the query. If empty the ABR level is 1", "type": "number" }, "bytes_read": { "description": "Number of uncompressed bytes read from the table.", "type": "number" }, "elapsed": { "description": "Time in seconds for the query to run.", "type": "number" }, "rows_read": { "description": "Number of rows scanned from the table.", "type": "number" } }, "required": [ "elapsed", "rows_read", "bytes_read" ] }, "workers-observability_query": { "type": "object", "properties": { "adhoc": { "description": "If the query wasn't explcitly saved", "type": "boolean" }, "created": { "type": "string", "format": "date-time" }, "createdBy": { "type": "string" }, "description": { "type": "string", "example": "Query description", "maxLength": 1000, "nullable": true }, "id": { "type": "string" }, "name": { "description": "Query name", "type": "string", "maxLength": 250, "minLength": 1 }, "parameters": { "properties": { "calculations": { "description": "Create Calculations to compute as part of the query.", "type": "array", "items": { "discriminator": { "propertyName": "operator" }, "oneOf": [ { "properties": { "alias": { "type": "string" }, "key": { "type": "string" }, "keyType": { "type": "string", "enum": [ "string", "number", "boolean" ] }, "operator": { "type": "string", "enum": [ "count", "COUNT" ] } }, "required": [ "operator" ], "type": "object" }, { "properties": { "alias": { "type": "string" }, "key": { "type": "string", "pattern": "\\S" }, "keyType": { "type": "string", "enum": [ "string", "number", "boolean" ] }, "operator": { "type": "string", "enum": [ "uniq", "max", "min", "sum", "avg", "median", "p001", "p01", "p05", "p10", "p25", "p75", "p90", "p95", "p99", "p999", "stddev", "variance", "COUNT_DISTINCT", "MAX", "MIN", "SUM", "AVG", "MEDIAN", "P001", "P01", "P05", "P10", "P25", "P75", "P90", "P95", "P99", "P999", "STDDEV", "VARIANCE" ] } }, "required": [ "key", "operator" ], "type": "object" } ] } }, "datasets": { "description": "Set the Datasets to query. Leave it empty to query all the datasets.", "type": "array", "items": { "type": "string" }, "example": [] }, "filterCombination": { "description": "Set a Flag to describe how to combine the filters on the query.", "type": "string", "enum": [ "and", "or", "AND", "OR" ] }, "filters": { "description": "Configure the Filters to apply to the query. Supports nested groups via kind: 'group'.", "type": "array", "items": { "$ref": "#/components/schemas/workers-observability_filter_node" } }, "groupBys": { "description": "Define how to group the results of the query.", "type": "array", "items": { "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean" ] }, "value": { "type": "string" } }, "required": [ "type", "value" ], "type": "object" } }, "havings": { "description": "Configure the Having clauses that filter on calculations in the query result.", "type": "array", "items": { "properties": { "key": { "type": "string" }, "operation": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte" ] }, "value": { "type": "number" } }, "required": [ "key", "operation", "value" ], "type": "object" } }, "limit": { "description": "Set a limit on the number of results / records returned by the query", "type": "integer", "maximum": 100, "minimum": 0 }, "needle": { "description": "Define an expression to search using full-text search.", "type": "object", "properties": { "isRegex": { "type": "boolean" }, "matchCase": { "type": "boolean" }, "value": { "allOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "maxLength": 1000, "type": "string" } ] } }, "required": [ "value" ] }, "orderBy": { "description": "Configure the order of the results returned by the query.", "type": "object", "properties": { "order": { "description": "Set the order of the results", "type": "string", "enum": [ "asc", "desc" ] }, "value": { "description": "Configure which Calculation to order the results by.", "type": "string" } }, "required": [ "value" ] } }, "type": "object" }, "updated": { "type": "string", "format": "date-time" }, "updatedBy": { "type": "string" } }, "required": [ "id", "name", "description", "adhoc", "parameters", "created", "createdBy", "updated", "updatedBy" ] }, "workers-observability_query_results": { "description": "Complete results of a query run. The populated fields depend on the requested view type (events, calculations, invocations, traces, or agents).", "type": "object", "properties": { "agents": { "description": "Agent run summaries. Present when the query view is 'agents'. Each entry represents one trace containing at least one agent invocation.", "type": "array", "items": { "properties": { "agentId": { "description": "ID from the earliest agent invocation that provides one.", "type": "string" }, "agentName": { "description": "Name from the earliest agent invocation that provides one.", "type": "string" }, "conversationId": { "description": "Conversation ID from the earliest invocation that provides one.", "type": "string" }, "errors": { "description": "Distinct errors reported by spans in the run.", "type": "array", "items": { "type": "string" } }, "id": { "description": "Stable pagination cursor for this agent run.", "type": "string" }, "inputTokens": { "description": "Input tokens summed across chat spans in the run's trace; informational, not billing data.", "type": "number" }, "models": { "description": "Distinct models reported by chat spans across the run's trace.", "type": "array", "items": { "type": "string" } }, "outputTokens": { "description": "Output tokens summed across chat spans in the run's trace; informational, not billing data.", "type": "number" }, "providers": { "description": "Distinct GenAI providers reported by chat spans in the run.", "type": "array", "items": { "type": "string" } }, "services": { "description": "Worker services represented in the run's trace.", "type": "array", "items": { "type": "string" } }, "spans": { "description": "Number of spans in the run's trace.", "type": "number" }, "status": { "description": "Observed run status.", "type": "string", "enum": [ "completed", "error" ] }, "traceDurationMs": { "description": "Total trace duration in milliseconds.", "type": "number" }, "traceEndMs": { "description": "End of the run's trace as a Unix epoch in milliseconds.", "type": "number" }, "traceId": { "description": "Trace identifier for this agent run.", "type": "string" }, "traceStartMs": { "description": "Start of the run's trace as a Unix epoch in milliseconds.", "type": "number" } }, "required": [ "id", "traceId", "traceStartMs", "traceEndMs", "traceDurationMs", "spans", "services", "errors", "status", "models", "providers" ], "type": "object" } }, "calculations": { "description": "Aggregated calculation results. Present when the query view is 'calculations'. Contains computed metrics (count, avg, p99, etc.) with optional group-by breakdowns and time-series data.", "type": "array", "items": { "properties": { "aggregates": { "type": "array", "items": { "properties": { "count": { "type": "number" }, "groups": { "type": "array", "items": { "properties": { "key": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "key", "value" ], "type": "object" } }, "interval": { "type": "number" }, "sampleInterval": { "type": "number" }, "value": { "type": "number" } }, "required": [ "value", "count", "interval", "sampleInterval" ], "type": "object" } }, "alias": { "type": "string" }, "calculation": { "type": "string" }, "series": { "type": "array", "items": { "properties": { "data": { "type": "array", "items": { "properties": { "count": { "type": "number" }, "firstSeen": { "type": "string" }, "groups": { "type": "array", "items": { "properties": { "key": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "key", "value" ], "type": "object" } }, "interval": { "type": "number" }, "lastSeen": { "type": "string" }, "sampleInterval": { "type": "number" }, "value": { "type": "number" } }, "required": [ "value", "count", "interval", "sampleInterval" ], "type": "object" } }, "time": { "type": "string" } }, "required": [ "time", "data" ], "type": "object" } } }, "required": [ "calculation", "aggregates", "series" ], "type": "object" } }, "compare": { "description": "Comparison calculation results from the previous time period. Present when the compare option is enabled. Same structure as calculations.", "type": "array", "items": { "properties": { "aggregates": { "type": "array", "items": { "properties": { "count": { "type": "number" }, "groups": { "type": "array", "items": { "properties": { "key": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "key", "value" ], "type": "object" } }, "interval": { "type": "number" }, "sampleInterval": { "type": "number" }, "value": { "type": "number" } }, "required": [ "value", "count", "interval", "sampleInterval" ], "type": "object" } }, "alias": { "type": "string" }, "calculation": { "type": "string" }, "series": { "type": "array", "items": { "properties": { "data": { "type": "array", "items": { "properties": { "count": { "type": "number" }, "firstSeen": { "type": "string" }, "groups": { "type": "array", "items": { "properties": { "key": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "key", "value" ], "type": "object" } }, "interval": { "type": "number" }, "lastSeen": { "type": "string" }, "sampleInterval": { "type": "number" }, "value": { "type": "number" } }, "required": [ "value", "count", "interval", "sampleInterval" ], "type": "object" } }, "time": { "type": "string" } }, "required": [ "time", "data" ], "type": "object" } } }, "required": [ "calculation", "aggregates", "series" ], "type": "object" } }, "distribution": { "$ref": "#/components/schemas/workers-observability_distribution_result" }, "events": { "description": "Individual event results. Present when the query view is 'events'. Contains the matching log lines and their metadata.", "type": "object", "properties": { "count": { "description": "Total number of events matching the query (may exceed the number returned due to limits).", "type": "number" }, "events": { "description": "List of individual telemetry events matching the query.", "type": "array", "items": { "$ref": "#/components/schemas/workers-observability_telemetry_event" } }, "fields": { "description": "List of fields discovered in the matched events. Useful for building dynamic UIs.", "type": "array", "items": { "properties": { "key": { "description": "Field name present in the matched events.", "type": "string" }, "type": { "description": "Data type of the field (string, number, or boolean).", "type": "string" } }, "required": [ "key", "type" ], "type": "object" } }, "series": { "description": "Time-series data for the matched events, bucketed by the query granularity.", "type": "array", "items": { "properties": { "data": { "type": "array", "items": { "properties": { "aggregates": { "type": "object", "properties": { "_count": { "type": "integer", "deprecated": true, "exclusiveMinimum": true, "minimum": 0 }, "_firstSeen": { "type": "string", "deprecated": true }, "_interval": { "type": "number", "deprecated": true, "exclusiveMinimum": true, "minimum": 0 }, "_lastSeen": { "type": "string", "deprecated": true }, "bin": { "type": "object", "deprecated": true } }, "required": [ "_count", "_interval" ] }, "count": { "type": "number" }, "errors": { "type": "number" }, "groups": { "description": "Groups in the query results.", "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "interval": { "type": "number" }, "sampleInterval": { "type": "number" } }, "required": [ "aggregates", "count", "interval", "sampleInterval" ], "type": "object" } }, "time": { "type": "string" } }, "required": [ "time", "data" ], "type": "object" } } } }, "invocations": { "description": "Events grouped by invocation (request ID). Present when the query view is 'invocations'. Each key is a request ID mapping to all events from that invocation.", "type": "object", "additionalProperties": { "items": { "$ref": "#/components/schemas/workers-observability_telemetry_event" }, "type": "array" } }, "run": { "$ref": "#/components/schemas/workers-observability_query_run" }, "statistics": { "$ref": "#/components/schemas/workers-observability_performance_information" }, "traces": { "description": "Trace summaries matching the query. Present when the query view is 'traces'. Each entry represents a distributed trace with its spans, duration, and services involved.", "type": "array", "items": { "properties": { "errors": { "description": "Error messages encountered during the trace, if any.", "type": "array", "items": { "type": "string" } }, "rootSpanName": { "description": "Name of the root span that initiated the trace.", "type": "string" }, "rootTransactionName": { "description": "Logical transaction name for the root span.", "type": "string" }, "service": { "description": "List of Worker services involved in the trace.", "type": "array", "items": { "type": "string" } }, "spans": { "description": "Total number of spans in the trace.", "type": "number" }, "traceDurationMs": { "description": "Total duration of the trace in milliseconds.", "type": "number" }, "traceEndMs": { "description": "Trace end time as a Unix epoch in milliseconds.", "type": "number" }, "traceId": { "description": "Unique identifier for the distributed trace.", "type": "string" }, "traceStartMs": { "description": "Trace start time as a Unix epoch in milliseconds.", "type": "number" } }, "required": [ "traceId", "spans", "service", "traceStartMs", "traceEndMs", "traceDurationMs", "rootSpanName", "rootTransactionName" ], "type": "object" } } }, "required": [ "run", "statistics" ] }, "workers-observability_query_run": { "description": "Represents a single execution of a query against Workers Observability data, including the query definition, execution status, and performance statistics.", "type": "object", "properties": { "accountId": { "description": "Cloudflare account ID that owns this query run.", "type": "string" }, "created": { "description": "ISO-8601 timestamp when the query run was created.", "type": "string" }, "dry": { "description": "Whether this was a dry run (results not persisted).", "type": "boolean" }, "granularity": { "description": "Number of time-series buckets used for the query. Higher values produce more detailed series data.", "type": "number" }, "id": { "description": "Unique identifier for this query run.", "type": "string" }, "query": { "description": "A saved query definition with its parameters, metadata, and ownership information.", "allOf": [ { "$ref": "#/components/schemas/workers-observability_query" }, { "properties": { "created": { "anyOf": [ { "type": "string" }, { "format": "date-time", "type": "string" } ] }, "updated": { "anyOf": [ { "type": "string" }, { "format": "date-time", "type": "string" } ] } }, "type": "object" } ] }, "statistics": { "description": "Query performance statistics from the database (does not include network latency).", "type": "object", "properties": { "abr_level": { "description": "The level of Adaptive Bit Rate (ABR) sampling used for the query. If empty the ABR level is 1", "type": "number" }, "bytes_read": { "description": "Number of uncompressed bytes read from the table.", "type": "number" }, "elapsed": { "description": "Time in seconds for the query to run.", "type": "number" }, "rows_read": { "description": "Number of rows scanned from the table.", "type": "number" } }, "required": [ "elapsed", "rows_read", "bytes_read" ] }, "status": { "description": "Current execution status of the query run.", "type": "string", "enum": [ "STARTED", "COMPLETED" ] }, "timeframe": { "description": "Time range for the query execution. 'from' must be earlier than 'to'. No fractional milliseconds.", "type": "object", "properties": { "from": { "description": "Start timestamp for the query timeframe. Unix timestamp in milliseconds", "type": "integer", "maximum": 253402300799999, "minimum": 0 }, "to": { "description": "End timestamp for the query timeframe. Unix timestamp in milliseconds", "type": "integer", "maximum": 253402300799999, "minimum": 0 } }, "required": [ "to", "from" ] }, "updated": { "description": "ISO-8601 timestamp when the query run was last updated.", "type": "string" }, "userId": { "description": "ID of the user who initiated the query run.", "type": "string" } }, "required": [ "id", "query", "accountId", "timeframe", "userId", "status", "granularity", "dry" ] }, "workers-observability_telemetry_event": { "description": "A single telemetry event representing a log line, span, or metric data point emitted by a Worker.", "type": "object", "properties": { "$containers": { "description": "Cloudflare Containers event information that enriches your logs for identifying and debugging issues.", "type": "object", "additionalProperties": true }, "$metadata": { "description": "Structured metadata extracted from the event. These fields are indexed and available for filtering and aggregation.", "type": "object", "properties": { "account": { "description": "Cloudflare account identifier.", "type": "string" }, "cloudService": { "description": "Cloudflare product that generated this event (e.g. workers, pages).", "type": "string" }, "coldStart": { "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "cost": { "description": "Estimated cost units for this invocation.", "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "duration": { "description": "Span duration in milliseconds.", "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "endTime": { "description": "Span end time as a Unix epoch in milliseconds.", "type": "integer", "minimum": 0 }, "error": { "description": "Error message, present when the log represents an error.", "type": "string" }, "errorTemplate": { "description": "Templatized version of the error message used for grouping similar errors.", "type": "string" }, "fingerprint": { "description": "Content-based fingerprint used to group similar events.", "type": "string" }, "id": { "description": "Unique event ID. Use as the cursor value for offset-based pagination.", "type": "string" }, "level": { "description": "Log level (e.g. log, debug, info, warn, error).", "type": "string" }, "message": { "description": "Log message text.", "type": "string" }, "messageTemplate": { "description": "Templatized version of the log message used for grouping similar messages.", "type": "string" }, "metricName": { "description": "Metric name when the event represents a metric data point.", "type": "string" }, "origin": { "description": "Origin of the event (e.g. fetch, scheduled, queue).", "type": "string" }, "parentSpanId": { "description": "Span ID of the parent span in the trace hierarchy.", "type": "string" }, "provider": { "description": "Infrastructure provider identifier.", "type": "string" }, "rayId": { "description": "Cloudflare Ray ID from the `cf-ray` header of the request that triggered the invocation.", "type": "string" }, "region": { "description": "Cloudflare data center / region that handled the request.", "type": "string" }, "requestId": { "description": "Cloudflare request ID that ties all logs from a single invocation together.", "type": "string" }, "service": { "description": "Worker script name that produced this event.", "type": "string" }, "spanId": { "description": "Span ID for this individual unit of work within a trace.", "type": "string" }, "spanName": { "description": "Human-readable name for this span.", "type": "string" }, "stackId": { "description": "Stack / deployment identifier.", "type": "string" }, "startTime": { "description": "Span start time as a Unix epoch in milliseconds.", "type": "integer", "minimum": 0 }, "statusCode": { "description": "HTTP response status code returned by the Worker.", "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "traceDuration": { "description": "Total duration of the entire trace in milliseconds.", "type": "integer", "exclusiveMinimum": true, "minimum": 0 }, "traceId": { "description": "Distributed trace ID linking spans across services.", "type": "string" }, "transactionName": { "description": "Logical transaction name for this request.", "type": "string" }, "trigger": { "description": "What triggered the invocation (e.g. GET /users, POST /orders, queue message).", "type": "string" }, "type": { "description": "Event type classifier (e.g. cf-worker-event, cf-worker-log).", "type": "string" }, "url": { "description": "Request URL that triggered the Worker invocation.", "type": "string" } }, "required": [ "id" ] }, "$workers": { "description": "Cloudflare Workers event information that enriches your logs for identifying and debugging issues.", "anyOf": [ { "properties": { "durableObjectId": { "type": "string" }, "entrypoint": { "type": "string" }, "event": { "type": "object", "additionalProperties": true }, "eventType": { "type": "string", "enum": [ "fetch", "scheduled", "alarm", "cron", "queue", "email", "tail", "rpc", "jsrpc", "websocket", "workflow", "unknown" ] }, "executionModel": { "type": "string", "enum": [ "durableObject", "stateless" ] }, "outcome": { "type": "string" }, "preview": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "requestId": { "type": "string" }, "scriptName": { "type": "string" }, "scriptVersion": { "type": "object", "properties": { "id": { "type": "string" }, "message": { "type": "string" }, "tag": { "type": "string" } } }, "spanId": { "type": "string" }, "traceId": { "type": "string" }, "truncated": { "type": "boolean" } }, "required": [ "scriptName", "eventType", "requestId" ], "type": "object" }, { "properties": { "cpuTimeMs": { "type": "number" }, "diagnosticsChannelEvents": { "type": "array", "items": { "properties": { "channel": { "type": "string" }, "message": { "type": "string" }, "timestamp": { "type": "number" } }, "required": [ "timestamp", "channel", "message" ], "type": "object" } }, "dispatchNamespace": { "type": "string" }, "durableObjectId": { "type": "string" }, "entrypoint": { "type": "string" }, "event": { "type": "object", "additionalProperties": true }, "eventType": { "type": "string", "enum": [ "fetch", "scheduled", "alarm", "cron", "queue", "email", "tail", "rpc", "jsrpc", "websocket", "workflow", "unknown" ] }, "executionModel": { "type": "string", "enum": [ "durableObject", "stateless" ] }, "outcome": { "type": "string" }, "preview": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "requestId": { "type": "string" }, "scriptName": { "type": "string" }, "scriptVersion": { "type": "object", "properties": { "id": { "type": "string" }, "message": { "type": "string" }, "tag": { "type": "string" } } }, "spanId": { "type": "string" }, "traceId": { "type": "string" }, "truncated": { "type": "boolean" }, "wallTimeMs": { "type": "number" } }, "required": [ "scriptName", "outcome", "eventType", "wallTimeMs", "cpuTimeMs", "requestId" ], "type": "object" } ] }, "dataset": { "description": "The dataset this event belongs to (e.g. cloudflare-workers).", "type": "string" }, "source": { "description": "Raw log payload. May be a string or a structured object depending on how the log was emitted.", "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ] }, "timestamp": { "description": "Event timestamp as a Unix epoch in milliseconds.", "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "dataset", "timestamp", "source", "$metadata" ] }, "workers_Domain": { "type": "object", "properties": { "cert_id": { "description": "ID of the TLS certificate issued for the domain.", "type": "string", "format": "uuid", "example": "9fdf92c8-64c2-4a3d-b1af-e15304961145", "readOnly": true, "x-auditable": true }, "environment": { "description": "Worker environment associated with the domain.", "type": "string", "example": "production", "deprecated": true, "readOnly": true, "x-auditable": true }, "hostname": { "description": "Hostname of the domain. Can be either the zone apex or a subdomain of the zone. Requests to this hostname will be routed to the configured Worker.", "type": "string", "example": "app.example.com", "x-auditable": true }, "id": { "description": "Immutable ID of the domain.", "type": "string", "example": "dbe10b4bc17c295377eabd600e1787fd", "readOnly": true, "x-auditable": true }, "service": { "description": "Name of the Worker associated with the domain. Requests to the configured hostname will be routed to this Worker.", "type": "string", "example": "my-worker", "x-auditable": true }, "zone_id": { "description": "ID of the zone containing the domain hostname.", "type": "string", "example": "593c9c94de529bbbfaac7c53ced0447d", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "zone_name": { "description": "Name of the zone containing the domain hostname.", "type": "string", "example": "example.com", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "id", "cert_id", "environment", "zone_id", "zone_name", "hostname", "service" ] }, "workers_ErrorAuth": { "type": "object", "properties": { "code": { "description": "Code indicating that the user is not authorized to perform this action.", "type": "integer", "enum": [ 10023 ] }, "message": { "description": "Message explaining that the user lacks access to this feature.", "type": "string" } }, "required": [ "code", "message" ] }, "workers_ErrorInternalServer": { "type": "object", "properties": { "code": { "description": "Code indicating that an unknown internal server error has occurred.", "type": "integer", "enum": [ 10002 ] }, "message": { "description": "Message explaining that an unknown error occurred and providing guidance for reporting the issue.", "type": "string" } }, "required": [ "code", "message" ] }, "workers_ErrorMissingParam": { "type": "object", "properties": { "code": { "description": "Code indicating that a required URL parameter is missing.", "type": "integer", "enum": [ 10003 ] }, "message": { "description": "Message explaining which required parameter is missing and suggesting to check the URL.", "type": "string" } }, "required": [ "code", "message" ] }, "workers_ErrorWorkerInvalid": { "type": "object", "properties": { "code": { "description": "Code indicating that the Worker request contains invalid data.", "type": "integer", "enum": [ 10021 ] }, "message": { "description": "Message explaining why the Worker request is invalid, such as malformed JSON.", "type": "string" } }, "required": [ "code", "message" ] }, "workers_ErrorWorkerLimit": { "type": "object", "properties": { "code": { "description": "Code indicating that the account has exceeded the maximum number of Workers allowed.", "type": "integer", "enum": [ 10037 ] }, "message": { "description": "Message explaining that the Worker limit has been exceeded and providing guidance.", "type": "string" } }, "required": [ "code", "message" ] }, "workers_ErrorWorkerNameConflict": { "type": "object", "properties": { "code": { "description": "Code indicating that a Worker with this name already exists.", "type": "integer", "enum": [ 10040 ] }, "message": { "description": "Message explaining that the Worker name is already in use and suggesting to choose a different name.", "type": "string" } }, "required": [ "code", "message" ] }, "workers_ErrorWorkerNameInvalid": { "type": "object", "properties": { "code": { "description": "Code indicating that the Worker name is invalid.", "type": "integer", "enum": [ 10016 ] }, "message": { "description": "Message explaining why the Worker name is invalid.", "type": "string" } }, "required": [ "code", "message" ] }, "workers_ErrorWorkerNamePreviewLengthLimit": { "type": "object", "properties": { "code": { "description": "Code indicating that the Worker name is too long to be used with previews enabled.", "type": "integer", "enum": [ 100315 ] }, "message": { "description": "Message explaining that Worker names with previews enabled cannot exceed 54 characters.", "type": "string" } }, "required": [ "code", "message" ] }, "workers_ErrorWorkerNameSubdomainLengthLimit": { "type": "object", "properties": { "code": { "description": "Code indicating that the Worker name is too long to be used as a subdomain.", "type": "integer", "enum": [ 100132 ] }, "message": { "description": "Message explaining that the Worker name exceeds the 63 character limit for subdomains.", "type": "string" } }, "required": [ "code", "message" ] }, "workers_ErrorWorkerNotFound": { "type": "object", "properties": { "code": { "description": "Code indicating that the Worker does not exist.", "type": "integer", "enum": [ 10007 ] }, "message": { "description": "Message explaining that the Worker was not found.", "type": "string" } }, "required": [ "code", "message" ] }, "workers_ErrorWorkerObservabilitySamplingRateInvalid": { "type": "object", "properties": { "code": { "description": "Code indicating that an observability sampling rate is invalid.", "type": "integer", "enum": [ 100308 ] }, "message": { "description": "Message explaining that sampling rates must be between 0 and 1 inclusive.", "type": "string" } }, "required": [ "code", "message" ] }, "workers_ErrorWorkerTagInvalid": { "type": "object", "properties": { "code": { "description": "Code indicating that the Worker has a tag containing invalid characters.", "type": "integer", "enum": [ 100134 ] }, "message": { "description": "Message explaining that tags cannot contain certain characters like comma or ampersand.", "type": "string" } }, "required": [ "code", "message" ] }, "workers_ErrorWorkerTagLengthLimit": { "type": "object", "properties": { "code": { "description": "Code indicating that the Worker has a tag that exceeds the maximum tag length.", "type": "integer", "enum": [ 100102 ] }, "message": { "description": "Message explaining why the tag is too long, including the maximum tag length.", "type": "string" } }, "required": [ "code", "message" ] }, "workers_ErrorWorkerTagLimit": { "type": "object", "properties": { "code": { "description": "Code indicating that the Worker has exceeded the maximum number of tags allowed.", "type": "integer", "enum": [ 100103 ] }, "message": { "description": "Message explaining that the tag limit has been exceeded and suggesting to remove a tag.", "type": "string" } }, "required": [ "code", "message" ] }, "workers_Version": { "type": "object", "properties": { "annotations": { "description": "Metadata about the version.", "type": "object", "properties": { "workers/message": { "description": "Human-readable message about the version. Truncated to 1000 bytes if longer.", "type": "string", "example": "Fixed bug.", "maxLength": 1000, "x-auditable": true }, "workers/tag": { "description": "User-provided identifier for the version. Maximum 100 bytes.", "type": "string", "example": "v1.0.1", "maxLength": 100, "x-auditable": true }, "workers/triggered_by": { "description": "Operation that triggered the creation of the version.", "type": "string", "example": "upload", "readOnly": true, "x-auditable": true } } }, "assets": { "description": "Configuration for assets within a Worker.\n\n[`_headers`](https://developers.cloudflare.com/workers/static-assets/headers/#custom-headers) and\n[`_redirects`](https://developers.cloudflare.com/workers/static-assets/redirects/) files should be\nincluded as modules named `_headers` and `_redirects` with content type `text/plain`.\n", "type": "object", "properties": { "config": { "description": "Configuration for assets within a Worker.", "type": "object", "properties": { "html_handling": { "description": "Determines the redirects and rewrites of requests for HTML content.", "type": "string", "example": "auto-trailing-slash", "default": "auto-trailing-slash", "enum": [ "auto-trailing-slash", "force-trailing-slash", "drop-trailing-slash", "none" ], "x-auditable": true }, "not_found_handling": { "description": "Determines the response when a request does not match a static asset, and there is no Worker script.", "type": "string", "example": "404-page", "default": "none", "enum": [ "none", "404-page", "single-page-application" ], "x-auditable": true }, "run_worker_first": { "default": false, "oneOf": [ { "description": "Contains a list path rules to control routing to either the Worker or assets. Glob (*) and negative (!) rules are supported. Rules must start with either '/' or '!/'. At least one non-negative rule must be provided, and negative rules have higher precedence than non-negative rules.", "example": "[\"/api/*\", \"/oauth/callback\", \"!/api/assets/*\"]", "items": { "type": "string" }, "type": "array" }, { "description": "Enables routing to always invoke the Worker script ahead of all requests. When true, this is equivalent to `[\"/*\"]` in the string array version of this field.", "example": true, "type": "boolean" } ] } } }, "jwt": { "description": "Token provided upon successful upload of all files from a registered manifest.", "type": "string", "x-sensitive": true } } }, "author_email": { "description": "Email of the user who created the version.", "type": "string", "format": "email", "example": "user@example.com", "readOnly": true, "x-auditable": true }, "author_id": { "description": "Identifier of the user who created the version.", "type": "string", "example": "408cbcdfd4dda4617efef40b04d168a1", "readOnly": true, "x-auditable": true }, "bindings": { "$ref": "#/components/schemas/workers_bindings" }, "cache_options": { "$ref": "#/components/schemas/workers_cache_options" }, "compatibility_date": { "$ref": "#/components/schemas/workers_compatibility_date" }, "compatibility_flags": { "$ref": "#/components/schemas/workers_compatibility_flags" }, "containers": { "$ref": "#/components/schemas/workers_containers" }, "created_on": { "description": "When the version was created.", "type": "string", "format": "date-time", "readOnly": true, "x-auditable": true }, "exports": { "description": "Declarative exports for the version, including Durable Object\nclasses (with their `storage` backend) and named Worker\nentrypoints. On reads, tombstoned lifecycle entries are\nomitted, so only live exports (`created` and\n`expecting-transfer`) are returned. `exports` and `migrations`\nare mutually exclusive on upload.\n", "allOf": [ { "$ref": "#/components/schemas/workers_exports_config_map" } ] }, "exports_reconciliation": { "description": "Summary of the declarative exports reconciliation that ran on\nthis upload. Populated only when the uploaded metadata included\nan `exports` block. Durable Object entries drive reconciliation;\n`type: worker` entries do not contribute to this summary.\n", "allOf": [ { "$ref": "#/components/schemas/workers_exports_reconciliation_result" } ] }, "id": { "description": "Version identifier.", "type": "string", "format": "uuid", "readOnly": true, "x-auditable": true }, "limits": { "description": "Resource limits enforced at runtime.", "type": "object", "properties": { "cpu_ms": { "description": "CPU time limit in milliseconds.", "type": "integer", "example": 50 }, "subrequests": { "description": "Subrequest limit per request.", "type": "integer", "example": 1000 } }, "x-stainless-terraform-configurability": "computed_optional" }, "main_module": { "description": "The name of the main module in the `modules` array (e.g. the name of the module that exports a `fetch` handler).", "type": "string", "example": "index.js", "x-auditable": true }, "migration_tag": { "description": "Durable Object migration tag. Set when the version is deployed. Omitted if the version has not been deployed or the Worker does not use Durable Objects.", "type": "string", "example": "v1", "readOnly": true }, "migrations": { "description": "Migrations for Durable Objects associated with the version. Migrations are applied when the version is deployed.", "oneOf": [ { "$ref": "#/components/schemas/workers_single_step_migrations" }, { "$ref": "#/components/schemas/workers_multiple_step_migrations" } ] }, "modules": { "description": "Code, sourcemaps, and other content used at runtime.\n\nThis includes [`_headers`](https://developers.cloudflare.com/workers/static-assets/headers/#custom-headers) and\n[`_redirects`](https://developers.cloudflare.com/workers/static-assets/redirects/) files used to configure \n[Static Assets](https://developers.cloudflare.com/workers/static-assets/). `_headers` and `_redirects` files should be \nincluded as modules named `_headers` and `_redirects` with content type `text/plain`.\n", "type": "array", "items": { "properties": { "content_base64": { "description": "The base64-encoded module content.", "type": "string", "format": "byte", "example": "ZXhwb3J0IGRlZmF1bHQgewogIGFzeW5jIGZldGNoKHJlcXVlc3QsIGVudiwgY3R4KSB7CiAgICByZXR1cm4gbmV3IFJlc3BvbnNlKCdIZWxsbyBXb3JsZCEnKQogIH0KfQ==" }, "content_type": { "description": "The content type of the module.", "type": "string", "example": "application/javascript+module" }, "name": { "description": "The name of the module.", "type": "string", "example": "index.js" } }, "required": [ "name", "content_type", "content_base64" ], "type": "object" }, "x-stainless-collection-type": "set" }, "number": { "description": "The integer version number, starting from one.", "type": "integer", "readOnly": true, "x-auditable": true }, "package_dependencies": { "description": "The list of npm packages that were installed and used when this Worker\nversion was built.\n", "type": "array", "items": { "properties": { "installedVersion": { "description": "The exact version that was resolved and installed by the package manager.", "type": "string", "example": "4.17.22" }, "name": { "description": "The npm package name.", "type": "string", "example": "lodash" }, "packageJsonVersion": { "description": "The version constraint as written in package.json.", "type": "string", "example": "^4.17.21" } }, "required": [ "name", "packageJsonVersion", "installedVersion" ], "type": "object" }, "x-auditable": true }, "placement": { "$ref": "#/components/schemas/workers_placement_info_no_status" }, "source": { "description": "The client used to create the version.", "type": "string", "example": "wrangler", "readOnly": true, "x-auditable": true }, "startup_time_ms": { "description": "Time in milliseconds spent on [Worker startup](https://developers.cloudflare.com/workers/platform/limits/#worker-startup-time).", "type": "integer", "example": 10, "readOnly": true, "x-auditable": true }, "urls": { "description": "All routable URLs that always point to this version. Does not include alias URLs, since aliases can be updated to point to a different version.", "type": "array", "items": { "format": "uri", "type": "string" }, "example": [ "https://9387e76d-my-worker.my-subdomain.workers.dev" ], "readOnly": true }, "usage_model": { "description": "Usage model for the version.", "type": "string", "example": "standard", "default": "standard", "enum": [ "standard", "bundled", "unbound" ], "deprecated": true, "x-auditable": true } }, "required": [ "id", "number", "urls", "created_on" ] }, "workers_Worker": { "type": "object", "properties": { "created_on": { "description": "When the Worker was created.", "type": "string", "format": "date-time", "readOnly": true, "x-auditable": true }, "deployed_on": { "description": "When the Worker's most recent deployment was created. `null` if the Worker has never been deployed.", "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "id": { "description": "Immutable ID of the Worker.", "type": "string", "example": "e8f70fdbc8b1fb0b8ddb1af166186758", "readOnly": true, "x-auditable": true }, "logpush": { "description": "Whether logpush is enabled for the Worker.", "type": "boolean", "default": false, "x-auditable": true }, "name": { "description": "Name of the Worker.", "type": "string", "example": "my-worker", "pattern": "^[a-z0-9_][a-z0-9-_]*$", "x-auditable": true }, "observability": { "description": "Observability settings for the Worker.", "type": "object", "properties": { "enabled": { "description": "Whether observability is enabled for the Worker.", "type": "boolean", "default": false, "x-auditable": true }, "head_sampling_rate": { "description": "The sampling rate for observability. From 0 to 1 (1 = 100%, 0.1 = 10%).", "type": "number", "example": 1, "default": 1, "x-auditable": true }, "logs": { "description": "Log settings for the Worker.", "type": "object", "properties": { "destinations": { "description": "A list of destinations where logs will be exported to.", "type": "array", "items": { "type": "string" }, "default": [], "x-auditable": true }, "enabled": { "description": "Whether logs are enabled for the Worker.", "type": "boolean", "default": false, "x-auditable": true }, "head_sampling_rate": { "description": "The sampling rate for logs. From 0 to 1 (1 = 100%, 0.1 = 10%).", "type": "number", "example": 1, "default": 1, "x-auditable": true }, "invocation_logs": { "description": "Whether [invocation logs](https://developers.cloudflare.com/workers/observability/logs/workers-logs/#invocation-logs) are enabled for the Worker.", "type": "boolean", "default": true, "x-auditable": true }, "persist": { "description": "Whether log persistence is enabled for the Worker.", "type": "boolean", "default": true, "x-auditable": true } } }, "redact_query_string": { "description": "Whether query strings are removed from request URLs in logs and traces.", "type": "boolean", "default": false, "x-auditable": true }, "traces": { "description": "Trace settings for the Worker.", "type": "object", "properties": { "destinations": { "description": "A list of destinations where traces will be exported to.", "type": "array", "items": { "type": "string" }, "default": [], "x-auditable": true }, "enabled": { "description": "Whether traces are enabled for the Worker.", "type": "boolean", "default": false, "x-auditable": true }, "head_sampling_rate": { "description": "The sampling rate for traces. From 0 to 1 (1 = 100%, 0.1 = 10%).", "type": "number", "example": 1, "default": 1, "x-auditable": true }, "persist": { "description": "Whether trace persistence is enabled for the Worker.", "type": "boolean", "default": true, "x-auditable": true }, "propagation_policy": { "description": "Controls how inbound trace context (traceparent/tracestate) headers on incoming requests are handled. \"authenticated\" honors inbound trace context only when accompanied by a valid trace auth token. \"accept\" unconditionally accepts inbound trace context. Requires the trace propagation feature to be enabled. Returns null when the trace propagation feature is not enabled for the account.", "type": "string", "enum": [ "authenticated", "accept", null ], "nullable": true, "x-auditable": true } } } } }, "references": { "description": "Other resources that reference the Worker and depend on it existing.", "type": "object", "properties": { "dispatch_namespace_outbounds": { "description": "Other Workers that reference the Worker as an outbound for a dispatch namespace.", "type": "array", "items": { "properties": { "namespace_id": { "description": "ID of the dispatch namespace.", "type": "string", "example": "e8f70fdbc8b1fb0b8ddb1af166186758" }, "namespace_name": { "description": "Name of the dispatch namespace.", "type": "string", "example": "my-dispatch-namespace" }, "worker_id": { "description": "ID of the Worker using the dispatch namespace.", "type": "string", "example": "e8f70fdbc8b1fb0b8ddb1af166186758" }, "worker_name": { "description": "Name of the Worker using the dispatch namespace.", "type": "string", "example": "my-worker" } }, "required": [ "worker_id", "worker_name", "namespace_id", "namespace_name" ], "type": "object" } }, "domains": { "description": "Custom domains connected to the Worker.", "type": "array", "items": { "properties": { "certificate_id": { "description": "ID of the TLS certificate issued for the custom domain.", "type": "string" }, "hostname": { "description": "Full hostname of the custom domain, including the zone name.", "type": "string", "example": "my-worker.example.com" }, "id": { "description": "ID of the custom domain.", "type": "string", "example": "e8f70fdbc8b1fb0b8ddb1af166186758" }, "zone_id": { "description": "ID of the zone.", "type": "string", "example": "e8f70fdbc8b1fb0b8ddb1af166186758" }, "zone_name": { "description": "Name of the zone.", "type": "string", "example": "example.com" } }, "required": [ "id", "hostname", "zone_id", "zone_name", "certificate_id" ], "type": "object" } }, "durable_objects": { "description": "Other Workers that reference Durable Object classes implemented by the Worker.", "type": "array", "items": { "properties": { "namespace_id": { "description": "ID of the Durable Object namespace being used.", "type": "string", "example": "e8f70fdbc8b1fb0b8ddb1af166186758" }, "namespace_name": { "description": "Name of the Durable Object namespace being used.", "type": "string", "example": "my-durable-object-namespace" }, "worker_id": { "description": "ID of the Worker using the Durable Object implementation.", "type": "string", "example": "e8f70fdbc8b1fb0b8ddb1af166186758" }, "worker_name": { "description": "Name of the Worker using the Durable Object implementation.", "type": "string", "example": "my-worker" } }, "required": [ "worker_id", "worker_name", "namespace_id", "namespace_name" ], "type": "object" } }, "queues": { "description": "Queues that send messages to the Worker.", "type": "array", "items": { "properties": { "queue_consumer_id": { "description": "ID of the queue consumer configuration.", "type": "string", "example": "e8f70fdbc8b1fb0b8ddb1af166186758" }, "queue_id": { "description": "ID of the queue.", "type": "string", "example": "e8f70fdbc8b1fb0b8ddb1af166186758" }, "queue_name": { "description": "Name of the queue.", "type": "string", "example": "my-queue" } }, "required": [ "queue_id", "queue_name", "queue_consumer_id" ], "type": "object" } }, "workers": { "description": "Other Workers that reference the Worker using [service bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/).", "type": "array", "items": { "properties": { "id": { "description": "ID of the referencing Worker.", "type": "string", "example": "e8f70fdbc8b1fb0b8ddb1af166186758" }, "name": { "description": "Name of the referencing Worker.", "type": "string", "example": "my-worker" } }, "required": [ "id", "name" ], "type": "object" } } }, "readOnly": true, "required": [ "workers", "domains", "dispatch_namespace_outbounds", "durable_objects", "queues" ] }, "subdomain": { "description": "Subdomain settings for the Worker.", "type": "object", "properties": { "enabled": { "description": "Whether the *.workers.dev subdomain is enabled for the Worker.", "type": "boolean", "default": false, "x-auditable": true }, "preview_url_suffix": { "description": "Prepend a version or preview prefix to this host suffix to form the *.workers.dev [preview URL](https://developers.cloudflare.com/workers/configuration/previews/) the Worker would serve on once previews are enabled, e.g. `https://-my-worker.my-subdomain.workers.dev`. Present whenever the account owns a workers.dev subdomain, regardless of whether `previews_enabled` is true, so presence does not imply preview URLs are currently live. Absent only when the account owns no workers.dev subdomain.", "type": "string", "example": "-my-worker.my-subdomain.workers.dev", "readOnly": true }, "previews_enabled": { "description": "Whether [preview URLs](https://developers.cloudflare.com/workers/configuration/previews/) are enabled for the Worker.", "type": "boolean", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "url": { "description": "The address the Worker would serve on once its *.workers.dev subdomain is enabled. Present whenever the account owns a workers.dev subdomain, regardless of whether `enabled` is true, so presence does not imply the Worker is currently live at this URL. Absent only when the account owns no workers.dev subdomain.", "type": "string", "format": "uri", "example": "https://my-worker.my-subdomain.workers.dev", "readOnly": true } } }, "tags": { "description": "Tags associated with the Worker.", "type": "array", "items": { "maxLength": 1024, "pattern": "^[^,&]*$", "type": "string" }, "example": [ "my-team", "my-public-api" ], "default": [], "maxItems": 8, "x-stainless-collection-type": "set" }, "tail_consumers": { "description": "Other Workers that should consume logs from the Worker.", "type": "array", "items": { "properties": { "name": { "description": "Name of the consumer Worker.", "type": "string", "example": "my-tail-consumer", "x-auditable": true } }, "required": [ "name" ], "type": "object" }, "default": [], "x-stainless-collection-type": "set" }, "updated_on": { "description": "When the Worker was most recently updated.", "type": "string", "format": "date-time", "readOnly": true, "x-auditable": true } }, "required": [ "id", "name", "tags", "subdomain", "observability", "logpush", "tail_consumers", "created_on", "updated_on", "references" ] }, "workers_account-settings": { "type": "object", "properties": { "default_usage_model": { "type": "string", "x-auditable": true }, "green_compute": { "type": "boolean", "x-auditable": true } } }, "workers_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "The number of total pages in the entire result set.", "type": "number", "example": 100 } } } }, "type": "object" } ] }, "workers_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/workers_messages" }, "messages": { "$ref": "#/components/schemas/workers_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "workers_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/workers_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/workers_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "workers_api-response-null-result": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "object", "enum": [ null ], "nullable": true } }, "type": "object" } ] }, "workers_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" } ] }, "workers_assets": { "description": "Configuration for assets within a Worker.", "type": "object", "properties": { "config": { "description": "Configuration for assets within a Worker.", "type": "object", "properties": { "_headers": { "description": "The contents of a _headers file (used to attach custom headers on asset responses).", "type": "string", "example": "/dashboard/*\nX-Frame-Options: DENY\n\n/static/*\nAccess-Control-Allow-Origin: *" }, "_redirects": { "description": "The contents of a _redirects file (used to apply redirects or proxy paths ahead of asset serving).", "type": "string", "example": "/foo /bar 301\n/news/* /blog/:splat" }, "html_handling": { "description": "Determines the redirects and rewrites of requests for HTML content.", "type": "string", "example": "auto-trailing-slash", "enum": [ "auto-trailing-slash", "force-trailing-slash", "drop-trailing-slash", "none" ] }, "not_found_handling": { "description": "Determines the response when a request does not match a static asset, and there is no Worker script.", "type": "string", "example": "404-page", "enum": [ "none", "404-page", "single-page-application" ] }, "run_worker_first": { "oneOf": [ { "description": "Contains a list path rules to control routing to either the Worker or assets. Glob (*) and negative (!) rules are supported. Rules must start with either '/' or '!/'. At least one non-negative rule must be provided, and negative rules have higher precedence than non-negative rules.", "example": "[\"/api/*\", \"/oauth/callback\", \"!/api/assets/*\"]", "items": { "type": "string" }, "type": "array" }, { "description": "Enables routing to always invoke the Worker script ahead of all requests. When true, this is equivalent to `[\"/*\"]` in the string array version of this field.", "example": true, "type": "boolean" } ] }, "serve_directly": { "description": "When true and the incoming request matches an asset, that will be served instead of invoking the Worker script. When false, requests will always invoke the Worker script.", "type": "boolean", "example": true, "deprecated": true } } }, "jwt": { "description": "Token provided upon successful upload of all files from a registered manifest.", "type": "string", "x-sensitive": true } } }, "workers_binding_item": { "description": "A binding to allow the Worker to communicate with resources.", "type": "object", "discriminator": { "mapping": { "ai": "#/components/schemas/workers_binding_kind_ai", "ai_search": "#/components/schemas/workers_binding_kind_ai_search", "ai_search_namespace": "#/components/schemas/workers_binding_kind_ai_search_namespace", "analytics_engine": "#/components/schemas/workers_binding_kind_analytics_engine", "assets": "#/components/schemas/workers_binding_kind_assets", "browser": "#/components/schemas/workers_binding_kind_browser", "d1": "#/components/schemas/workers_binding_kind_d1", "data_blob": "#/components/schemas/workers_binding_kind_data_blob", "dispatch_namespace": "#/components/schemas/workers_binding_kind_dispatch_namespace", "durable_object_namespace": "#/components/schemas/workers_binding_kind_durable_object_namespace", "flagship": "#/components/schemas/workers_binding_kind_flagship", "hyperdrive": "#/components/schemas/workers_binding_kind_hyperdrive", "images": "#/components/schemas/workers_binding_kind_images", "inherit": "#/components/schemas/workers_binding_kind_inherit", "json": "#/components/schemas/workers_binding_kind_json", "kv_namespace": "#/components/schemas/workers_binding_kind_kv_namespace", "media": "#/components/schemas/workers_binding_kind_media", "messaging": "#/components/schemas/workers_binding_kind_messaging", "mtls_certificate": "#/components/schemas/workers_binding_kind_mtls_certificate", "pipelines": "#/components/schemas/workers_binding_kind_pipelines", "plain_text": "#/components/schemas/workers_binding_kind_plain_text", "queue": "#/components/schemas/workers_binding_kind_queue", "r2_bucket": "#/components/schemas/workers_binding_kind_r2_bucket", "ratelimit": "#/components/schemas/workers_binding_kind_ratelimit", "secret_key": "#/components/schemas/workers_binding_kind_secret_key", "secret_text": "#/components/schemas/workers_binding_kind_secret_text", "secrets_store_secret": "#/components/schemas/workers_binding_kind_secrets_store_secret", "send_email": "#/components/schemas/workers_binding_kind_send_email", "service": "#/components/schemas/workers_binding_kind_service", "text_blob": "#/components/schemas/workers_binding_kind_text_blob", "vectorize": "#/components/schemas/workers_binding_kind_vectorize", "version_metadata": "#/components/schemas/workers_binding_kind_version_metadata", "vpc_network": "#/components/schemas/workers_binding_kind_vpc_network", "vpc_service": "#/components/schemas/workers_binding_kind_vpc_service", "wasm_module": "#/components/schemas/workers_binding_kind_wasm_module", "workflow": "#/components/schemas/workers_binding_kind_workflow" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/workers_binding_kind_ai" }, { "$ref": "#/components/schemas/workers_binding_kind_ai_search" }, { "$ref": "#/components/schemas/workers_binding_kind_ai_search_namespace" }, { "$ref": "#/components/schemas/workers_binding_kind_messaging" }, { "$ref": "#/components/schemas/workers_binding_kind_analytics_engine" }, { "$ref": "#/components/schemas/workers_binding_kind_assets" }, { "$ref": "#/components/schemas/workers_binding_kind_browser" }, { "$ref": "#/components/schemas/workers_binding_kind_d1" }, { "$ref": "#/components/schemas/workers_binding_kind_data_blob" }, { "$ref": "#/components/schemas/workers_binding_kind_dispatch_namespace" }, { "$ref": "#/components/schemas/workers_binding_kind_durable_object_namespace" }, { "$ref": "#/components/schemas/workers_binding_kind_hyperdrive" }, { "$ref": "#/components/schemas/workers_binding_kind_inherit" }, { "$ref": "#/components/schemas/workers_binding_kind_images" }, { "$ref": "#/components/schemas/workers_binding_kind_json" }, { "$ref": "#/components/schemas/workers_binding_kind_kv_namespace" }, { "$ref": "#/components/schemas/workers_binding_kind_media" }, { "$ref": "#/components/schemas/workers_binding_kind_mtls_certificate" }, { "$ref": "#/components/schemas/workers_binding_kind_plain_text" }, { "$ref": "#/components/schemas/workers_binding_kind_pipelines" }, { "$ref": "#/components/schemas/workers_binding_kind_queue" }, { "$ref": "#/components/schemas/workers_binding_kind_ratelimit" }, { "$ref": "#/components/schemas/workers_binding_kind_r2_bucket" }, { "$ref": "#/components/schemas/workers_binding_kind_secret_text" }, { "$ref": "#/components/schemas/workers_binding_kind_send_email" }, { "$ref": "#/components/schemas/workers_binding_kind_service" }, { "$ref": "#/components/schemas/workers_binding_kind_text_blob" }, { "$ref": "#/components/schemas/workers_binding_kind_vectorize" }, { "$ref": "#/components/schemas/workers_binding_kind_version_metadata" }, { "$ref": "#/components/schemas/workers_binding_kind_secrets_store_secret" }, { "$ref": "#/components/schemas/workers_binding_kind_flagship" }, { "$ref": "#/components/schemas/workers_binding_kind_secret_key" }, { "$ref": "#/components/schemas/workers_binding_kind_workflow" }, { "$ref": "#/components/schemas/workers_binding_kind_wasm_module" }, { "$ref": "#/components/schemas/workers_binding_kind_vpc_service" }, { "$ref": "#/components/schemas/workers_binding_kind_vpc_network" } ] }, "workers_binding_kind_ai": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "ai" ], "x-auditable": true } }, "required": [ "name", "type" ] }, "workers_binding_kind_ai_search": { "type": "object", "properties": { "instance_name": { "description": "The user-chosen instance name. Must exist at deploy time. The worker can search, chat, update, and manage items/jobs on this instance.", "type": "string", "example": "cloudflare-blog", "x-auditable": true }, "name": { "$ref": "#/components/schemas/workers_binding_name" }, "namespace": { "description": "The namespace the instance belongs to. Defaults to \"default\" if omitted. Customers who don't use namespaces can simply omit this field.", "type": "string", "example": "production", "x-auditable": true }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "ai_search" ], "x-auditable": true } }, "required": [ "name", "type", "instance_name" ] }, "workers_binding_kind_ai_search_namespace": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "namespace": { "description": "The user-chosen namespace name. Must exist before deploy -- Wrangler handles auto-creation on deploy failure (R2 bucket pattern). The \"default\" namespace is auto-created by config-api for new accounts. Grants full access (CRUD + search + chat) to all instances within the namespace.", "type": "string", "example": "production", "x-auditable": true }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "ai_search_namespace" ], "x-auditable": true } }, "required": [ "name", "type", "namespace" ] }, "workers_binding_kind_analytics_engine": { "type": "object", "properties": { "dataset": { "description": "The name of the dataset to bind to.", "type": "string", "example": "some_dataset", "x-auditable": true }, "name": { "$ref": "#/components/schemas/workers_binding_name" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "analytics_engine" ], "x-auditable": true } }, "required": [ "name", "type", "dataset" ] }, "workers_binding_kind_assets": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "assets" ], "x-auditable": true } }, "required": [ "name", "type" ] }, "workers_binding_kind_browser": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "browser" ], "x-auditable": true } }, "required": [ "name", "type" ] }, "workers_binding_kind_d1": { "type": "object", "properties": { "database_id": { "description": "Identifier of the D1 database to bind to.", "type": "string", "example": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "x-auditable": true }, "id": { "description": "Identifier of the D1 database to bind to.", "type": "string", "example": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "deprecated": true, "x-auditable": true, "x-stainless-deprecation-message": "This property has been renamed to `database_id`." }, "name": { "$ref": "#/components/schemas/workers_binding_name" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "d1" ], "x-auditable": true } }, "required": [ "name", "type", "database_id" ] }, "workers_binding_kind_data_blob": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "part": { "description": "The name of the file containing the data content. Only accepted for `service worker syntax` Workers.", "type": "string", "example": "my-module.bin", "x-auditable": true }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "data_blob" ], "deprecated": true, "x-auditable": true } }, "required": [ "name", "type", "part" ] }, "workers_binding_kind_dispatch_namespace": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "namespace": { "description": "The name of the dispatch namespace.", "type": "string", "example": "my-namespace", "x-auditable": true }, "outbound": { "description": "Outbound worker.", "type": "object", "properties": { "params": { "description": "Pass information from the Dispatch Worker to the Outbound Worker through the parameters.", "type": "array", "items": { "properties": { "name": { "description": "Name of the parameter.", "type": "string", "example": "customer_name", "x-auditable": true } }, "required": [ "name" ], "type": "object" } }, "worker": { "description": "Outbound worker.", "type": "object", "properties": { "entrypoint": { "description": "Entrypoint to invoke on the outbound worker.", "type": "string", "x-auditable": true }, "environment": { "description": "Environment of the outbound worker.", "type": "string", "x-auditable": true }, "service": { "description": "Name of the outbound worker.", "type": "string", "x-auditable": true } } } } }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "dispatch_namespace" ], "x-auditable": true } }, "required": [ "name", "type", "namespace" ] }, "workers_binding_kind_durable_object_namespace": { "type": "object", "properties": { "class_name": { "description": "The exported class name of the Durable Object.", "type": "string", "example": "MyDurableObject", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "dispatch_namespace": { "description": "The dispatch namespace the Durable Object script belongs to.", "type": "string", "example": "my-dispatch-namespace", "x-auditable": true }, "environment": { "description": "The environment of the script_name to bind to.", "type": "string", "example": "production", "x-auditable": true }, "name": { "$ref": "#/components/schemas/workers_binding_name" }, "namespace_id": { "allOf": [ { "$ref": "#/components/schemas/workers_namespace_identifier" }, { "type": "string", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } ] }, "script_name": { "description": "The script where the Durable Object is defined, if it is external to this Worker.", "type": "string", "example": "my-other-worker", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "durable_object_namespace" ], "x-auditable": true } }, "required": [ "name", "type" ] }, "workers_binding_kind_flagship": { "type": "object", "properties": { "app_id": { "description": "ID of the Flagship app to bind to for feature flag evaluation.", "type": "string", "example": "app-12345678-1234-1234-1234-123456789012", "maxLength": 128, "x-auditable": true }, "name": { "$ref": "#/components/schemas/workers_binding_name" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "flagship" ], "x-auditable": true } }, "required": [ "name", "type", "app_id" ] }, "workers_binding_kind_hyperdrive": { "type": "object", "properties": { "id": { "description": "Identifier of the Hyperdrive connection to bind to.", "type": "string", "example": "57b7076f58be42419276f058a8968187", "x-auditable": true }, "name": { "$ref": "#/components/schemas/workers_binding_name" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "hyperdrive" ], "x-auditable": true } }, "required": [ "name", "type", "id" ] }, "workers_binding_kind_images": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "images" ], "x-auditable": true } }, "required": [ "name", "type" ] }, "workers_binding_kind_inherit": { "type": "object", "properties": { "name": { "description": "The name of the inherited binding.", "type": "string", "example": "MY_BINDING", "x-auditable": true }, "old_name": { "description": "The old name of the inherited binding. If set, the binding will be renamed from `old_name` to `name` in the new version. If not set, the binding will keep the same name between versions.", "type": "string", "example": "MY_OLD_BINDING", "x-auditable": true }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "inherit" ], "x-auditable": true }, "version_id": { "description": "Identifier for the version to inherit the binding from, which can be the version ID or the literal \"latest\" to inherit from the latest version. Defaults to inheriting the binding from the latest version.", "type": "string", "example": "8969331f-7192-434c-9938-6aea24ed58bf", "default": "latest", "x-auditable": true } }, "required": [ "name", "type" ] }, "workers_binding_kind_json": { "type": "object", "properties": { "json": { "description": "JSON data to use.", "type": "object", "x-stainless-any": true }, "name": { "$ref": "#/components/schemas/workers_binding_name" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "json" ], "x-auditable": true } }, "required": [ "name", "type", "json" ] }, "workers_binding_kind_kv_namespace": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "namespace_id": { "$ref": "#/components/schemas/workers_namespace_identifier" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "kv_namespace" ], "x-auditable": true } }, "required": [ "name", "type", "namespace_id" ] }, "workers_binding_kind_media": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "media" ], "x-auditable": true } }, "required": [ "name", "type" ] }, "workers_binding_kind_messaging": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "namespace": { "description": "The Messaging namespace to bind to.", "type": "string", "example": "production", "x-auditable": true }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "messaging" ], "x-auditable": true } }, "required": [ "name", "type", "namespace" ] }, "workers_binding_kind_mtls_certificate": { "type": "object", "properties": { "certificate_id": { "description": "Identifier of the certificate to bind to.", "type": "string", "example": "efwu2n6s-q69d-2kr9-184j-4913e8h391k6", "x-auditable": true }, "name": { "$ref": "#/components/schemas/workers_binding_name" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "mtls_certificate" ], "x-auditable": true } }, "required": [ "name", "type", "certificate_id" ] }, "workers_binding_kind_pipelines": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "pipeline": { "description": "Name of the Pipeline to bind to.", "type": "string", "example": "my-pipeline", "x-auditable": true }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "pipelines" ], "x-auditable": true } }, "required": [ "name", "type", "pipeline" ] }, "workers_binding_kind_plain_text": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "text": { "description": "The text value to use.", "type": "string", "example": "Hello, world!", "x-auditable": true }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "plain_text" ], "x-auditable": true } }, "required": [ "name", "type", "text" ] }, "workers_binding_kind_queue": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "queue_name": { "description": "Name of the Queue to bind to.", "type": "string", "example": "my-queue" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "queue" ], "x-auditable": true } }, "required": [ "name", "type", "queue_name" ] }, "workers_binding_kind_r2_bucket": { "type": "object", "properties": { "bucket_name": { "description": "R2 bucket to bind to.", "type": "string", "example": "my-r2-bucket", "x-auditable": true }, "jurisdiction": { "description": "The [jurisdiction](https://developers.cloudflare.com/r2/reference/data-location/#jurisdictional-restrictions) of the R2 bucket.", "type": "string", "example": "eu", "enum": [ "eu", "fedramp", "fedramp-high", "us" ], "x-auditable": true }, "name": { "$ref": "#/components/schemas/workers_binding_name" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "r2_bucket" ], "x-auditable": true } }, "required": [ "name", "type", "bucket_name" ] }, "workers_binding_kind_ratelimit": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "namespace_id": { "description": "Identifier of the rate limit namespace to bind to.", "type": "string", "example": "1234", "x-auditable": true }, "simple": { "description": "The rate limit configuration.", "type": "object", "properties": { "limit": { "description": "The limit (requests per period).", "type": "number", "example": 100, "x-auditable": true }, "mitigation_timeout": { "description": "Duration in seconds to apply the mitigation action after the rate limit is exceeded. Valid values are 0 (disabled), 10, or multiples of 60 up to 86400. Must be greater than or equal to the period when non-zero.\n", "type": "integer", "example": 60, "x-auditable": true }, "period": { "description": "The period in seconds.", "type": "integer", "example": 60, "x-auditable": true } }, "required": [ "limit", "period" ] }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "ratelimit" ], "x-auditable": true } }, "required": [ "name", "type", "namespace_id", "simple" ] }, "workers_binding_kind_secret_key": { "type": "object", "properties": { "algorithm": { "description": "Algorithm-specific key parameters. [Learn more](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey#algorithm).", "type": "object", "x-auditable": true }, "format": { "description": "Data format of the key. [Learn more](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey#format).", "type": "string", "example": "raw", "enum": [ "raw", "pkcs8", "spki", "jwk" ], "x-auditable": true }, "key_base64": { "description": "Base64-encoded key data. Required if `format` is \"raw\", \"pkcs8\", or \"spki\".", "type": "string", "writeOnly": true, "x-sensitive": true }, "key_jwk": { "description": "Key data in [JSON Web Key](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey#json_web_key) format. Required if `format` is \"jwk\".", "type": "object", "writeOnly": true, "x-sensitive": true }, "name": { "$ref": "#/components/schemas/workers_binding_name" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "secret_key" ], "x-auditable": true }, "usages": { "description": "Allowed operations with the key. [Learn more](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey#keyUsages).", "type": "array", "items": { "enum": [ "encrypt", "decrypt", "sign", "verify", "deriveKey", "deriveBits", "wrapKey", "unwrapKey" ], "type": "string" }, "example": [ "encrypt", "decrypt" ], "x-auditable": true, "x-stainless-collection-type": "set" } }, "required": [ "name", "type", "format", "algorithm", "usages" ] }, "workers_binding_kind_secret_text": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "text": { "description": "The secret value to use.", "type": "string", "example": "My secret.", "writeOnly": true, "x-sensitive": true }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "secret_text" ], "x-auditable": true } }, "required": [ "name", "type", "text" ] }, "workers_binding_kind_secrets_store_secret": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "secret_name": { "description": "Name of the secret in the store.", "type": "string", "example": "my_secret", "x-auditable": true }, "store_id": { "description": "ID of the store containing the secret.", "type": "string", "example": "8c8b1387108e49be85669169793e7bd2", "x-auditable": true }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "secrets_store_secret" ], "x-auditable": true } }, "required": [ "name", "type", "store_id", "secret_name" ] }, "workers_binding_kind_send_email": { "type": "object", "properties": { "allowed_destination_addresses": { "description": "List of allowed destination addresses.", "type": "array", "items": { "format": "email", "type": "string" }, "example": [ "user1@example.com", "user2@example.com" ], "x-auditable": true }, "allowed_sender_addresses": { "description": "List of allowed sender addresses.", "type": "array", "items": { "format": "email", "type": "string" }, "example": [ "user1@example.com", "user2@example.com" ], "x-auditable": true }, "destination_address": { "description": "Destination address for the email.", "type": "string", "format": "email", "example": "user@example.com", "x-auditable": true }, "name": { "$ref": "#/components/schemas/workers_binding_name" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "send_email" ], "x-auditable": true } }, "required": [ "name", "type" ] }, "workers_binding_kind_service": { "type": "object", "properties": { "entrypoint": { "description": "Entrypoint to invoke on the target Worker.", "type": "string", "example": "MyHandler", "x-auditable": true }, "environment": { "description": "Optional environment if the Worker utilizes one.", "type": "string", "example": "production", "default": "production", "x-auditable": true }, "name": { "$ref": "#/components/schemas/workers_binding_name" }, "service": { "description": "Name of Worker to bind to.", "type": "string", "example": "my-worker", "x-auditable": true }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "service" ], "x-auditable": true } }, "required": [ "name", "type", "service" ] }, "workers_binding_kind_text_blob": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "part": { "description": "The name of the file containing the text content. Only accepted for `service worker syntax` Workers.", "type": "string", "example": "my-module.txt", "x-auditable": true }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "text_blob" ], "deprecated": true, "x-auditable": true } }, "required": [ "name", "type", "part" ] }, "workers_binding_kind_vectorize": { "type": "object", "properties": { "index_name": { "description": "Name of the Vectorize index to bind to.", "type": "string", "example": "my-index-name", "x-auditable": true }, "name": { "$ref": "#/components/schemas/workers_binding_name" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "vectorize" ], "x-auditable": true } }, "required": [ "name", "type", "index_name" ] }, "workers_binding_kind_version_metadata": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "version_metadata" ], "x-auditable": true } }, "required": [ "name", "type" ] }, "workers_binding_kind_vpc_network": { "type": "object", "properties": { "identity": { "description": "Enables Gateway identity for the binding. Requires network_id to be \"cf1:network\" and cannot be combined with tunnel_id.\n", "type": "string", "enum": [ "runtime-email-alpha" ], "x-auditable": true }, "name": { "$ref": "#/components/schemas/workers_binding_name" }, "network_id": { "description": "Identifier of the network to bind to. Only \"cf1:network\" is currently supported. Mutually exclusive with tunnel_id.\n", "type": "string", "example": "cf1:network", "x-auditable": true }, "tunnel_id": { "description": "UUID of the Cloudflare Tunnel to bind to. Mutually exclusive with network_id.\n", "type": "string", "example": "abcd1234-5678-90ef-ghij-klmnopqrstuv", "x-auditable": true }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "vpc_network" ], "x-auditable": true } }, "required": [ "name", "type" ] }, "workers_binding_kind_vpc_service": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "service_id": { "description": "Identifier of the VPC service to bind to.", "type": "string", "example": "8c8b1387108e49be85669169793e7bd2", "x-auditable": true }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "vpc_service" ], "x-auditable": true } }, "required": [ "name", "type", "service_id" ] }, "workers_binding_kind_wasm_module": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/workers_binding_name" }, "part": { "description": "The name of the file containing the WebAssembly module content. Only accepted for `service worker syntax` Workers.", "type": "string", "example": "my-module.wasm", "x-auditable": true }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "wasm_module" ], "deprecated": true, "x-auditable": true } }, "required": [ "name", "type", "part" ] }, "workers_binding_kind_workflow": { "type": "object", "properties": { "class_name": { "description": "Class name of the Workflow. Should only be provided if the Workflow belongs to this script.", "type": "string", "example": "my-workflow" }, "name": { "$ref": "#/components/schemas/workers_binding_name" }, "script_name": { "description": "Script name that contains the Workflow. If not provided, defaults to this script name.", "type": "string", "example": "my-workflow", "x-auditable": true }, "type": { "description": "The kind of resource that the binding provides.", "type": "string", "enum": [ "workflow" ] }, "workflow_name": { "description": "Name of the Workflow to bind to.", "type": "string", "example": "my-workflow" } }, "required": [ "name", "type", "workflow_name" ] }, "workers_binding_name": { "description": "A JavaScript variable name for the binding.", "type": "string", "example": "myBinding", "x-auditable": true }, "workers_bindings": { "description": "List of bindings attached to a Worker. You can find more about bindings on our docs: https://developers.cloudflare.com/workers/configuration/multipart-upload-metadata/#bindings.", "type": "array", "items": { "$ref": "#/components/schemas/workers_binding_item" }, "example": [ { "name": "MY_ENV_VAR", "text": "my_data", "type": "plain_text" } ] }, "workers_cache_options": { "description": "Global CacheW configuration for the Worker. When caching is on,\nthe platform provisions a `cloudflare.app` zone for the Worker.\nA `type: worker` entry in the `exports` map can override this\nvalue for a single entrypoint.\n", "type": "object", "properties": { "cross_version_cache": { "description": "Whether cached responses are shared across Worker version\nuploads. This is independent of `enabled`. It can stay true\nwhile caching is off, so the preference survives turning\ncaching off and back on.\n", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "enabled": { "description": "Whether caching is enabled for this Worker.", "type": "boolean", "example": true, "default": false, "x-auditable": true } }, "additionalProperties": false, "required": [ "enabled" ] }, "workers_compatibility_date": { "description": "Date indicating targeted support in the Workers runtime. Backwards incompatible fixes to the runtime following this date will not affect this Worker.", "type": "string", "example": "2021-01-01T00:00:00Z", "x-auditable": true }, "workers_compatibility_flag": { "description": "Flag that enables or disables a specific feature in the Workers runtime.", "type": "string", "example": "nodejs_compat", "x-auditable": true }, "workers_compatibility_flags": { "description": "Flags that enable or disable certain features in the Workers runtime. Used to enable upcoming features or opt in or out of specific changes not included in a `compatibility_date`.", "type": "array", "items": { "$ref": "#/components/schemas/workers_compatibility_flag" }, "example": [ "nodejs_compat" ], "default": [], "x-stainless-collection-type": "set" }, "workers_completed-upload-assets-response": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "jwt": { "description": "A \"completion\" JWT which can be redeemed when creating a Worker version.", "type": "string", "x-sensitive": true } } } }, "type": "object" } ] }, "workers_container_item": { "description": "Container configuration for a Worker.", "type": "object", "properties": { "class_name": { "description": "Select which Durable Object class should get this container attached.", "type": "string", "x-auditable": true } }, "required": [ "class_name" ] }, "workers_containers": { "description": "List of containers attached to a Worker. Containers can only be attached to Durable Object classes of this Worker script.", "type": "array", "items": { "$ref": "#/components/schemas/workers_container_item" }, "example": [ { "class_name": "MyDurableObject" } ], "x-stainless-collection-type": "set" }, "workers_create-assets-upload-session-object": { "type": "object", "properties": { "manifest": { "description": "A manifest ([path]: {hash, size}) map of files to upload. As an example, `/blog/hello-world.html` would be a valid path key.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/workers_manifest-value" } } }, "required": [ "manifest" ] }, "workers_create-assets-upload-session-response": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "buckets": { "description": "The requests to make to upload assets.", "type": "array", "items": { "description": "The set of assets to include in each request while uploading.", "items": { "description": "The file hash to include in this bucket.", "type": "string" }, "type": "array", "x-stainless-collection-type": "set" }, "x-stainless-collection-type": "set" }, "jwt": { "description": "A JWT to use as authentication for uploading assets.", "type": "string", "x-sensitive": true } } } }, "type": "object" } ] }, "workers_created_on": { "description": "When the script was created.", "type": "string", "format": "date-time", "example": "2017-01-01T00:00:00Z", "readOnly": true, "x-auditable": true }, "workers_cursor": { "description": "Opaque token indicating the position from which to continue when requesting the next set of records. A valid value for the cursor can be obtained from the cursors object in the result_info structure.", "type": "string", "example": "AAAAANuhDN7SjacTnSVsDu3WW1Lvst6dxJGTjRY5BhxPXdf6L6uTcpd_NVtjhn11OUYRsVEykxoUwF-JQU4dn6QylZSKTOJuG0indrdn_MlHpMRtsxgXjs-RPdHYIVm3odE_uvEQ_dTQGFm8oikZMohns34DLBgrQpc" }, "workers_deployment": { "type": "object", "properties": { "annotations": { "type": "object", "properties": { "workers/message": { "description": "Human-readable message about the deployment. Truncated to 1000 bytes if longer.", "type": "string", "example": "Deploy bug fix.", "maxLength": 1000, "x-auditable": true }, "workers/triggered_by": { "description": "Operation that triggered the creation of the deployment.", "type": "string", "example": "deployment", "readOnly": true } } }, "author_email": { "type": "string", "format": "email", "readOnly": true, "x-auditable": true }, "created_on": { "type": "string", "format": "date-time", "readOnly": true, "x-auditable": true }, "id": { "type": "string", "format": "uuid", "readOnly": true, "x-auditable": true }, "source": { "type": "string", "example": "api", "readOnly": true, "x-auditable": true }, "strategy": { "type": "string", "enum": [ "percentage" ], "x-auditable": true }, "versions": { "type": "array", "items": { "properties": { "percentage": { "type": "number", "example": 100, "maximum": 100, "minimum": 0.01, "x-auditable": true }, "version_id": { "type": "string", "format": "uuid", "x-auditable": true } }, "required": [ "version_id", "percentage" ], "type": "object" }, "x-auditable": true } }, "required": [ "id", "source", "strategy", "versions", "created_on" ] }, "workers_dispatch_namespace_name": { "description": "Name of the Workers for Platforms dispatch namespace.", "type": "string", "example": "my-dispatch-namespace", "pattern": "^.+$", "x-auditable": true }, "workers_durable_object_deleted_export": { "description": "A `deleted` tombstone: retires the provisioned namespace for this\nclass and all of its data. The class must be absent from the\nuploaded code and no other Worker in the account may bind to the\nnamespace, otherwise the deploy is rejected. No other fields are\nallowed. Deletion is irreversible.\n", "type": "object", "properties": { "state": { "description": "Tombstone that deletes the namespace.", "type": "string", "enum": [ "deleted" ] }, "type": { "description": "Marks this entry as a Durable Object export.", "type": "string", "enum": [ "durable-object" ] } }, "additionalProperties": false, "required": [ "type", "state" ] }, "workers_durable_object_expecting_transfer_export": { "description": "The target side of a two-phase transfer (`state:\nexpecting-transfer`). Declares that this script expects to receive\na namespace for this class from the `transfer_from` script. This\nis a live entry, not a tombstone: bindings resolve through the\nsource's namespace until the source commits with a `transferred`\ntombstone. `storage` and `transfer_from` are required; `renamed_to`\nand `transferred_to` are not allowed.\n", "type": "object", "properties": { "container": { "description": "Name of the container (declared in the upload's\n`metadata.containers`) that backs this Durable Object once the\ntransfer settles. Valid only on live entries.\n", "type": "string", "example": "my-container", "maxLength": 128 }, "state": { "description": "Target side of a two-phase transfer.", "type": "string", "enum": [ "expecting-transfer" ] }, "storage": { "$ref": "#/components/schemas/workers_export_storage" }, "transfer_from": { "description": "The source script name to receive the namespace from. Must be\nin the same account and dispatch-namespace context. Present on\nreads for `expecting-transfer` entries.\n", "type": "string", "example": "source-worker", "maxLength": 128 }, "type": { "description": "Marks this entry as a Durable Object export.", "type": "string", "enum": [ "durable-object" ] } }, "additionalProperties": false, "required": [ "type", "state", "storage", "transfer_from" ] }, "workers_durable_object_export": { "description": "A live Durable Object export (`state: created`, the default). The\nplatform auto-provisions the namespace on first deploy, matches it\non subsequent deploys, and never mutates or deletes it as a side\neffect of a code-only change. `storage` is required; `renamed_to`,\n`transferred_to` and `transfer_from` are not allowed on a live\nentry.\n", "type": "object", "properties": { "container": { "description": "Name of the container (declared in the upload's\n`metadata.containers`) that backs this Durable Object. When\nset, the namespace is container-enabled. Valid only on live\nentries.\n", "type": "string", "example": "my-container", "maxLength": 128 }, "state": { "description": "Live export. May be omitted; defaults to `created`.", "type": "string", "default": "created", "enum": [ "created" ] }, "storage": { "$ref": "#/components/schemas/workers_export_storage" }, "type": { "description": "Marks this entry as a Durable Object export.", "type": "string", "enum": [ "durable-object" ] } }, "additionalProperties": false, "required": [ "type", "storage" ] }, "workers_durable_object_export_variants": { "description": "Any Durable Object export entry (`type: durable-object`), across\nall lifecycle states. The optional `state` field selects the\nvariant (default `created`); the tombstone states (`deleted`,\n`renamed`, `transferred`) and the live transfer target\n(`expecting-transfer`) are the alternatives. The server validates\nthe exact per-state field combinations; fields not listed for a\nvariant are rejected.\n", "oneOf": [ { "$ref": "#/components/schemas/workers_durable_object_export" }, { "$ref": "#/components/schemas/workers_durable_object_deleted_export" }, { "$ref": "#/components/schemas/workers_durable_object_renamed_export" }, { "$ref": "#/components/schemas/workers_durable_object_transferred_export" }, { "$ref": "#/components/schemas/workers_durable_object_expecting_transfer_export" } ] }, "workers_durable_object_renamed_export": { "description": "A `renamed` tombstone: rewrites the provisioned namespace's class\nname from this map key to `renamed_to`. The source class may stay\nin code during the rollout window (an info notice is emitted).\n`storage`, `transferred_to` and `transfer_from` are not allowed.\n", "type": "object", "properties": { "renamed_to": { "description": "The destination class name. Must differ from the source class\n(the map key) and must be declared as a live (`created`) entry\nin the same `exports` map. Write-only: never present in GET\nresponses.\n", "type": "string", "example": "NewName", "maxLength": 128, "writeOnly": true }, "state": { "description": "Tombstone that renames the namespace's class.", "type": "string", "enum": [ "renamed" ] }, "type": { "description": "Marks this entry as a Durable Object export.", "type": "string", "enum": [ "durable-object" ] } }, "additionalProperties": false, "required": [ "type", "state", "renamed_to" ] }, "workers_durable_object_transferred_export": { "description": "A `transferred` tombstone (source side of a two-phase transfer):\nhands ownership of the provisioned namespace to another script in\nthe same account, named by `transferred_to`. The target must have\nalready deployed a matching `expecting-transfer` entry. The source\nclass may stay in code during the rollout window (an info notice\nis emitted). `storage`, `renamed_to` and `transfer_from` are not\nallowed.\n", "type": "object", "properties": { "state": { "description": "Tombstone that transfers the namespace to another script.", "type": "string", "enum": [ "transferred" ] }, "transferred_to": { "description": "The destination script name. Must be in the same account and\nthe same dispatch-namespace context (or both non-dispatch).\nCross-dispatch-namespace transfers are rejected. Write-only:\nnever present in GET responses.\n", "type": "string", "example": "target-worker", "maxLength": 128, "writeOnly": true }, "type": { "description": "Marks this entry as a Durable Object export.", "type": "string", "enum": [ "durable-object" ] } }, "additionalProperties": false, "required": [ "type", "state", "transferred_to" ] }, "workers_entrypoint_cache_options": { "description": "CacheW configuration for a single `type: worker` entrypoint.\nWhen present it overrides the Worker's global\n`cache_options.enabled` for that entrypoint, so a Worker can turn\ncaching on globally and opt one entrypoint out, or the reverse.\n", "type": "object", "properties": { "enabled": { "description": "Whether caching is enabled for this entrypoint.", "type": "boolean", "example": true, "x-auditable": true } }, "additionalProperties": false, "required": [ "enabled" ] }, "workers_environment": { "description": "Optional environment if the Worker utilizes one.", "type": "string", "example": "production", "x-auditable": true }, "workers_etag": { "description": "Hashed script content, can be used in a If-None-Match header when updating.", "type": "string", "example": "ea95132c15732412d22c1476fa83f27a", "readOnly": true }, "workers_export_config": { "description": "A single entry in the `exports` map, keyed by export name (a\n`WorkerEntrypoint` class name, a Durable Object class name, or\n`default` for the Worker's default export). The `type`\ndiscriminator selects the top-level shape: `worker` entrypoint\nentries may carry `cache` configuration, while `durable-object`\nentries are further refined by the optional `state` field\n(default `created`). Tombstone states (`deleted`, `renamed`,\n`transferred`) express destructive lifecycle operations\ndeclaratively; `expecting-transfer` is the live target side of a\ntransfer. The server validates the exact per-(type, state) field\ncombinations; fields not listed for a variant are rejected.\n", "discriminator": { "mapping": { "durable-object": "#/components/schemas/workers_durable_object_export_variants", "worker": "#/components/schemas/workers_worker_export" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/workers_worker_export" }, { "$ref": "#/components/schemas/workers_durable_object_export_variants" } ] }, "workers_export_storage": { "description": "Durable Object storage backend. `sqlite` is the recommended (and\nonly) backend for new namespaces. `legacy-kv` is accepted only for\na class whose namespace already exists as KV-backed; the `exports`\nflow never provisions a new `legacy-kv` namespace.\n", "type": "string", "enum": [ "sqlite", "legacy-kv" ] }, "workers_exports_config_map": { "description": "Declarative exports for the Worker, keyed by export name. Worker\nentrypoint entries (`type: worker`) carry cache configuration for\nthat entrypoint. Durable Object entries (`type: durable-object`)\nare also configured here and drive namespace reconciliation. At\nmost 100 entries; class names are at most 128 characters.\n", "type": "object", "example": { "Admin": { "cache": { "enabled": true }, "type": "worker" }, "Counter": { "storage": "sqlite", "type": "durable-object" }, "OldCounter": { "renamed_to": "Counter", "state": "renamed", "type": "durable-object" }, "default": { "cache": { "enabled": false }, "type": "worker" } }, "additionalProperties": { "$ref": "#/components/schemas/workers_export_config" }, "maxProperties": 100 }, "workers_exports_reconciliation_error": { "description": "A single blocking reconciliation error. Returned in the v4 error\nenvelope under `meta.details` on the exports reconciliation\nfailure error (code 100402). All per-class failures are reported\ntogether, sorted by class name.\n", "type": "object", "properties": { "class": { "description": "The class name the error is about.", "type": "string" }, "message": { "description": "Human-readable explanation.", "type": "string" }, "namespace_id": { "description": "The provisioned namespace the error relates to, when applicable.", "type": "string", "format": "uuid" }, "referencing_scripts": { "description": "Other Workers in the account whose bindings block the\noperation (e.g. a `deleted` tombstone blocked by external\nbindings).\n", "type": "array", "items": { "type": "string" } }, "scenario": { "$ref": "#/components/schemas/workers_exports_reconciliation_scenario" }, "suggestion": { "description": "An actionable hint for resolving the error, when available.", "type": "string" } }, "required": [ "class", "scenario", "message" ] }, "workers_exports_reconciliation_error_response": { "description": "The v4 error envelope returned with HTTP 400 when one or more\ndeclared `exports` entries fail reconciliation (error code\n100402). The top-level error `message` aggregates the per-class\nfailures as human-readable prose; the structured per-class payload\nis carried in `errors[].meta.details`, sorted by class name.\n", "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "integer", "example": 100402, "enum": [ 100402 ] }, "message": { "description": "Aggregate, multi-line, human-readable summary of every\nper-class reconciliation failure.\n", "type": "string" }, "meta": { "type": "object", "properties": { "details": { "description": "Structured per-class reconciliation failures, sorted\nby class name.\n", "type": "array", "items": { "$ref": "#/components/schemas/workers_exports_reconciliation_error" } } }, "required": [ "details" ] } }, "required": [ "code", "message", "meta" ], "type": "object" } }, "messages": { "$ref": "#/components/schemas/workers_messages" }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "workers_exports_reconciliation_info": { "description": "A non-blocking reconciliation info entry. Emitted for stale\ntombstones (a no-op on this deploy) and for tombstones applied\nwith the source class still in code (the supported zero-downtime\nrollout pattern).\n", "type": "object", "properties": { "class": { "description": "The class name the info entry is about.", "type": "string" }, "message": { "description": "Human-readable explanation.", "type": "string" }, "namespace_id": { "description": "The provisioned namespace the entry relates to, when applicable.", "type": "string", "format": "uuid" }, "referencing_scripts": { "description": "Other Workers in the account that still bind to the affected\nclass. Advisory: while non-empty the tombstone is not yet safe\nto remove — redeploy these Workers with bindings re-pointed\nfirst.\n", "type": "array", "items": { "type": "string" } }, "scenario": { "$ref": "#/components/schemas/workers_exports_reconciliation_scenario" } }, "required": [ "class", "scenario", "message" ] }, "workers_exports_reconciliation_rename": { "description": "A single applied `renamed` tombstone.", "type": "object", "properties": { "from": { "description": "The original (source) class name.", "type": "string" }, "to": { "description": "The new class name (`renamed_to`).", "type": "string" } }, "required": [ "from", "to" ] }, "workers_exports_reconciliation_result": { "description": "Summary of what the declarative exports reconciliation did on this\nupload. Present only on uploads that included an `exports` block.\nReconciliation acts on Durable Object entries; `type: worker`\nentries in the same map do not participate. Every array is always\npresent (possibly empty) so clients can iterate unconditionally.\nClients should surface `warnings` prominently, render `info` at\nlower visibility, and use `removable_entries` as the \"safe to\ndelete from your config\" hint.\n", "type": "object", "properties": { "created": { "description": "Class names for which a new namespace was provisioned.", "type": "array", "items": { "type": "string" } }, "deleted": { "description": "Class names whose namespace was deleted by a `deleted` tombstone.", "type": "array", "items": { "type": "string" } }, "info": { "description": "Non-blocking info entries (stale tombstones, tombstone applied\nwith class still in code). See `exports_reconciliation_info`.\n", "type": "array", "items": { "$ref": "#/components/schemas/workers_exports_reconciliation_info" } }, "removable_entries": { "description": "Source class names whose tombstone entry is now stale and safe\nto delete from `exports` (no remaining referencing scripts).\n", "type": "array", "items": { "type": "string" } }, "renamed": { "description": "Applied `renamed` tombstones.", "type": "array", "items": { "$ref": "#/components/schemas/workers_exports_reconciliation_rename" } }, "transfer_pending": { "description": "Phase-1 transfer hints recorded on the target side.", "type": "array", "items": { "$ref": "#/components/schemas/workers_exports_reconciliation_transfer_pending" } }, "transferred": { "description": "Committed `transferred` tombstones (phase-2).", "type": "array", "items": { "$ref": "#/components/schemas/workers_exports_reconciliation_transfer" } }, "updated": { "description": "Class names whose provisioned namespace was mutated in place.", "type": "array", "items": { "type": "string" } }, "warnings": { "description": "Non-blocking warnings. See `exports_reconciliation_warning`.", "type": "array", "items": { "$ref": "#/components/schemas/workers_exports_reconciliation_warning" } } }, "readOnly": true, "required": [ "created", "updated", "deleted", "renamed", "transferred", "transfer_pending", "warnings", "info", "removable_entries" ] }, "workers_exports_reconciliation_scenario": { "description": "Stable, machine-readable tag identifying which reconciliation\nscenario produced an error, warning, or info entry. Clients may\nbranch on this value instead of parsing `message`.\n", "type": "string", "enum": [ "code_class_not_in_exports", "provisioned_class_missing_from_config", "config_export_not_in_code", "config_references_nonexistent_class", "orphaned_provisioned_namespace", "storage_type_mismatch", "free_tier_requires_sqlite", "invalid_export", "tombstone_delete_class_still_in_code", "tombstone_delete_blocked_by_external_bindings", "tombstone_renamed_to_occupied", "transferred_pending_not_found", "transferred_target_missing", "transferred_target_mismatch", "phase_one_transfer_source_missing", "phase_one_transfer_source_namespace_missing", "phase_one_transfer_target_class_provisioned", "phase_one_transfer_after_commit_mismatch", "phase_one_transfer_duplicate", "phase_one_transfer_target_in_dispatch_namespace", "phase_one_transfer_source_in_dispatch_namespace", "transferred_source_in_dispatch_namespace", "transferred_target_in_dispatch_namespace", "container_undeclared_reference", "container_class_not_durable_object", "container_wiring_inconsistent", "container_multiple_durable_objects", "transfer_container_parity_mismatch", "transfer_container_parity_mismatch_on_commit", "tombstone_class_still_in_code", "stale_tombstone", "transfer_receive_already_applied", "transfer_receive_cleanup_complete" ] }, "workers_exports_reconciliation_transfer": { "description": "A single committed `transferred` tombstone (phase-2 commit).", "type": "object", "properties": { "class": { "description": "The source class name that was transferred.", "type": "string" }, "phase": { "description": "The transfer phase. Currently always `committed`.", "type": "string", "example": "committed", "enum": [ "committed" ] }, "to": { "description": "The destination script that now owns the namespace.", "type": "string" } }, "required": [ "class", "to", "phase" ] }, "workers_exports_reconciliation_transfer_pending": { "description": "A single phase-1 transfer hint recorded on the target side (a live\n`expecting-transfer` entry).\n", "type": "object", "properties": { "class": { "description": "The target-side class name awaiting transfer.", "type": "string" }, "from": { "description": "The source script the namespace will be transferred from.", "type": "string" } }, "required": [ "class", "from" ] }, "workers_exports_reconciliation_warning": { "description": "A non-blocking reconciliation warning. Reserved: no scenario\npopulates this array today (`code_class_not_in_exports` is\nsurfaced as info and `provisioned_class_missing_from_config` is a\nhard error). Clients should still surface any entries that appear.\n", "type": "object", "properties": { "class": { "description": "The class name the warning is about.", "type": "string" }, "message": { "description": "Human-readable explanation of the warning.", "type": "string" }, "namespace_id": { "description": "The provisioned namespace the warning relates to, when applicable.", "type": "string", "format": "uuid" }, "scenario": { "$ref": "#/components/schemas/workers_exports_reconciliation_scenario" } }, "required": [ "class", "scenario", "message" ] }, "workers_has_assets": { "description": "Whether a Worker contains assets.", "type": "boolean", "example": false, "x-auditable": true }, "workers_has_modules": { "description": "Whether a Worker contains modules.", "type": "boolean", "example": false, "x-auditable": true }, "workers_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "workers_limits": { "description": "Limits to apply for this Worker.", "type": "object", "properties": { "cpu_ms": { "description": "The amount of CPU time this Worker can use in milliseconds.", "type": "integer", "example": 50, "x-auditable": true }, "subrequests": { "description": "The number of subrequests this Worker can make per request.", "type": "integer", "example": 1000, "x-auditable": true } } }, "workers_logpush": { "description": "Whether Logpush is turned on for the Worker.", "type": "boolean", "example": false, "default": false, "x-auditable": true }, "workers_manifest-value": { "type": "object", "properties": { "hash": { "description": "The hash of the file.", "type": "string" }, "size": { "description": "The size of the file in bytes.", "type": "integer" } }, "required": [ "hash", "size" ] }, "workers_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "workers_migration_step": { "type": "object", "properties": { "deleted_classes": { "description": "A list of classes to delete Durable Object namespaces from.", "type": "array", "items": { "type": "string", "x-auditable": true }, "writeOnly": true }, "new_classes": { "description": "A list of classes to create Durable Object namespaces from.", "type": "array", "items": { "type": "string", "x-auditable": true }, "writeOnly": true }, "new_sqlite_classes": { "description": "A list of classes to create Durable Object namespaces with SQLite from.", "type": "array", "items": { "type": "string", "x-auditable": true }, "writeOnly": true }, "renamed_classes": { "description": "A list of classes with Durable Object namespaces that were renamed.", "type": "array", "items": { "properties": { "from": { "type": "string", "writeOnly": true, "x-auditable": true }, "to": { "type": "string", "writeOnly": true, "x-auditable": true } }, "type": "object" }, "writeOnly": true }, "transferred_classes": { "description": "A list of transfers for Durable Object namespaces from a different Worker and class to a class defined in this Worker.", "type": "array", "items": { "properties": { "from": { "type": "string", "writeOnly": true, "x-auditable": true }, "from_script": { "type": "string", "writeOnly": true, "x-auditable": true }, "to": { "type": "string", "writeOnly": true, "x-auditable": true } }, "type": "object" }, "writeOnly": true } } }, "workers_migration_tag_conditions": { "type": "object", "properties": { "new_tag": { "description": "Tag to set as the latest migration tag.", "type": "string", "example": "v2", "writeOnly": true, "x-auditable": true }, "old_tag": { "description": "Tag used to verify against the latest migration tag for this Worker. If they don't match, the upload is rejected.", "type": "string", "example": "v1", "writeOnly": true, "x-auditable": true } } }, "workers_modified_on": { "description": "When the script was last modified.", "type": "string", "format": "date-time", "example": "2017-01-01T00:00:00Z", "readOnly": true, "x-auditable": true }, "workers_multipart-script": { "type": "object", "properties": { "files": { "description": "An array of modules (often JavaScript files) comprising a Worker script. At least one module must be present and referenced in the metadata as `main_module` or `body_part` by filename.
Possible Content-Type(s) are: `application/javascript+module`, `text/javascript+module`, `application/javascript`, `text/javascript`, `text/x-python`, `text/x-python-requirement`, `application/wasm`, `text/plain`, `application/octet-stream`, `application/source-map`.", "type": "array", "items": { "format": "binary", "type": "string" }, "x-stainless-collection-type": "set" }, "metadata": { "description": "JSON-encoded metadata about the uploaded parts and Worker configuration.", "type": "object", "properties": { "assets": { "$ref": "#/components/schemas/workers_assets" }, "bindings": { "$ref": "#/components/schemas/workers_bindings" }, "body_part": { "description": "Name of the uploaded file that contains the script (e.g. the file adding a listener to the `fetch` event). Indicates a `service worker syntax` Worker.", "type": "string", "example": "worker.js" }, "cache_options": { "$ref": "#/components/schemas/workers_cache_options" }, "compatibility_date": { "$ref": "#/components/schemas/workers_compatibility_date" }, "compatibility_flags": { "$ref": "#/components/schemas/workers_compatibility_flags" }, "exports": { "description": "Declarative exports for the Worker. Worker entrypoint\nentries (`type: worker`) carry cache configuration for\nthat entrypoint.\n", "allOf": [ { "$ref": "#/components/schemas/workers_exports_config_map" } ], "writeOnly": true }, "exports_reconciliation": { "description": "Summary of the declarative exports reconciliation that ran\non this upload. Populated only when the uploaded metadata\nincluded an `exports` block. Durable Object entries drive\nreconciliation; `type: worker` entries do not contribute to\nthis summary.\n", "allOf": [ { "$ref": "#/components/schemas/workers_exports_reconciliation_result" } ] }, "keep_assets": { "description": "Retain assets which exist for a previously uploaded Worker version; used in lieu of providing a completion token. An explicit `assets` upload takes precedence over `keep_assets`.", "type": "boolean", "example": false }, "keep_bindings": { "description": "List of binding types to keep from previous_upload.", "type": "array", "items": { "type": "string" }, "x-stainless-collection-type": "set" }, "limits": { "$ref": "#/components/schemas/workers_limits" }, "logpush": { "$ref": "#/components/schemas/workers_logpush" }, "main_module": { "description": "Name of the uploaded file that contains the main module (e.g. the file exporting a `fetch` handler). Indicates a `module syntax` Worker.", "type": "string", "example": "worker.js" }, "migrations": { "description": "Migrations to apply for Durable Objects associated with this Worker.", "oneOf": [ { "$ref": "#/components/schemas/workers_single_step_migrations" }, { "$ref": "#/components/schemas/workers_multiple_step_migrations" } ], "writeOnly": true }, "observability": { "$ref": "#/components/schemas/workers_observability" }, "package_dependencies": { "description": "The list of npm packages that were installed and used when this Worker\nversion was built.\n", "type": "array", "items": { "properties": { "installedVersion": { "description": "The exact version that was resolved and installed by the package manager.", "type": "string", "example": "4.17.22" }, "name": { "description": "The npm package name.", "type": "string", "example": "lodash" }, "packageJsonVersion": { "description": "The version constraint as written in package.json.", "type": "string", "example": "^4.17.21" } }, "required": [ "name", "packageJsonVersion", "installedVersion" ], "type": "object" }, "x-auditable": true }, "placement": { "$ref": "#/components/schemas/workers_placement_info" }, "tags": { "description": "List of strings to use as tags for this Worker.", "type": "array", "items": { "type": "string" }, "x-stainless-collection-type": "set" }, "tail_consumers": { "$ref": "#/components/schemas/workers_tail_consumers" }, "usage_model": { "$ref": "#/components/schemas/workers_usage_model" } } } }, "example": { "files": [ "export default {\n async fetch(request, env, ctx) {\n return new Response(\"Hello, world!\");\n }\n};" ], "metadata": { "compatibility_date": {}, "compatibility_flags": [ "nodejs_compat" ], "main_module": "worker.js" } }, "required": [ "metadata" ] }, "workers_multiple_step_migrations": { "allOf": [ { "$ref": "#/components/schemas/workers_migration_tag_conditions" }, { "properties": { "steps": { "description": "Migrations to apply in order.", "type": "array", "items": { "$ref": "#/components/schemas/workers_migration_step" }, "writeOnly": true } }, "type": "object" } ] }, "workers_namespace": { "type": "object", "properties": { "class": { "type": "string" }, "id": { "type": "string", "readOnly": true }, "name": { "type": "string" }, "script": { "type": "string" }, "use_sqlite": { "type": "boolean" } } }, "workers_namespace-list-response": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/workers_namespace-response" } } }, "type": "object" } ] }, "workers_namespace-response": { "type": "object", "properties": { "created_by": { "$ref": "#/components/schemas/workers_identifier" }, "created_on": { "$ref": "#/components/schemas/workers_created_on" }, "modified_by": { "$ref": "#/components/schemas/workers_identifier" }, "modified_on": { "$ref": "#/components/schemas/workers_modified_on" }, "namespace_id": { "$ref": "#/components/schemas/workers_uuid" }, "namespace_name": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" }, "script_count": { "$ref": "#/components/schemas/workers_script_count" }, "trusted_workers": { "$ref": "#/components/schemas/workers_trusted_workers" } } }, "workers_namespace-script-and-version-settings-item": { "description": "Script and version settings for Workers for Platforms namespace scripts. Same as script-and-version-settings-item but without annotations, which are not supported for namespace scripts.\n", "type": "object", "properties": { "bindings": { "allOf": [ { "$ref": "#/components/schemas/workers_bindings" }, { "default": [], "items": { "$ref": "#/components/schemas/workers_binding_item" }, "type": "array" } ] }, "cache_options": { "$ref": "#/components/schemas/workers_cache_options" }, "compatibility_date": { "allOf": [ { "$ref": "#/components/schemas/workers_compatibility_date" }, { "default": "", "type": "string", "x-auditable": true } ] }, "compatibility_flags": { "allOf": [ { "$ref": "#/components/schemas/workers_compatibility_flags" }, { "default": [], "items": { "type": "string", "x-auditable": true }, "type": "array", "x-stainless-collection-type": "set" } ] }, "exports": { "description": "Declarative exports for the Worker. Worker entrypoint entries\n(`type: worker`) carry cache configuration for that entrypoint.\n", "allOf": [ { "$ref": "#/components/schemas/workers_exports_config_map" } ], "writeOnly": true }, "exports_reconciliation": { "description": "Summary of the declarative exports reconciliation that ran on\nthis upload. Populated only when the uploaded metadata included\nan `exports` block. Durable Object entries drive reconciliation;\n`type: worker` entries do not contribute to this summary.\n", "allOf": [ { "$ref": "#/components/schemas/workers_exports_reconciliation_result" } ] }, "limits": { "$ref": "#/components/schemas/workers_limits" }, "logpush": { "$ref": "#/components/schemas/workers_logpush" }, "migrations": { "description": "Migrations to apply for Durable Objects associated with this Worker.\n", "oneOf": [ { "$ref": "#/components/schemas/workers_single_step_migrations" }, { "$ref": "#/components/schemas/workers_multiple_step_migrations" } ], "writeOnly": true }, "observability": { "$ref": "#/components/schemas/workers_observability" }, "placement": { "allOf": [ { "$ref": "#/components/schemas/workers_placement_info_no_status" }, { "default": {}, "type": "object" } ] }, "tags": { "allOf": [ { "$ref": "#/components/schemas/workers_tags" }, { "default": [], "items": { "type": "string", "x-auditable": true }, "type": "array", "x-stainless-collection-type": "set" } ] }, "tail_consumers": { "allOf": [ { "$ref": "#/components/schemas/workers_tail_consumers" }, { "default": [], "items": { "$ref": "#/components/schemas/workers_tail_consumers_script" }, "type": "array", "x-stainless-collection-type": "set" } ] }, "usage_model": { "$ref": "#/components/schemas/workers_usage_model" } } }, "workers_namespace-script-delete-bulk-response": { "description": "Detail about bulk deletion of scripts in a namespace.", "type": "object", "properties": { "deleted": { "type": "array", "items": { "properties": { "id": { "$ref": "#/components/schemas/workers_uuid" } }, "type": "object" } }, "deleted_count": { "type": "integer", "example": 100 }, "has_more": { "type": "boolean", "example": false } } }, "workers_namespace-script-response": { "description": "Details about a worker uploaded to a Workers for Platforms namespace.", "type": "object", "properties": { "created_on": { "$ref": "#/components/schemas/workers_created_on" }, "dispatch_namespace": { "$ref": "#/components/schemas/workers_dispatch_namespace_name" }, "modified_on": { "$ref": "#/components/schemas/workers_modified_on" }, "script": { "$ref": "#/components/schemas/workers_script-response" } } }, "workers_namespace-script-response-single": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_namespace-script-response" } }, "required": [ "result" ], "type": "object" } ] }, "workers_namespace-single-response": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_namespace-response" } }, "type": "object" } ] }, "workers_namespace_identifier": { "description": "Namespace identifier tag.", "type": "string", "example": "0f2ac74b498b48028cb68387c421e279", "maxLength": 32, "x-auditable": true }, "workers_object": { "type": "object", "properties": { "hasStoredData": { "description": "Whether the Durable Object has stored data.", "type": "boolean", "example": true, "readOnly": true }, "id": { "description": "ID of the Durable Object.", "type": "string", "example": "fe7803fc55b964e09d94666545aab688d360c6bda69ba349ced1e5f28d2fc2c8", "readOnly": true } } }, "workers_observability": { "description": "Observability settings for the Worker.", "type": "object", "properties": { "enabled": { "description": "Whether observability is enabled for the Worker.", "type": "boolean", "example": true, "x-auditable": true }, "head_sampling_rate": { "description": "The sampling rate for incoming requests. From 0 to 1 (1 = 100%, 0.1 = 10%). Default is 1.", "type": "number", "example": 0.1, "nullable": true, "x-auditable": true }, "logs": { "description": "Log settings for the Worker.", "type": "object", "nullable": true, "properties": { "destinations": { "description": "A list of destinations where logs will be exported to.", "type": "array", "items": { "type": "string" }, "example": [ "cloudflare" ], "x-auditable": true }, "enabled": { "description": "Whether logs are enabled for the Worker.", "type": "boolean", "example": true, "x-auditable": true }, "head_sampling_rate": { "description": "The sampling rate for logs. From 0 to 1 (1 = 100%, 0.1 = 10%). Default is 1.", "type": "number", "example": 0.1, "nullable": true, "x-auditable": true }, "invocation_logs": { "description": "Whether [invocation logs](https://developers.cloudflare.com/workers/observability/logs/workers-logs/#invocation-logs) are enabled for the Worker.", "type": "boolean", "example": true, "x-auditable": true }, "persist": { "description": "Whether log persistence is enabled for the Worker.", "type": "boolean", "example": true, "default": true, "x-auditable": true } }, "required": [ "enabled", "invocation_logs" ] }, "redact_query_string": { "description": "Whether query strings are removed from request URLs in logs and traces.", "type": "boolean", "example": false, "default": false, "x-auditable": true }, "traces": { "description": "Trace settings for the Worker.", "type": "object", "nullable": true, "properties": { "destinations": { "description": "A list of destinations where traces will be exported to.", "type": "array", "items": { "type": "string" }, "example": [ "cloudflare" ], "x-auditable": true }, "enabled": { "description": "Whether traces are enabled for the Worker.", "type": "boolean", "example": true, "x-auditable": true }, "head_sampling_rate": { "description": "The sampling rate for traces. From 0 to 1 (1 = 100%, 0.1 = 10%). Default is 1.", "type": "number", "example": 0.1, "nullable": true, "x-auditable": true }, "persist": { "description": "Whether trace persistence is enabled for the Worker.", "type": "boolean", "example": true, "default": true, "x-auditable": true }, "propagation_policy": { "description": "Controls how inbound trace context (traceparent/tracestate) headers on incoming requests are handled. \"authenticated\" honors inbound trace context only when accompanied by a valid trace auth token. \"accept\" unconditionally accepts inbound trace context. Requires the trace propagation feature to be enabled. Returns null when the trace propagation feature is not enabled for the account.", "type": "string", "enum": [ "authenticated", "accept", null ], "nullable": true, "x-auditable": true } } } }, "required": [ "enabled" ] }, "workers_placement-provider": { "type": "object", "properties": { "id": { "description": "The cloud provider identifier.", "type": "string", "example": "aws" }, "regions": { "description": "List of regions available for this provider.", "type": "array", "items": { "$ref": "#/components/schemas/workers_placement-region" } } }, "required": [ "id", "regions" ] }, "workers_placement-region": { "type": "object", "properties": { "id": { "description": "The region identifier.", "type": "string", "example": "us-east-1" } }, "required": [ "id" ] }, "workers_placement-regions-response": { "type": "object", "properties": { "providers": { "description": "List of cloud providers with their available regions.", "type": "array", "items": { "$ref": "#/components/schemas/workers_placement-provider" } } }, "required": [ "providers" ] }, "workers_placement_info": { "description": "Configuration for [Smart Placement](https://developers.cloudflare.com/workers/configuration/smart-placement). Specify mode='smart' for Smart Placement, or one of region/hostname/host.", "type": "object", "allOf": [ { "oneOf": [ { "properties": { "mode": { "description": "Enables [Smart Placement](https://developers.cloudflare.com/workers/configuration/smart-placement).", "type": "string", "enum": [ "smart" ], "x-auditable": true } }, "required": [ "mode" ], "type": "object" }, { "properties": { "region": { "description": "Cloud region for targeted placement in format 'provider:region'.", "type": "string", "example": "aws:us-east-1", "x-auditable": true } }, "required": [ "region" ], "type": "object" }, { "properties": { "hostname": { "description": "HTTP hostname for targeted placement.", "type": "string", "example": "api.example.com", "x-auditable": true } }, "required": [ "hostname" ], "type": "object" }, { "properties": { "host": { "description": "TCP host and port for targeted placement.", "type": "string", "example": "db.example.com:5432", "x-auditable": true } }, "required": [ "host" ], "type": "object" }, { "properties": { "mode": { "description": "Targeted placement mode.", "type": "string", "enum": [ "targeted" ], "x-auditable": true }, "region": { "description": "Cloud region for targeted placement in format 'provider:region'.", "type": "string", "example": "aws:us-east-1", "x-auditable": true } }, "required": [ "mode", "region" ], "type": "object" }, { "properties": { "hostname": { "description": "HTTP hostname for targeted placement.", "type": "string", "example": "api.example.com", "x-auditable": true }, "mode": { "description": "Targeted placement mode.", "type": "string", "enum": [ "targeted" ], "x-auditable": true } }, "required": [ "mode", "hostname" ], "type": "object" }, { "properties": { "host": { "description": "TCP host and port for targeted placement.", "type": "string", "example": "db.example.com:5432", "x-auditable": true }, "mode": { "description": "Targeted placement mode.", "type": "string", "enum": [ "targeted" ], "x-auditable": true } }, "required": [ "mode", "host" ], "type": "object" }, { "properties": { "mode": { "description": "Targeted placement mode.", "type": "string", "enum": [ "targeted" ], "x-auditable": true }, "target": { "description": "Array of placement targets (currently limited to single target).", "type": "array", "items": { "$ref": "#/components/schemas/workers_placement_target" }, "maxItems": 1, "minItems": 1, "x-auditable": true } }, "required": [ "mode", "target" ], "type": "object" } ] }, { "properties": { "last_analyzed_at": { "description": "The last time the script was analyzed for [Smart Placement](https://developers.cloudflare.com/workers/configuration/smart-placement).", "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00Z", "readOnly": true }, "status": { "$ref": "#/components/schemas/workers_placement_status" } }, "type": "object" } ] }, "workers_placement_info_no_status": { "description": "Configuration for [Smart Placement](https://developers.cloudflare.com/workers/configuration/smart-placement). Specify mode='smart' for Smart Placement, or one of region/hostname/host.", "type": "object", "oneOf": [ { "additionalProperties": false, "properties": { "mode": { "description": "Enables [Smart Placement](https://developers.cloudflare.com/workers/configuration/smart-placement).", "type": "string", "enum": [ "smart" ], "x-auditable": true } }, "required": [ "mode" ], "type": "object" }, { "additionalProperties": false, "properties": { "region": { "description": "Cloud region for targeted placement in format 'provider:region'.", "type": "string", "example": "aws:us-east-1", "x-auditable": true } }, "required": [ "region" ], "type": "object" }, { "additionalProperties": false, "properties": { "hostname": { "description": "HTTP hostname for targeted placement.", "type": "string", "example": "api.example.com", "x-auditable": true } }, "required": [ "hostname" ], "type": "object" }, { "additionalProperties": false, "properties": { "host": { "description": "TCP host and port for targeted placement.", "type": "string", "example": "db.example.com:5432", "x-auditable": true } }, "required": [ "host" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "description": "Targeted placement mode.", "type": "string", "enum": [ "targeted" ], "x-auditable": true }, "region": { "description": "Cloud region for targeted placement in format 'provider:region'.", "type": "string", "example": "aws:us-east-1", "x-auditable": true } }, "required": [ "mode", "region" ], "type": "object" }, { "additionalProperties": false, "properties": { "hostname": { "description": "HTTP hostname for targeted placement.", "type": "string", "example": "api.example.com", "x-auditable": true }, "mode": { "description": "Targeted placement mode.", "type": "string", "enum": [ "targeted" ], "x-auditable": true } }, "required": [ "mode", "hostname" ], "type": "object" }, { "additionalProperties": false, "properties": { "host": { "description": "TCP host and port for targeted placement.", "type": "string", "example": "db.example.com:5432", "x-auditable": true }, "mode": { "description": "Targeted placement mode.", "type": "string", "enum": [ "targeted" ], "x-auditable": true } }, "required": [ "mode", "host" ], "type": "object" }, { "additionalProperties": false, "properties": { "mode": { "description": "Targeted placement mode.", "type": "string", "enum": [ "targeted" ], "x-auditable": true }, "target": { "description": "Array of placement targets (currently limited to single target).", "type": "array", "items": { "$ref": "#/components/schemas/workers_placement_target" }, "maxItems": 1, "minItems": 1, "x-auditable": true } }, "required": [ "mode", "target" ], "type": "object" } ] }, "workers_placement_mode": { "description": "Configuration for [Smart Placement](https://developers.cloudflare.com/workers/configuration/smart-placement). Specify mode='smart' for Smart Placement, or one of region/hostname/host.", "type": "string", "enum": [ "smart", "targeted" ], "x-auditable": true }, "workers_placement_status": { "description": "Status of [Smart Placement](https://developers.cloudflare.com/workers/configuration/smart-placement).", "type": "string", "enum": [ "SUCCESS", "UNSUPPORTED_APPLICATION", "INSUFFICIENT_INVOCATIONS" ], "readOnly": true, "x-auditable": true }, "workers_placement_target": { "description": "A target to run your Worker near.", "type": "object", "oneOf": [ { "additionalProperties": false, "properties": { "region": { "description": "Cloud region in format 'provider:region'.", "type": "string", "example": "aws:us-east-1" } }, "required": [ "region" ], "type": "object" }, { "additionalProperties": false, "properties": { "hostname": { "description": "HTTP hostname for targeted placement.", "type": "string", "example": "api.example.com" } }, "required": [ "hostname" ], "type": "object" }, { "additionalProperties": false, "properties": { "host": { "description": "TCP host:port for targeted placement.", "type": "string", "example": "db.example.com:5432" } }, "required": [ "host" ], "type": "object" } ] }, "workers_route": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/workers_identifier" } ], "readOnly": true }, "pattern": { "description": "Pattern to match incoming requests against. [Learn more](https://developers.cloudflare.com/workers/configuration/routing/routes/#matching-behavior).", "type": "string", "example": "example.com/*", "x-auditable": true }, "script": { "description": "Name of the script to run if the route matches.", "type": "string", "example": "my-workers-script", "x-auditable": true } }, "required": [ "id", "pattern" ] }, "workers_schedule": { "type": "object", "properties": { "created_on": { "type": "string", "readOnly": true, "x-auditable": true }, "cron": { "type": "string", "example": "*/30 * * * *", "x-auditable": true }, "modified_on": { "type": "string", "readOnly": true, "x-auditable": true } }, "required": [ "cron" ] }, "workers_schemas-id": { "description": "ID of the namespace.", "type": "string", "example": "5fd1cafff895419c8bcc647fc64ab8f0" }, "workers_script-and-version-settings-item": { "type": "object", "properties": { "annotations": { "description": "Annotations for the Worker version. Annotations are not inherited across settings updates; omitting this field means the new version will have no annotations.", "type": "object", "properties": { "workers/message": { "description": "Human-readable message about the version. Truncated to 1000 bytes if longer.", "type": "string", "example": "Fixed bug.", "maxLength": 1000 }, "workers/tag": { "description": "User-provided identifier for the version. Maximum 100 bytes.", "type": "string", "example": "v1.0.1", "maxLength": 100 }, "workers/triggered_by": { "description": "Operation that triggered the creation of the version. This is read-only and set by the server.", "type": "string", "example": "upload", "readOnly": true } } }, "bindings": { "allOf": [ { "$ref": "#/components/schemas/workers_bindings" }, { "default": [], "items": { "$ref": "#/components/schemas/workers_binding_item" }, "type": "array" } ] }, "cache_options": { "$ref": "#/components/schemas/workers_cache_options" }, "compatibility_date": { "allOf": [ { "$ref": "#/components/schemas/workers_compatibility_date" }, { "default": "", "type": "string", "x-auditable": true } ] }, "compatibility_flags": { "allOf": [ { "$ref": "#/components/schemas/workers_compatibility_flags" }, { "default": [], "items": { "type": "string", "x-auditable": true }, "type": "array", "x-stainless-collection-type": "set" } ] }, "exports": { "description": "Declarative exports for the Worker. Worker entrypoint entries\n(`type: worker`) carry cache configuration for that entrypoint.\n", "allOf": [ { "$ref": "#/components/schemas/workers_exports_config_map" } ], "writeOnly": true }, "exports_reconciliation": { "description": "Summary of the declarative exports reconciliation that ran on\nthis upload. Populated only when the uploaded metadata included\nan `exports` block. Durable Object entries drive reconciliation;\n`type: worker` entries do not contribute to this summary.\n", "allOf": [ { "$ref": "#/components/schemas/workers_exports_reconciliation_result" } ] }, "limits": { "$ref": "#/components/schemas/workers_limits" }, "logpush": { "$ref": "#/components/schemas/workers_logpush" }, "migrations": { "description": "Migrations to apply for Durable Objects associated with this Worker.\n", "oneOf": [ { "$ref": "#/components/schemas/workers_single_step_migrations" }, { "$ref": "#/components/schemas/workers_multiple_step_migrations" } ], "writeOnly": true }, "observability": { "$ref": "#/components/schemas/workers_observability" }, "placement": { "allOf": [ { "$ref": "#/components/schemas/workers_placement_info_no_status" }, { "default": {}, "type": "object" } ] }, "tags": { "allOf": [ { "$ref": "#/components/schemas/workers_tags" }, { "default": [], "items": { "type": "string", "x-auditable": true }, "type": "array", "x-stainless-collection-type": "set" } ] }, "tail_consumers": { "allOf": [ { "$ref": "#/components/schemas/workers_tail_consumers" }, { "default": [], "items": { "$ref": "#/components/schemas/workers_tail_consumers_script" }, "type": "array", "x-stainless-collection-type": "set" } ] }, "usage_model": { "$ref": "#/components/schemas/workers_usage_model" } } }, "workers_script-and-version-settings-response": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_script-and-version-settings-item" } }, "required": [ "result" ], "type": "object" } ] }, "workers_script-response": { "type": "object", "properties": { "cache_options": { "$ref": "#/components/schemas/workers_cache_options" }, "compatibility_date": { "$ref": "#/components/schemas/workers_compatibility_date" }, "compatibility_flags": { "$ref": "#/components/schemas/workers_compatibility_flags" }, "created_on": { "$ref": "#/components/schemas/workers_created_on" }, "etag": { "$ref": "#/components/schemas/workers_etag" }, "exports": { "description": "Declarative exports for the Worker's most recent version,\nincluding Durable Object classes (with their `storage`\nbackend) and named Worker entrypoints. Tombstoned lifecycle\nentries are omitted, so only live exports (`created` and\n`expecting-transfer`) are returned.\n", "allOf": [ { "$ref": "#/components/schemas/workers_exports_config_map" } ], "readOnly": true }, "handlers": { "description": "The names of handlers exported as part of the default export.", "type": "array", "items": { "type": "string" }, "example": [ "fetch", "scheduled" ] }, "has_assets": { "$ref": "#/components/schemas/workers_has_assets" }, "has_modules": { "$ref": "#/components/schemas/workers_has_modules" }, "id": { "description": "The name used to identify the script.", "type": "string", "example": "my-workers-script", "readOnly": true, "x-auditable": true }, "last_deployed_from": { "description": "The client most recently used to deploy this Worker.", "type": "string", "example": "wrangler" }, "logpush": { "$ref": "#/components/schemas/workers_logpush" }, "migration_tag": { "description": "The tag of the Durable Object migration that was most recently applied for this Worker.", "type": "string", "example": "v1" }, "modified_on": { "$ref": "#/components/schemas/workers_modified_on" }, "named_handlers": { "description": "Named exports, such as Durable Object class implementations and named entrypoints.", "type": "array", "items": { "properties": { "handlers": { "description": "The names of handlers exported as part of the named export.", "type": "array", "items": { "type": "string" }, "example": [ "class" ] }, "name": { "description": "The name of the export.", "type": "string", "example": "MyDurableObject" } }, "type": "object" } }, "observability": { "$ref": "#/components/schemas/workers_observability" }, "placement": { "$ref": "#/components/schemas/workers_placement_info" }, "placement_mode": { "allOf": [ { "$ref": "#/components/schemas/workers_placement_mode" }, { "deprecated": true, "type": "string" } ] }, "placement_status": { "allOf": [ { "$ref": "#/components/schemas/workers_placement_status" }, { "deprecated": true, "type": "string" } ] }, "tag": { "description": "The immutable ID of the script.", "type": "string", "example": "e8f70fdbc8b1fb0b8ddb1af166186758", "readOnly": true }, "tags": { "$ref": "#/components/schemas/workers_tags" }, "tail_consumers": { "$ref": "#/components/schemas/workers_tail_consumers" }, "usage_model": { "$ref": "#/components/schemas/workers_usage_model" } } }, "workers_script-response-collection": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/workers_script-response" }, { "properties": { "routes": { "description": "Routes associated with the Worker.", "type": "array", "items": { "$ref": "#/components/schemas/workers_route" }, "nullable": true } }, "type": "object" } ] } } }, "required": [ "result" ], "type": "object" } ] }, "workers_script-response-single": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_script-response" } }, "required": [ "result" ], "type": "object", "x-cfLinkErrors": { "10001": "Unsupported or unexpected Content Type", "10002": "Unexpected internal server error", "10003": "Missing required URL parameter", "10004": "Malformed URL parameter", "10006": "Unparseable script body", "10007": "Resource not found (similar to HTTP 404)", "10015": "The current account is not authorized to use workers", "10018": "Attempted to update a script where the e-tag does not match", "10021": "Script content failed validation checks, but was otherwise parseable", "10023": "Unauthorized access attempt", "10027": "Script body was too large", "10075": "Requires a Workers Paid plan" } } ] }, "workers_script-response-upload": { "allOf": [ { "$ref": "#/components/schemas/workers_script-response" }, { "properties": { "entry_point": { "description": "The entry point for the script.", "type": "string", "example": "index.js", "readOnly": true }, "startup_time_ms": { "type": "integer", "example": 10, "readOnly": true, "x-auditable": true } }, "required": [ "startup_time_ms" ], "type": "object" } ] }, "workers_script-response-upload-single": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_script-response-upload" } }, "required": [ "result" ], "type": "object", "x-cfLinkErrors": { "10001": "Unsupported or unexpected Content Type", "10002": "Unexpected internal server error", "10003": "Missing required URL parameter", "10004": "Malformed URL parameter", "10006": "Unparseable script body", "10007": "Resource not found (similar to HTTP 404)", "10015": "The current account is not authorized to use workers", "10018": "Attempted to update a script where the e-tag does not match", "10021": "Script content failed validation checks, but was otherwise parseable", "10023": "Unauthorized access attempt", "10027": "Script body was too large", "10075": "Requires a Workers Paid plan" } } ] }, "workers_script-settings-item": { "type": "object", "properties": { "logpush": { "$ref": "#/components/schemas/workers_logpush" }, "observability": { "allOf": [ { "$ref": "#/components/schemas/workers_observability" }, { "nullable": true, "type": "object", "x-auditable": true } ] }, "tags": { "allOf": [ { "$ref": "#/components/schemas/workers_tags" }, { "items": { "$ref": "#/components/schemas/workers_tag" }, "nullable": true, "type": "array", "x-auditable": true } ] }, "tail_consumers": { "description": "List of Workers that will consume logs from the attached Worker.", "type": "array", "items": { "$ref": "#/components/schemas/workers_tail_consumers_script" }, "nullable": true, "x-stainless-collection-type": "set" } } }, "workers_script-settings-response": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_script-settings-item" } }, "required": [ "result" ], "type": "object" } ] }, "workers_script_count": { "description": "The current number of scripts in this Dispatch Namespace.", "type": "integer", "example": 800 }, "workers_script_name": { "description": "Name of the script, used in URLs and route configuration.", "type": "string", "example": "this-is_my_script-01", "pattern": "^[a-z0-9_][a-z0-9-_]*$", "x-auditable": true }, "workers_script_name-2": { "description": "Name of the script.", "type": "string", "example": "this-is_my_script-01", "pattern": "^[a-z0-9_][a-z0-9-_]*$" }, "workers_secret": { "description": "A secret value accessible through a binding.", "type": "object", "discriminator": { "mapping": { "secret_key": "#/components/schemas/workers_binding_kind_secret_key", "secret_text": "#/components/schemas/workers_binding_kind_secret_text" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/workers_binding_kind_secret_text" }, { "$ref": "#/components/schemas/workers_binding_kind_secret_key" } ] }, "workers_secret-patch-request": { "description": "JSON Merge Patch (RFC 7396) request body for bulk secret changes.\n", "type": "object", "properties": { "secrets": { "description": "Map of secret names to secret values:\n- Set to a secret object to create or update.\n- Set to `null` to delete.\n- Omit to leave unchanged.\n", "type": "object", "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/workers_secret" } ], "nullable": true, "type": "object" } }, "version_tags": { "description": "Optional version tags to apply to the new script version.", "type": "object", "additionalProperties": true } } }, "workers_secret-patch-response": { "description": "Map of secret names to secret metadata for resulting secrets.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/workers_secret" } }, "workers_secret_name": { "description": "A JavaScript variable name for the secret binding.", "type": "string", "example": "mySecret", "readOnly": true, "x-auditable": true }, "workers_secret_name_url_encoded": { "description": "Flag that indicates whether the secret name is URL encoded.", "type": "boolean", "example": true, "readOnly": true, "x-auditable": true }, "workers_service": { "description": "Name of Worker to bind to.", "type": "string", "example": "my-worker", "x-auditable": true }, "workers_single_step_migrations": { "description": "A single set of migrations to apply.", "allOf": [ { "$ref": "#/components/schemas/workers_migration_tag_conditions" }, { "$ref": "#/components/schemas/workers_migration_step" } ] }, "workers_subdomain": { "type": "object", "properties": { "enabled": { "description": "Whether the Worker is available on the workers.dev subdomain.", "type": "boolean", "example": false, "default": false, "x-auditable": true }, "previews_enabled": { "description": "Whether the Worker's Preview URLs are available on the workers.dev subdomain.", "type": "boolean", "example": false, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } }, "required": [ "enabled", "previews_enabled" ] }, "workers_subdomain-2": { "type": "object", "properties": { "subdomain": { "type": "string", "example": "my-subdomain", "x-auditable": true } }, "required": [ "subdomain" ] }, "workers_tag": { "type": "string", "example": "my-tag", "maxLength": 1024, "pattern": "^[^,&]*$" }, "workers_tags": { "description": "Tags associated with the Worker.", "type": "array", "items": { "$ref": "#/components/schemas/workers_tag" }, "example": [ "my-team", "my-public-api" ], "maxItems": 10, "nullable": true, "x-auditable": true, "x-stainless-collection-type": "set" }, "workers_tail": { "type": "object", "properties": { "expires_at": { "type": "string", "readOnly": true, "x-auditable": true }, "id": { "allOf": [ { "$ref": "#/components/schemas/workers_identifier" } ], "readOnly": true }, "url": { "type": "string", "readOnly": true, "x-auditable": true } }, "required": [ "id", "url", "expires_at" ] }, "workers_tail_consumers": { "description": "List of Workers that will consume logs from the attached Worker.", "type": "array", "items": { "$ref": "#/components/schemas/workers_tail_consumers_script" }, "nullable": true, "x-stainless-collection-type": "set" }, "workers_tail_consumers_script": { "description": "A reference to a script that will consume logs from the attached Worker.", "type": "object", "properties": { "environment": { "description": "Optional environment if the Worker utilizes one.", "type": "string", "example": "production", "x-auditable": true }, "namespace": { "description": "Optional dispatch namespace the script belongs to.", "type": "string", "example": "my-namespace", "x-auditable": true }, "service": { "description": "Name of Worker that is to be the consumer.", "type": "string", "example": "my-log-consumer", "x-auditable": true } }, "required": [ "service" ] }, "workers_trusted_workers": { "description": "Whether the Workers in the namespace are executed in a \"trusted\" manner. When a Worker is trusted, it has access to the shared caches for the zone in the Cache API, and has access to the `request.cf` object on incoming Requests. When a Worker is untrusted, caches are not shared across the zone, and `request.cf` is undefined. By default, Workers in a namespace are \"untrusted\".", "type": "boolean", "example": false, "default": false, "x-auditable": true }, "workers_upload-assets-response": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "object", "additionalProperties": false, "maxProperties": 0 } }, "type": "object" } ] }, "workers_usage-model-response": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "usage_model": { "$ref": "#/components/schemas/workers_usage_model" }, "user_limits": { "$ref": "#/components/schemas/workers_user_limits" } } } }, "required": [ "result" ], "type": "object" } ] }, "workers_usage_model": { "description": "Usage model for the Worker invocations.", "type": "string", "example": "standard", "default": "standard", "enum": [ "standard", "bundled", "unbound" ], "x-auditable": true }, "workers_user_limits": { "description": "User-defined resource limits for Workers with standard usage model.", "type": "object", "properties": { "cpu_ms": { "description": "The amount of CPU time this Worker can use in milliseconds.", "type": "integer", "example": 50, "nullable": true } }, "nullable": true }, "workers_uuid": { "description": "API Resource UUID tag.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "x-auditable": true }, "workers_version-item-full": { "allOf": [ { "$ref": "#/components/schemas/workers_version-item-short" }, { "properties": { "resources": { "type": "object", "example": { "bindings": [ { "json": "example_binding", "name": "JSON_VAR", "type": "json" } ], "script": { "etag": "13a3240e8fb414561b0366813b0b8f42b3e6cfa0d9e70e99835dae83d0d8a794", "handlers": [ "fetch" ], "last_deployed_from": "api" }, "script_runtime": { "usage_model": "standard" } }, "properties": { "bindings": { "type": "array", "items": { "$ref": "#/components/schemas/workers_binding_item" }, "allOf": [ { "$ref": "#/components/schemas/workers_bindings" }, { "items": { "$ref": "#/components/schemas/workers_binding_item" }, "readOnly": true, "type": "array" } ] }, "script": { "type": "object", "example": { "etag": "13a3240e8fb414561b0366813b0b8f42b3e6cfa0d9e70e99835dae83d0d8a794", "handlers": [ "fetch" ], "last_deployed_from": "api", "named_handlers": [ { "handlers": [ "fetch" ], "name": "MyClass" } ] }, "properties": { "etag": { "description": "Hashed script content", "type": "string", "example": "13a3240e8fb414561b0366813b0b8f42b3e6cfa0d9e70e99835dae83d0d8a794", "readOnly": true, "x-auditable": true }, "handlers": { "description": "The names of handlers exported as part of the default export.", "type": "array", "items": { "example": "fetch", "readOnly": true, "type": "string" }, "example": [ "fetch" ], "readOnly": true, "x-stainless-collection-type": "set" }, "last_deployed_from": { "description": "The client most recently used to deploy this Worker.", "type": "string", "example": "api", "readOnly": true, "x-auditable": true }, "named_handlers": { "description": "Named exports, such as Durable Object class implementations and named entrypoints.", "type": "array", "items": { "example": { "handlers": [ "fetch" ], "name": "MyClass" }, "properties": { "handlers": { "description": "The names of handlers exported as part of the named export.", "type": "array", "items": { "example": "fetch", "readOnly": true, "type": "string" }, "example": [ "fetch" ], "readOnly": true, "x-stainless-collection-type": "set" }, "name": { "description": "The name of the exported class or entrypoint.", "type": "string", "example": "MyClass", "readOnly": true } }, "readOnly": true, "type": "object" }, "example": [ { "handlers": [ "fetch" ], "name": "MyClass" } ], "readOnly": true, "x-stainless-collection-type": "set" } }, "readOnly": true }, "script_runtime": { "description": "Runtime configuration for the Worker.", "type": "object", "properties": { "compatibility_date": { "description": "Date indicating targeted support in the Workers runtime. Backwards incompatible fixes to the runtime following this date will not affect this Worker.", "type": "string", "example": "2022-11-08T00:00:00Z", "readOnly": true, "x-auditable": true }, "compatibility_flags": { "description": "Flags that enable or disable certain features in the Workers runtime.", "type": "array", "items": { "example": "x", "readOnly": true, "type": "string" }, "readOnly": true, "x-stainless-collection-type": "set" }, "exports": { "description": "Declarative exports for this version, including\nDurable Object classes (with their `storage`\nbackend) and named Worker entrypoints. Tombstoned\nlifecycle entries are omitted, so only live exports\n(`created` and `expecting-transfer`) are returned.\n", "allOf": [ { "$ref": "#/components/schemas/workers_exports_config_map" } ], "readOnly": true }, "limits": { "description": "Resource limits for the Worker.", "type": "object", "example": { "cpu_ms": 50 }, "properties": { "cpu_ms": { "description": "The amount of CPU time this Worker can use in milliseconds.", "type": "integer", "example": 50, "readOnly": true } }, "readOnly": true }, "migration_tag": { "description": "The tag of the Durable Object migration that was most recently applied for this Worker.", "type": "string", "example": "v1", "readOnly": true, "x-auditable": true }, "usage_model": { "description": "Usage model for the Worker invocations.", "type": "string", "example": "standard", "enum": [ "bundled", "unbound", "standard" ], "readOnly": true, "x-auditable": true } }, "readOnly": true } }, "readOnly": true } }, "required": [ "resources" ], "type": "object" } ] }, "workers_version-item-short": { "type": "object", "properties": { "id": { "description": "Unique identifier for the version.", "type": "string", "example": "18f97339-c287-4872-9bdd-e2135c07ec12", "readOnly": true, "x-auditable": true }, "metadata": { "type": "object", "example": { "author_email": "user@example.com", "author_id": "408cbcdfd4dda4617efef40b04d168a1", "created_on": "2022-11-08T17:19:29.176266Z", "modified_on": "2022-11-08T17:19:29.176266Z", "source": "api" }, "properties": { "author_email": { "description": "Email of the user who created the version.", "type": "string", "example": "user@example.com", "readOnly": true, "x-auditable": true }, "author_id": { "description": "Identifier of the user who created the version.", "type": "string", "example": "408cbcdfd4dda4617efef40b04d168a1", "readOnly": true, "x-auditable": true }, "created_on": { "description": "When the version was created.", "type": "string", "example": "2022-11-08T17:19:29.176266Z", "readOnly": true, "x-auditable": true }, "hasPreview": { "description": "Whether the version can be previewed.", "type": "boolean", "readOnly": true }, "modified_on": { "description": "When the version was last modified.", "type": "string", "example": "2022-11-08T17:19:29.176266Z", "readOnly": true, "x-auditable": true }, "source": { "description": "The source of the version upload.", "type": "string", "example": "api", "enum": [ "unknown", "api", "wrangler", "terraform", "dash", "cf_cli", "dash_template", "integration", "quick_editor", "playground", "workersci" ], "readOnly": true, "x-auditable": true } }, "readOnly": true }, "number": { "description": "Sequential version number.", "type": "number", "example": 1, "readOnly": true, "x-auditable": true } } }, "workers_version-item-uploaded": { "allOf": [ { "$ref": "#/components/schemas/workers_version-item-full" }, { "properties": { "exports_reconciliation": { "description": "Summary of the declarative exports reconciliation that\nran on this upload. Populated only when the uploaded\nmetadata included an `exports` block. Durable Object\nentries drive reconciliation; `type: worker` entries do\nnot contribute to this summary.\n", "allOf": [ { "$ref": "#/components/schemas/workers_exports_reconciliation_result" } ] }, "startup_time_ms": { "description": "Time in milliseconds spent on [Worker startup](https://developers.cloudflare.com/workers/platform/limits/#worker-startup-time).", "type": "integer", "example": 10 } }, "required": [ "resources" ], "type": "object" } ] }, "workers_version_identifier": { "type": "string", "example": "bcf48806-b317-4351-9ee7-36e7d557d4de", "maxLength": 36, "readOnly": true }, "workers_versions-list-response": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/workers_version-item-short" } } } } }, "required": [ "result" ], "type": "object" } ] }, "workers_versions-single-response": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_version-item-full" } }, "required": [ "result" ], "type": "object" } ] }, "workers_versions-upload-response": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/workers_version-item-uploaded" } }, "required": [ "result" ], "type": "object" } ] }, "workers_worker_export": { "description": "A named Worker entrypoint export (`type: worker`). Worker\nentrypoints are always live (`state: created`) and carry no\nstorage or lifecycle fields. The optional `cache` block overrides\nthe Worker's global `cache_options.enabled` for this entrypoint.\n", "type": "object", "properties": { "cache": { "description": "Cache override for this entrypoint. Overrides the Worker's\nglobal `cache_options.enabled` for this entrypoint only.\n", "allOf": [ { "$ref": "#/components/schemas/workers_entrypoint_cache_options" } ] }, "state": { "description": "Live export. May be omitted; defaults to `created`.", "type": "string", "default": "created", "enum": [ "created" ] }, "type": { "description": "Marks this entry as a Worker entrypoint export.", "type": "string", "enum": [ "worker" ] } }, "additionalProperties": false, "required": [ "type" ] }, "zaraz_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/zaraz_messages" }, "messages": { "$ref": "#/components/schemas/zaraz_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "x-auditable": true } }, "required": [ "success", "errors", "messages", "result" ] }, "zaraz_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/zaraz_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/zaraz_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "zaraz_base-mc": { "allOf": [ { "$ref": "#/components/schemas/zaraz_base-tool" }, { "properties": { "actions": { "description": "Actions configured on a tool. Either this or neoEvents field is required.", "type": "object", "additionalProperties": { "properties": { "actionType": { "description": "Tool event type.", "type": "string", "x-auditable": true }, "blockingTriggers": { "description": "List of blocking triggers IDs.", "type": "array", "items": { "type": "string", "x-auditable": true } }, "data": { "description": "Event payload.", "type": "object" }, "firingTriggers": { "description": "List of firing triggers IDs.", "type": "array", "items": { "type": "string", "x-auditable": true }, "minItems": 1 } }, "required": [ "actionType", "blockingTriggers", "firingTriggers", "data" ], "type": "object" } }, "component": { "description": "Tool's internal name.", "type": "string", "x-auditable": true }, "neoEvents": { "description": "DEPRECATED - List of actions configured on a tool. Either this or actions field is required. If both are present, actions field will take precedence.", "type": "array", "items": { "properties": { "actionType": { "description": "Tool event type.", "type": "string", "x-auditable": true }, "blockingTriggers": { "description": "List of blocking triggers IDs.", "type": "array", "items": { "type": "string", "x-auditable": true } }, "data": { "description": "Event payload.", "type": "object" }, "firingTriggers": { "description": "List of firing triggers IDs.", "type": "array", "items": { "type": "string", "x-auditable": true }, "minItems": 1 } }, "required": [ "actionType", "blockingTriggers", "firingTriggers", "data" ], "type": "object" } }, "permissions": { "description": "List of permissions granted to the component.", "type": "array", "items": { "type": "string", "x-auditable": true } }, "settings": { "description": "Tool's settings.", "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ], "x-auditable": true } } }, "required": [ "component", "settings", "permissions" ], "type": "object" } ] }, "zaraz_base-tool": { "type": "object", "properties": { "blockingTriggers": { "description": "List of blocking trigger IDs.", "type": "array", "items": { "type": "string", "x-auditable": true } }, "defaultFields": { "description": "Default fields for tool's actions.", "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ], "x-auditable": true } }, "defaultPurpose": { "description": "Default consent purpose ID.", "type": "string", "x-auditable": true }, "enabled": { "description": "Whether tool is enabled.", "type": "boolean", "x-auditable": true }, "name": { "description": "Tool's name defined by the user.", "type": "string", "x-auditable": true }, "vendorName": { "description": "Vendor name for TCF compliant consent modal, required for Custom Managed Components and Custom HTML tool with a defaultPurpose assigned.", "type": "string", "x-auditable": true }, "vendorPolicyUrl": { "description": "Vendor's Privacy Policy URL for TCF compliant consent modal, required for Custom Managed Components and Custom HTML tool with a defaultPurpose assigned.", "type": "string", "x-auditable": true } }, "required": [ "enabled", "blockingTriggers", "name", "defaultFields" ] }, "zaraz_click-listener-rule": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "clickListener" ], "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "settings": { "type": "object", "properties": { "selector": { "type": "string", "x-auditable": true }, "type": { "type": "string", "enum": [ "xpath", "css" ], "x-auditable": true }, "waitForTags": { "type": "integer", "minimum": 0, "x-auditable": true } }, "required": [ "type", "selector", "waitForTags" ] } }, "required": [ "id", "action", "settings" ] }, "zaraz_custom-managed-component": { "allOf": [ { "$ref": "#/components/schemas/zaraz_base-mc" }, { "properties": { "type": { "type": "string", "enum": [ "custom-mc" ] }, "worker": { "description": "Cloudflare worker that acts as a managed component.", "type": "object", "properties": { "escapedWorkerName": { "type": "string", "x-auditable": true }, "workerTag": { "type": "string", "x-auditable": true } }, "required": [ "workerTag", "escapedWorkerName" ] } }, "required": [ "worker", "type" ], "type": "object" } ] }, "zaraz_element-visibility-rule": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "elementVisibility" ], "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "settings": { "type": "object", "properties": { "selector": { "type": "string", "x-auditable": true } }, "required": [ "selector" ] } }, "required": [ "id", "action", "settings" ] }, "zaraz_form-submission-rule": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "formSubmission" ], "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "settings": { "type": "object", "properties": { "selector": { "type": "string", "x-auditable": true }, "validate": { "type": "boolean", "x-auditable": true } }, "required": [ "selector", "validate" ] } }, "required": [ "id", "action", "settings" ] }, "zaraz_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "zaraz_load-rule": { "type": "object", "properties": { "id": { "type": "string", "x-auditable": true }, "match": { "type": "string", "x-auditable": true }, "op": { "type": "string", "enum": [ "CONTAINS", "EQUALS", "STARTS_WITH", "ENDS_WITH", "MATCH_REGEX", "NOT_MATCH_REGEX", "GREATER_THAN", "GREATER_THAN_OR_EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL" ], "x-auditable": true }, "value": { "type": "string", "x-auditable": true } }, "required": [ "id", "match", "op", "value" ] }, "zaraz_managed-component": { "allOf": [ { "$ref": "#/components/schemas/zaraz_base-mc" }, { "properties": { "type": { "type": "string", "enum": [ "component" ] } }, "required": [ "type" ], "type": "object" } ] }, "zaraz_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "zaraz_scroll-depth-rule": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "scrollDepth" ], "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "settings": { "type": "object", "properties": { "positions": { "type": "string", "x-auditable": true } }, "required": [ "positions" ] } }, "required": [ "id", "action", "settings" ] }, "zaraz_secret_variable": { "type": "object", "properties": { "name": { "type": "string", "x-auditable": true }, "type": { "type": "string", "enum": [ "secret" ], "x-auditable": true }, "value": { "type": "string", "x-auditable": true, "x-sensitive": true } }, "required": [ "name", "type", "value" ] }, "zaraz_string_variable": { "type": "object", "properties": { "name": { "type": "string", "x-auditable": true }, "type": { "type": "string", "enum": [ "string" ], "x-auditable": true }, "value": { "type": "string", "x-auditable": true } }, "required": [ "name", "type", "value" ] }, "zaraz_timer-rule": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "timer" ], "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "settings": { "type": "object", "properties": { "interval": { "type": "integer", "minimum": 50, "x-auditable": true }, "limit": { "type": "integer", "minimum": 0, "x-auditable": true } }, "required": [ "interval", "limit" ] } }, "required": [ "id", "action", "settings" ] }, "zaraz_variable-match-rule": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "variableMatch" ], "x-auditable": true }, "id": { "type": "string", "x-auditable": true }, "settings": { "type": "object", "properties": { "match": { "type": "string", "x-auditable": true }, "variable": { "type": "string", "x-auditable": true } }, "required": [ "variable", "match" ] } }, "required": [ "id", "action", "settings" ] }, "zaraz_worker_variable": { "type": "object", "properties": { "name": { "type": "string", "x-auditable": true }, "type": { "type": "string", "enum": [ "worker" ], "x-auditable": true }, "value": { "type": "object", "properties": { "escapedWorkerName": { "type": "string", "x-auditable": true }, "workerTag": { "type": "string", "x-auditable": true } }, "required": [ "escapedWorkerName", "workerTag" ] } }, "required": [ "name", "type", "value" ] }, "zaraz_zaraz-config-base": { "description": "Zaraz configuration.", "type": "object", "properties": { "analytics": { "description": "Cloudflare Monitoring settings.", "type": "object", "properties": { "defaultPurpose": { "description": "Consent purpose assigned to Monitoring.", "type": "string", "x-auditable": true }, "enabled": { "description": "Whether Advanced Monitoring reports are enabled.", "type": "boolean", "x-auditable": true }, "sessionExpTime": { "description": "Session expiration time (seconds).", "type": "integer", "maximum": 86400, "minimum": 60, "x-auditable": true } } }, "consent": { "description": "Consent management configuration.", "type": "object", "properties": { "buttonTextTranslations": { "type": "object", "properties": { "accept_all": { "description": "Object where keys are language codes.", "type": "object", "additionalProperties": { "type": "string", "x-auditable": true } }, "confirm_my_choices": { "description": "Object where keys are language codes.", "type": "object", "additionalProperties": { "type": "string", "x-auditable": true } }, "reject_all": { "description": "Object where keys are language codes.", "type": "object", "additionalProperties": { "type": "string", "x-auditable": true } } }, "required": [ "accept_all", "reject_all", "confirm_my_choices" ] }, "companyEmail": { "type": "string", "x-auditable": true }, "companyName": { "type": "string", "x-auditable": true }, "companyStreetAddress": { "type": "string", "x-auditable": true }, "consentModalIntroHTML": { "type": "string", "x-auditable": true }, "consentModalIntroHTMLWithTranslations": { "description": "Object where keys are language codes.", "type": "object", "additionalProperties": { "type": "string", "x-auditable": true } }, "cookieName": { "type": "string", "x-auditable": true }, "customCSS": { "type": "string", "x-auditable": true }, "customIntroDisclaimerDismissed": { "type": "boolean", "x-auditable": true }, "defaultLanguage": { "type": "string", "x-auditable": true }, "enabled": { "type": "boolean" }, "hideModal": { "type": "boolean", "x-auditable": true }, "purposes": { "description": "Object where keys are purpose alpha-numeric IDs.", "type": "object", "additionalProperties": { "properties": { "description": { "type": "string", "x-auditable": true }, "name": { "type": "string", "x-auditable": true } }, "required": [ "name", "description" ], "type": "object" } }, "purposesWithTranslations": { "description": "Object where keys are purpose alpha-numeric IDs.", "type": "object", "additionalProperties": { "properties": { "description": { "description": "Object where keys are language codes.", "type": "object", "additionalProperties": { "type": "string", "x-auditable": true } }, "name": { "description": "Object where keys are language codes.", "type": "object", "additionalProperties": { "type": "string", "x-auditable": true } }, "order": { "type": "integer", "x-auditable": true } }, "required": [ "name", "description", "order" ], "type": "object" } }, "tcfCompliant": { "type": "boolean" } }, "required": [ "enabled" ] }, "dataLayer": { "description": "Data layer compatibility mode enabled.", "type": "boolean", "x-auditable": true }, "debugKey": { "description": "The key for Zaraz debug mode.", "type": "string", "x-auditable": true }, "historyChange": { "description": "Single Page Application support enabled.", "type": "boolean", "x-auditable": true }, "settings": { "description": "General Zaraz settings.", "type": "object", "properties": { "autoInjectScript": { "description": "Automatic injection of Zaraz scripts enabled.", "type": "boolean", "x-auditable": true }, "contextEnricher": { "description": "Details of the worker that receives and edits Zaraz Context object.", "type": "object", "properties": { "escapedWorkerName": { "type": "string", "x-auditable": true }, "workerTag": { "type": "string", "x-auditable": true } }, "required": [ "escapedWorkerName", "workerTag" ] }, "cookieDomain": { "description": "The domain Zaraz will use for writing and reading its cookies.", "type": "string", "x-auditable": true }, "ecommerce": { "description": "Ecommerce API enabled.", "type": "boolean", "x-auditable": true }, "eventsApiPath": { "description": "Custom endpoint for server-side track events.", "type": "string", "x-auditable": true }, "hideExternalReferer": { "description": "Hiding external referrer URL enabled.", "type": "boolean", "x-auditable": true }, "hideIPAddress": { "description": "Trimming IP address enabled.", "type": "boolean", "x-auditable": true }, "hideQueryParams": { "description": "Removing URL query params enabled.", "type": "boolean", "x-auditable": true }, "hideUserAgent": { "description": "Removing sensitive data from User Agent string enabled.", "type": "boolean" }, "initPath": { "description": "Custom endpoint for Zaraz init script.", "type": "string", "x-auditable": true }, "injectIframes": { "description": "Injection of Zaraz scripts into iframes enabled.", "type": "boolean", "x-auditable": true }, "mcRootPath": { "description": "Custom path for Managed Components server functionalities.", "type": "string", "x-auditable": true }, "scriptPath": { "description": "Custom endpoint for Zaraz main script.", "type": "string", "x-auditable": true }, "trackPath": { "description": "Custom endpoint for Zaraz tracking requests.", "type": "string", "x-auditable": true } }, "required": [ "autoInjectScript" ] }, "triggers": { "description": "Triggers set up under Zaraz configuration, where key is the trigger alpha-numeric ID and value is the trigger configuration.", "type": "object", "additionalProperties": { "properties": { "description": { "description": "Trigger description.", "type": "string", "x-auditable": true }, "excludeRules": { "description": "Rules defining when the trigger is not fired.", "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/zaraz_load-rule" }, { "$ref": "#/components/schemas/zaraz_click-listener-rule" }, { "$ref": "#/components/schemas/zaraz_timer-rule" }, { "$ref": "#/components/schemas/zaraz_form-submission-rule" }, { "$ref": "#/components/schemas/zaraz_variable-match-rule" }, { "$ref": "#/components/schemas/zaraz_scroll-depth-rule" }, { "$ref": "#/components/schemas/zaraz_element-visibility-rule" } ] } }, "loadRules": { "description": "Rules defining when the trigger is fired.", "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/zaraz_load-rule" }, { "$ref": "#/components/schemas/zaraz_click-listener-rule" }, { "$ref": "#/components/schemas/zaraz_timer-rule" }, { "$ref": "#/components/schemas/zaraz_form-submission-rule" }, { "$ref": "#/components/schemas/zaraz_variable-match-rule" }, { "$ref": "#/components/schemas/zaraz_scroll-depth-rule" }, { "$ref": "#/components/schemas/zaraz_element-visibility-rule" } ] } }, "name": { "description": "Trigger name.", "type": "string", "x-auditable": true }, "system": { "type": "string", "enum": [ "pageload" ], "x-auditable": true } }, "required": [ "name", "loadRules", "excludeRules" ], "type": "object" } }, "variables": { "description": "Variables set up under Zaraz configuration, where key is the variable alpha-numeric ID and value is the variable configuration. Values of variables of type secret are not included.", "type": "object", "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/zaraz_string_variable" }, { "$ref": "#/components/schemas/zaraz_secret_variable" }, { "$ref": "#/components/schemas/zaraz_worker_variable" } ], "discriminator": { "mapping": { "secret": "#/components/schemas/zaraz_secret_variable", "string": "#/components/schemas/zaraz_string_variable", "worker": "#/components/schemas/zaraz_worker_variable" }, "propertyName": "type" } } }, "zarazVersion": { "description": "Zaraz internal version of the config.", "type": "integer", "x-auditable": true } }, "example": { "consent": { "cookieName": "zaraz-consent", "customIntroDisclaimerDismissed": true, "enabled": false }, "dataLayer": true, "debugKey": "my-debug-key", "settings": { "autoInjectScript": true, "ecommerce": true, "initPath": "/i" }, "tools": { "aJvt": { "actions": { "hrnc": { "actionType": "pageview", "blockingTriggers": [], "data": { "__zaraz_setting_name": "Page view", "ev": "PageView" }, "firingTriggers": [ "Pageview" ] } }, "component": "facebook-pixel", "defaultFields": { "testKey": "TEST123456" }, "enabled": true, "name": "Facebook Pixel", "permissions": [ "access_client_kv" ], "settings": { "accessToken": "ABcdEFg", "ecommerce": true, "property": "12345" }, "type": "component" } }, "triggers": { "ktBn": { "Pageview": { "clientRules": [], "description": "All page loads", "excludeRules": [], "loadRules": [ { "match": "{{ client.__zarazTrack }}", "op": "EQUALS", "value": "Pageview" } ], "name": "Pageview", "system": "pageload" } } }, "variables": { "Autd": { "name": "ip", "type": "string", "value": "{{ system.device.ip }}" } }, "zarazVersion": 43 }, "required": [ "tools", "triggers", "variables", "settings", "dataLayer", "debugKey", "zarazVersion" ] }, "zaraz_zaraz-config-body": { "allOf": [ { "$ref": "#/components/schemas/zaraz_zaraz-config-base" }, { "properties": { "tools": { "description": "Tools set up under Zaraz configuration, where key is the alpha-numeric tool ID and value is the tool configuration object.", "type": "object", "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/zaraz_managed-component" }, { "$ref": "#/components/schemas/zaraz_custom-managed-component" } ] } } }, "type": "object" } ] }, "zaraz_zaraz-config-history-response": { "allOf": [ { "$ref": "#/components/schemas/zaraz_api-response-common" }, { "properties": { "result": { "description": "Object where keys are numeric configuration IDs.", "type": "object", "example": { "12345": { "config": { "consent": { "cookieName": "zaraz-consent", "customIntroDisclaimerDismissed": true, "enabled": false }, "dataLayer": true, "debugKey": "my-debug-key", "settings": { "autoInjectScript": true }, "tools": { "aJvt": { "component": "facebook-pixel", "defaultFields": { "testKey": "TEST123456" }, "enabled": true, "name": "Facebook Pixel", "neoEvents": [ { "actionType": "pageview", "blockingTriggers": [], "data": { "__zaraz_setting_name": "Page view", "ev": "PageView" }, "firingTriggers": [ "Pageview" ] } ], "permissions": [ "access_client_kv" ], "settings": { "accessToken": "ABcdEFg", "ecommerce": true, "property": "12345" }, "type": "component" } }, "triggers": { "ktBn": { "Pageview": { "clientRules": [], "description": "All page loads", "excludeRules": [], "loadRules": [ { "match": "{{ client.__zarazTrack }}", "op": "EQUALS", "value": "Pageview" } ], "name": "Pageview", "system": "pageload" } } }, "variables": { "Autd": { "name": "ip", "type": "string", "value": "{{ system.device.ip }}" } }, "zarazVersion": 43 }, "createdAt": "2023-02-23T05:05:55.155273Z", "id": 12345, "updatedAt": "2023-02-23T05:05:55.155273Z", "userId": "278d0d0g123cd8e49d45ea64f12faa37" }, "23456": null }, "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/zaraz_zaraz-config-row-base" }, { "description": "Configuration record corresponding to an ID provided in query params.", "nullable": true, "properties": { "config": { "$ref": "#/components/schemas/zaraz_zaraz-config-return" } }, "required": [ "config" ], "type": "object" } ] } } }, "type": "object" } ] }, "zaraz_zaraz-config-response": { "allOf": [ { "$ref": "#/components/schemas/zaraz_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/zaraz_zaraz-config-return" } }, "type": "object" } ] }, "zaraz_zaraz-config-return": { "allOf": [ { "$ref": "#/components/schemas/zaraz_zaraz-config-base" }, { "properties": { "tools": { "description": "Tools set up under Zaraz configuration, where key is the alpha-numeric tool ID and value is the tool configuration object.", "type": "object", "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/zaraz_managed-component" }, { "$ref": "#/components/schemas/zaraz_custom-managed-component" } ] } } }, "type": "object" } ] }, "zaraz_zaraz-config-row-base": { "type": "object", "properties": { "createdAt": { "description": "Date and time the configuration was created.", "type": "string", "format": "date-time", "x-auditable": true }, "id": { "description": "ID of the configuration.", "type": "integer", "x-auditable": true }, "updatedAt": { "description": "Date and time the configuration was last updated.", "type": "string", "format": "date-time", "x-auditable": true }, "userId": { "description": "Alpha-numeric ID of the account user who published the configuration.", "type": "string", "x-auditable": true } }, "required": [ "id", "createdAt", "updatedAt", "userId" ] }, "zaraz_zaraz-history-response": { "allOf": [ { "$ref": "#/components/schemas/zaraz_api-response-common" }, { "properties": { "result": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/zaraz_zaraz-config-row-base" }, { "example": { "createdAt": "2023-02-23T05:05:55.155273Z", "description": "Config with enabled ecommerce tracking", "id": 12345, "updatedAt": "2023-02-23T05:05:55.155273Z", "userId": "278d0d0g123cd8e49d45ea64f12faa37" }, "properties": { "description": { "description": "Configuration description provided by the user who published this configuration.", "type": "string" } }, "required": [ "description" ], "type": "object" } ] } } }, "type": "object" } ] }, "zaraz_zaraz-workflow": { "description": "Zaraz workflow.", "type": "string", "enum": [ "realtime", "preview" ], "x-auditable": true }, "zaraz_zaraz-workflow-response": { "allOf": [ { "$ref": "#/components/schemas/zaraz_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/zaraz_zaraz-workflow" } }, "type": "object" } ] }, "zaraz_zone-identifier": { "$ref": "#/components/schemas/zaraz_identifier" }, "zero-trust-gateway_account-log-options": { "type": "object", "properties": { "log_all": { "description": "Specify whether to log all requests to this service.", "type": "boolean", "example": false, "default": false, "x-auditable": true }, "log_blocks": { "description": "Specify whether to log only blocking requests to this service.", "type": "boolean", "example": true, "default": false, "x-auditable": true } } }, "zero-trust-gateway_action": { "description": "Specify the action to perform when the associated traffic, identity, and device posture expressions either absent or evaluate to `true`.", "type": "string", "example": "allow", "enum": [ "on", "off", "allow", "block", "scan", "noscan", "safesearch", "ytrestricted", "isolate", "noisolate", "override", "l4_override", "egress", "resolve", "quarantine", "redirect" ], "x-auditable": true }, "zero-trust-gateway_activity-log-settings": { "description": "Specify activity log settings.", "type": "object", "properties": { "enabled": { "description": "Specify whether to log activity.", "type": "boolean", "example": true, "nullable": true, "x-auditable": true } }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_anti-virus-settings": { "description": "Specify anti-virus settings.", "type": "object", "properties": { "enabled_download_phase": { "$ref": "#/components/schemas/zero-trust-gateway_enabled_download_phase" }, "enabled_upload_phase": { "$ref": "#/components/schemas/zero-trust-gateway_enabled_upload_phase" }, "fail_closed": { "$ref": "#/components/schemas/zero-trust-gateway_fail_closed" }, "notification_settings": { "$ref": "#/components/schemas/zero-trust-gateway_notification_settings" } }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_api-response-collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-common" }, { "properties": { "result_info": { "$ref": "#/components/schemas/zero-trust-gateway_result_info" } }, "type": "object" } ] }, "zero-trust-gateway_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/zero-trust-gateway_messages" }, "messages": { "$ref": "#/components/schemas/zero-trust-gateway_messages" }, "success": { "description": "Indicate whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "zero-trust-gateway_api-response-common-failure": { "type": "object", "properties": { "errors": { "type": "object", "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_messages" } ], "minLength": 1 }, "messages": { "type": "object", "example": [], "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Indicate whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "zero-trust-gateway_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-common" } ] }, "zero-trust-gateway_app-types": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_application" }, { "$ref": "#/components/schemas/zero-trust-gateway_application_type" } ], "readOnly": true }, "zero-trust-gateway_app_id": { "description": "Identify this application. Only one application per ID.", "type": "integer", "x-auditable": true }, "zero-trust-gateway_app_type_id": { "description": "Identify the type of this application. Multiple applications can share the same type. Refers to the `id` of a returned application type.", "type": "integer", "x-auditable": true }, "zero-trust-gateway_application": { "type": "object", "properties": { "application_type_id": { "$ref": "#/components/schemas/zero-trust-gateway_app_type_id" }, "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_timestamp" }, "id": { "$ref": "#/components/schemas/zero-trust-gateway_app_id" }, "name": { "$ref": "#/components/schemas/zero-trust-gateway_name-4" } } }, "zero-trust-gateway_application_type": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_timestamp" }, "description": { "description": "Provide a short summary of applications with this type.", "type": "string", "example": "Applications used to communicate or collaborate in a business setting." }, "id": { "$ref": "#/components/schemas/zero-trust-gateway_app_type_id" }, "name": { "$ref": "#/components/schemas/zero-trust-gateway_name-4" } } }, "zero-trust-gateway_applications_review_status_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/zero-trust-gateway_applications_review_status_response_content" } }, "type": "object" } ], "x-auditable": true }, "zero-trust-gateway_applications_review_status_response_content": { "type": "object", "properties": { "approved_apps": { "$ref": "#/components/schemas/zero-trust-gateway_approved_apps" }, "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "in_review_apps": { "$ref": "#/components/schemas/zero-trust-gateway_in_review_apps" }, "unapproved_apps": { "$ref": "#/components/schemas/zero-trust-gateway_unapproved_apps" }, "updated_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" } } }, "zero-trust-gateway_approved_apps": { "description": "Contains the ids of the approved applications.", "type": "array", "items": { "type": "integer" }, "x-stainless-collection-type": "set" }, "zero-trust-gateway_beta": { "description": "Indicate whether the category is in beta and subject to change.", "type": "boolean", "example": false, "x-auditable": true }, "zero-trust-gateway_binding_status": { "description": "Indicate the read-only deployment status of the certificate on Cloudflare's edge. Gateway TLS interception can use certificates in the 'available' (previously called 'active') state.", "type": "string", "enum": [ "pending_deployment", "available", "pending_deletion", "inactive" ], "readOnly": true, "x-auditable": true }, "zero-trust-gateway_block-page-settings": { "description": "Specify block page layout settings.", "type": "object", "properties": { "background_color": { "description": "Specify the block page background color in `#rrggbb` format when the mode is customized_block_page.", "type": "string", "x-auditable": true }, "enabled": { "description": "Specify whether to enable the custom block page.", "type": "boolean", "example": true, "nullable": true, "x-auditable": true }, "footer_text": { "description": "Specify the block page footer text when the mode is customized_block_page.", "type": "string", "example": "--footer--", "x-auditable": true }, "header_text": { "description": "Specify the block page header text when the mode is customized_block_page.", "type": "string", "example": "--header--", "x-auditable": true }, "include_context": { "description": "Specify whether to append context to target_uri as query parameters. This applies only when the mode is redirect_uri.", "type": "boolean", "x-auditable": true }, "logo_path": { "description": "Specify the full URL to the logo file when the mode is customized_block_page.", "type": "string", "example": "https://logos.com/a.png", "x-auditable": true }, "mailto_address": { "description": "Specify the admin email for users to contact when the mode is customized_block_page.", "type": "string", "example": "admin@example.com", "x-auditable": true }, "mailto_subject": { "description": "Specify the subject line for emails created from the block page when the mode is customized_block_page.", "type": "string", "example": "Blocked User Inquiry", "x-auditable": true }, "mode": { "description": "Specify whether to redirect users to a Cloudflare-hosted block page or a customer-provided URI.", "type": "string", "default": "", "enum": [ "", "customized_block_page", "redirect_uri" ], "x-auditable": true, "x-stainless-terraform-configurability": "optional" }, "name": { "description": "Specify the block page title when the mode is customized_block_page.", "type": "string", "example": "Cloudflare", "x-auditable": true }, "read_only": { "description": "Indicate that this setting was shared via the Orgs API and read only for the current account.", "type": "boolean", "nullable": true, "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "source_account": { "description": "Indicate the account tag of the account that shared this setting.", "type": "string", "nullable": true, "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "suppress_footer": { "description": "Specify whether to suppress detailed information at the bottom of the block page when the mode is customized_block_page.", "type": "boolean", "example": false }, "target_uri": { "description": "Specify the URI to redirect users to when the mode is redirect_uri.", "type": "string", "format": "uri", "x-auditable": true }, "version": { "description": "Indicate the version number of the setting.", "type": "integer", "example": 1, "nullable": true, "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" } }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_body-scanning-settings": { "description": "Specify the DLP inspection mode.", "type": "object", "properties": { "inspection_mode": { "description": "Specify the inspection mode as either `deep` or `shallow`.", "type": "string", "example": "deep", "enum": [ "deep", "shallow" ], "x-auditable": true } }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_browser-isolation-settings": { "description": "Specify Clientless Browser Isolation settings.", "type": "object", "properties": { "non_identity_enabled": { "description": "Specify whether to enable non-identity onramp support for Browser Isolation.", "type": "boolean", "example": true, "x-auditable": true }, "url_browser_isolation_enabled": { "description": "Specify whether to enable Clientless Browser Isolation.", "type": "boolean", "example": true, "x-auditable": true } }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_categories": { "type": "object", "properties": { "beta": { "$ref": "#/components/schemas/zero-trust-gateway_beta" }, "class": { "$ref": "#/components/schemas/zero-trust-gateway_class" }, "description": { "$ref": "#/components/schemas/zero-trust-gateway_description-3" }, "id": { "$ref": "#/components/schemas/zero-trust-gateway_id" }, "name": { "$ref": "#/components/schemas/zero-trust-gateway_name-5" }, "subcategories": { "description": "Provide all subcategories for this category.", "type": "array", "items": { "$ref": "#/components/schemas/zero-trust-gateway_subcategory" } } }, "readOnly": true }, "zero-trust-gateway_certificate-settings": { "description": "Specify certificate settings for Gateway TLS interception. If unset, the Cloudflare Root CA handles interception.", "type": "object", "properties": { "id": { "description": "Specify the UUID of the certificate used for interception. Ensure the certificate is available at the edge(previously called 'active'). A nil UUID directs Cloudflare to use the Root CA.", "type": "string", "example": "d1b364c5-1311-466e-a194-f0e943e0799f", "x-auditable": true } }, "nullable": true, "required": [ "id" ], "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_certificates": { "type": "object", "properties": { "binding_status": { "$ref": "#/components/schemas/zero-trust-gateway_binding_status" }, "certificate": { "description": "Provide the CA certificate (read-only).", "type": "string", "example": "-----BEGIN CERTIFICATE-----\\nMIIDmDCCAoCgAwIBAgIUKTOAZNjcXVZRj4oQt0SHsl1c1vMwDQYJKoZIhvcNAQELBQAwUTELMAkGA1UEBhMCVVMxFjAUBgNVBAgMDVNhbiBGcmFuY2lzY28xEzARBgNVBAcMCkNhbGlmb3JuaWExFTATBgNVBAoMDEV4YW1wbGUgSW5jLjAgFw0yMjExMjIxNjU5NDdaGA8yMTIyMTAyOTE2NTk0N1owUTELMAkGA1UEBhMCVVMxFjAUBgNVBAgMDVNhbiBGcmFuY2lzY28xEzARBgNVBAcMCkNhbGlmb3JuaWExFTATBgNVBAoMDEV4YW1wbGUgSW5jLjCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMRcORwgJFTdcG/2GKI+cFYiOBNDKjCZUXEOvXWY42BkH9wxiMT869CO+enA1w5pIrXow6kCM1sQspHHaVmJUlotEMJxyoLFfA/8Kt1EKFyobOjuZs2SwyVyJ2sStvQuUQEosULZCNGZEqoH5g6zhMPxaxm7ZLrrsDZ9maNGVqo7EWLWHrZ57Q/5MtTrbxQL+eXjUmJ9K3kS+3uEwMdqR6Z3BluU1ivanpPc1CN2GNhdO0/hSY4YkGEnuLsqJyDd3cIiB1MxuCBJ4ZaqOd2viV1WcP3oU3dxVPm4MWyfYIldMWB14FahScxLhWdRnM9YZ/i9IFcLypXsuz7DjrJPtPUCAwEAAaNmMGQwHQYDVR0OBBYEFP5JzLUawNF+c3AXsYTEWHh7z2czMB8GA1UdIwQYMBaAFP5JzLUawNF+c3AXsYTEWHh7z2czMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/AgEBMA0GCSqGSIb3DQEBCwUAA4IBAQBc+Be7NDhpE09y7hLPZGRPl1cSKBw4RI0XIv6rlbSTFs5EebpTGjhx/whNxwEZhB9HZ7111Oa1YlT8xkI9DshB78mjAHCKBAJ76moK8tkG0aqdYpJ4ZcJTVBB7l98Rvgc7zfTii7WemTy72deBbSeiEtXavm4EF0mWjHhQ5Nxpnp00Bqn5g1x8CyTDypgmugnep+xG+iFzNmTdsz7WI9T/7kDMXqB7M/FPWBORyS98OJqNDswCLF8bIZYwUBEe+bRHFomoShMzaC3tvim7WCb16noDkSTMlfKO4pnvKhpcVdSgwcruATV7y+W+Lvmz2OT/Gui4JhqeoTewsxndhDDE\\n-----END CERTIFICATE-----\\n", "readOnly": true }, "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "expires_on": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "fingerprint": { "description": "Provide the SHA256 fingerprint of the certificate (read-only).", "type": "string", "example": "E9:19:49:AA:DD:D8:1E:C1:20:2A:D8:22:BF:A5:F8:FC:1A:F7:10:9F:C7:5B:69:AB:0:31:91:8B:61:B4:BF:1C", "readOnly": true, "x-auditable": true }, "id": { "$ref": "#/components/schemas/zero-trust-gateway_uuid" }, "in_use": { "description": "Indicate whether Gateway TLS interception uses this certificate (read-only). You cannot set this value directly. To configure interception, use the Gateway configuration setting named `certificate` (read-only).", "type": "boolean", "readOnly": true, "x-stainless-terraform-configurability": "computed" }, "issuer_org": { "description": "Indicate the organization that issued the certificate (read-only).", "type": "string", "example": "Example Inc.", "readOnly": true, "x-auditable": true }, "issuer_raw": { "description": "Provide the entire issuer field of the certificate (read-only).", "type": "string", "example": "O=Example Inc.,L=California,ST=San Francisco,C=US", "readOnly": true, "x-auditable": true }, "type": { "$ref": "#/components/schemas/zero-trust-gateway_type" }, "updated_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "uploaded_on": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" } } }, "zero-trust-gateway_cf_account_id": { "description": "Specify the Cloudflare account ID.", "type": "string", "example": "699d98642c564d2e855e9661899b7252", "maxLength": 32 }, "zero-trust-gateway_class": { "description": "Specify which account types can create policies for this category. `blocked` Blocks unconditionally for all accounts. `removalPending` Allows removal from policies but disables addition. `noBlock` Prevents blocking.", "type": "string", "example": "premium", "enum": [ "free", "premium", "blocked", "removalPending", "noBlock" ], "x-auditable": true }, "zero-trust-gateway_client-default": { "description": "Indicate whether this location is the default location.", "type": "boolean", "example": false, "default": false, "x-auditable": true }, "zero-trust-gateway_contents": { "description": "Actual contents of the PAC file", "type": "string", "example": "function FindProxyForURL(url, host) { return \"DIRECT\"; }", "x-auditable": true }, "zero-trust-gateway_count": { "description": "Indicate the number of items in the list.", "type": "number", "example": 20, "readOnly": true, "x-stainless-terraform-configurability": "computed" }, "zero-trust-gateway_csv_operation": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "data": { "$ref": "#/components/schemas/zero-trust-gateway_csv_operation_data" }, "id": { "$ref": "#/components/schemas/zero-trust-gateway_uuid-2" }, "operation_type": { "description": "The type of operation.", "type": "string", "example": "create_list", "enum": [ "create_list" ] }, "processing_error": { "description": "A human-readable error message if the operation failed. Only present when the operation status is `failed`.", "type": "string", "nullable": true }, "result": { "description": "The result of the operation. Only present when the operation has completed successfully.", "type": "string", "nullable": true }, "status": { "description": "The status of the operation.", "type": "string", "example": "pending", "enum": [ "pending", "active", "failed", "complete" ] }, "updated_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" } } }, "zero-trust-gateway_csv_operation_data": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/zero-trust-gateway_description" }, "list_type": { "$ref": "#/components/schemas/zero-trust-gateway_type-2" }, "name": { "$ref": "#/components/schemas/zero-trust-gateway_name" } } }, "zero-trust-gateway_csv_operation_single_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/zero-trust-gateway_csv_operation" } }, "type": "object" } ] }, "zero-trust-gateway_custom-certificate-settings": { "description": "Specify custom certificate settings for BYO-PKI. This field is deprecated; use `certificate` instead.", "type": "object", "properties": { "binding_status": { "description": "Indicate the internal certificate status.", "type": "string", "example": "pending_deployment", "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "enabled": { "description": "Specify whether to enable a custom certificate authority for signing Gateway traffic.", "type": "boolean", "example": true, "nullable": true, "x-auditable": true }, "id": { "description": "Specify the UUID of the certificate (ID from MTLS certificate store).", "type": "string", "example": "d1b364c5-1311-466e-a194-f0e943e0799f", "x-auditable": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "x-stainless-terraform-configurability": "computed" } }, "deprecated": true, "nullable": true, "required": [ "enabled" ], "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_deleted_at": { "description": "Indicate the date of deletion, if any.", "type": "string", "format": "date-time", "nullable": true, "readOnly": true, "x-stainless-terraform-configurability": "computed" }, "zero-trust-gateway_description": { "description": "Provide the list description.", "type": "string", "example": "The serial numbers for administrators", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "zero-trust-gateway_description-2": { "description": "Specify the rule description.", "type": "string", "example": "Block bad websites based on their host name.", "x-auditable": true }, "zero-trust-gateway_description-3": { "description": "Provide a short summary of domains in the category.", "type": "string", "example": "Sites related to educational content that are not included in other categories such as Science, Technology or Educational institutions.", "x-auditable": true }, "zero-trust-gateway_description-4": { "description": "Detailed description of the PAC file.", "type": "string", "example": "PAC file for Devops team", "x-auditable": true }, "zero-trust-gateway_description_item": { "description": "Provide the list item description (optional).", "type": "string", "example": "Austin office IP", "minimum": 0 }, "zero-trust-gateway_device_posture": { "description": "Specify the wirefilter expression used for device posture check. The API automatically formats and sanitizes expressions before storing them. To prevent Terraform state drift, use the formatted expression returned in the API response.", "type": "string", "example": "any(device_posture.checks.passed[*] in {\"1308749e-fcfb-4ebc-b051-fe022b632644\"})", "default": "", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "zero-trust-gateway_dns-destination-ips-id-read": { "description": "Indicate the identifier of the pair of IPv4 addresses assigned to this location.", "type": "string", "example": "0e4a32c6-6fb8-4858-9296-98f51631e8e6", "default": "0e4a32c6-6fb8-4858-9296-98f51631e8e6", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "zero-trust-gateway_dns-destination-ips-id-write": { "description": "Specify the identifier of the pair of IPv4 addresses assigned to this location. When creating a location, if this field is absent or set to null, the pair of shared IPv4 addresses (0e4a32c6-6fb8-4858-9296-98f51631e8e6) is auto-assigned. When updating a location, if this field is absent or set to null, the pre-assigned pair remains unchanged.", "type": "string", "example": "0e4a32c6-6fb8-4858-9296-98f51631e8e6", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "zero-trust-gateway_dns_destination_ip_pair": { "type": "object", "properties": { "backup_ip": { "type": "string", "example": "172.64.36.2", "x-auditable": true }, "id": { "type": "string", "example": "0e4a32c6-6fb8-4858-9296-98f51631e8e6", "x-auditable": true }, "pair_type": { "description": "Specify whether the pair shared across multiple accounts (shared) or available exclusively to this account. Non-shared pairs can contain Cloudflare-owned IPs (dedicated) or customer-provided IPs (byoip).", "example": "shared", "enum": [ "shared", "dedicated", "byoip" ], "x-auditable": true }, "primary_ip": { "type": "string", "example": "172.64.36.1", "x-auditable": true } }, "required": [ "id", "primary_ip", "backup_ip", "pair_type" ] }, "zero-trust-gateway_dns_destination_ipv6_block_id": { "description": "Specify the UUID of the IPv6 block brought to the gateway so that this location's IPv6 address is allocated from the Bring Your Own IPv6 (BYOIPv6) block rather than the standard Cloudflare IPv6 block.", "type": "string", "example": "b08f7231-d458-495c-98ef-190604c9ee83", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_dns_resolver_settings_v4": { "type": "object", "properties": { "ip": { "description": "Specify the IPv4 address of the upstream resolver.", "type": "string", "example": "2.2.2.2", "x-auditable": true }, "port": { "description": "Specify a port number to use for the upstream resolver. Defaults to 53 if unspecified.", "type": "integer", "example": 5053, "x-auditable": true }, "route_through_private_network": { "description": "Indicate whether to connect to this resolver over a private network. Must set when vnet_id set.", "type": "boolean", "example": true, "x-auditable": true }, "vnet_id": { "description": "Specify an optional virtual network for this resolver. Uses default virtual network id if omitted.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "x-auditable": true } }, "required": [ "ip" ], "x-stainless-terraform-configurability": "computed_optional" }, "zero-trust-gateway_dns_resolver_settings_v6": { "type": "object", "properties": { "ip": { "description": "Specify the IPv6 address of the upstream resolver.", "type": "string", "example": "2001:DB8::", "x-auditable": true }, "port": { "description": "Specify a port number to use for the upstream resolver. Defaults to 53 if unspecified.", "type": "integer", "example": 5053, "x-auditable": true }, "route_through_private_network": { "description": "Indicate whether to connect to this resolver over a private network. Must set when vnet_id set.", "type": "boolean", "example": true, "x-auditable": true }, "vnet_id": { "description": "Specify an optional virtual network for this resolver. Uses default virtual network id if omitted.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "x-auditable": true } }, "required": [ "ip" ], "x-stainless-terraform-configurability": "computed_optional" }, "zero-trust-gateway_doh_endpoint": { "type": "object", "properties": { "enabled": { "description": "Indicate whether the DOH endpoint is enabled for this location.", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "networks": { "$ref": "#/components/schemas/zero-trust-gateway_ip_networks" }, "require_token": { "description": "Specify whether the DOH endpoint requires user identity authentication.", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } } }, "zero-trust-gateway_dot_endpoint": { "type": "object", "properties": { "enabled": { "description": "Indicate whether the DOT endpoint is enabled for this location.", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "networks": { "$ref": "#/components/schemas/zero-trust-gateway_ip_networks" } } }, "zero-trust-gateway_ecs-support": { "description": "Indicate whether the location must resolve EDNS queries.", "type": "boolean", "example": false, "default": false, "x-auditable": true }, "zero-trust-gateway_empty_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-single" }, { "properties": { "result": { "type": "object" } }, "type": "object" } ] }, "zero-trust-gateway_enabled": { "description": "Specify whether the rule is enabled.", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "zero-trust-gateway_enabled_download_phase": { "description": "Specify whether to enable anti-virus scanning on downloads.", "type": "boolean", "example": false, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "zero-trust-gateway_enabled_upload_phase": { "description": "Specify whether to enable anti-virus scanning on uploads.", "type": "boolean", "example": false, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "zero-trust-gateway_endpoints": { "description": "Configure the destination endpoints for this location.", "type": "object", "properties": { "doh": { "$ref": "#/components/schemas/zero-trust-gateway_doh_endpoint" }, "dot": { "$ref": "#/components/schemas/zero-trust-gateway_dot_endpoint" }, "ipv4": { "$ref": "#/components/schemas/zero-trust-gateway_ipv4_endpoint" }, "ipv6": { "$ref": "#/components/schemas/zero-trust-gateway_ipv6_endpoint" } }, "nullable": true, "required": [ "ipv4", "ipv6", "doh", "dot" ], "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_expiration": { "description": "Defines the expiration time stamp and default duration of a DNS policy. Takes precedence over the policy's `schedule` configuration, if any. This does not apply to HTTP or network policies. Settable only for `dns` rules.", "type": "object", "properties": { "duration": { "description": "Defines the default duration a policy active in minutes. Must set in order to use the `reset_expiration` endpoint on this rule.", "type": "integer", "example": 10, "minimum": 5, "x-auditable": true }, "expired": { "description": "Indicates whether the policy is expired.", "type": "boolean", "example": false, "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "expires_at": { "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_timestamp" }, { "description": "Show the timestamp when the policy expires and stops applying. The value must follow RFC 3339 and include a UTC offset. The system accepts non-zero offsets but converts them to the equivalent UTC+00:00 value and returns timestamps with a trailing Z. Expiration policies ignore client timezones and expire globally at the specified expires_at time.", "example": "2014-01-01T05:20:20Z", "type": "string", "x-auditable": true } ] } }, "nullable": true, "required": [ "expires_at" ], "x-stainless-terraform-configurability": "computed_optional" }, "zero-trust-gateway_extended-email-matching": { "description": "Configures user email settings for firewall policies. When you enable this, the system standardizes email addresses in the identity portion of the rule to match extended email variants in firewall policies. When you disable this setting, the system matches email addresses exactly as you provide them. Enable this setting if your email uses `.` or `+` modifiers.", "type": "object", "properties": { "enabled": { "description": "Specify whether to match all variants of user emails (with + or . modifiers) used as criteria in Firewall policies.", "type": "boolean", "example": true, "nullable": true, "x-auditable": true }, "read_only": { "description": "Indicate that this setting was shared via the Orgs API and read only for the current account.", "type": "boolean", "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "source_account": { "description": "Indicate the account tag of the account that shared this setting.", "type": "string", "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "version": { "description": "Indicate the version number of the setting.", "type": "integer", "example": 1, "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" } }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_fail_closed": { "description": "Specify whether to block requests for unscannable files.", "type": "boolean", "example": false, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "zero-trust-gateway_filters": { "description": "Specify the protocol or layer to evaluate the traffic, identity, and device posture expressions. Can only contain a single value.", "type": "array", "items": { "description": "Specify the protocol or layer to use.", "enum": [ "http", "dns", "l4", "egress", "dns_resolver" ], "example": "http", "type": "string", "x-auditable": true }, "example": [ "http" ], "maxItems": 1, "minItems": 1 }, "zero-trust-gateway_fips-settings": { "description": "Specify FIPS settings.", "type": "object", "properties": { "tls": { "description": "Enforce cipher suites and TLS versions compliant with FIPS 140-2.", "type": "boolean", "example": true, "x-auditable": true } }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_gateway-account-egress-cidr": { "type": "object", "properties": { "geolocation": { "description": "Specify the geographic location of this CIDR pair.", "type": "object", "properties": { "city": { "description": "Specify the city of this egress IP.", "type": "string" }, "country": { "description": "Specify the country of this egress IP.", "type": "string" } } }, "ipv4": { "description": "Specify the IPv4 address of this egress CIDR pair.", "type": "string" }, "ipv4_colo_name": { "description": "Specify the colocation from which this IPv4 address egresses.", "type": "string" }, "ipv6_cidr": { "description": "Specify the IPv6 network address of this egress CIDR pair.", "type": "string" } }, "required": [ "ipv4", "ipv4_colo_name", "ipv6_cidr", "geolocation" ] }, "zero-trust-gateway_gateway-account-egress-cidr-pair-list-response": { "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-single" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/zero-trust-gateway_gateway-account-egress-cidr" } } }, "type": "object" } ] }, "zero-trust-gateway_gateway-account-logging-settings": { "type": "object", "properties": { "redact_pii": { "description": "Indicate whether to redact personally identifiable information from activity logging (PII fields include source IP, user email, user ID, device ID, URL, referrer, and user agent).", "type": "boolean", "example": true, "default": false, "x-auditable": true }, "settings_by_rule_type": { "description": "Configure logging settings for each rule type.", "type": "object", "properties": { "dns": { "description": "Configure logging settings for DNS firewall.", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_account-log-options" } ] }, "http": { "description": "Configure logging settings for HTTP/HTTPS firewall.", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_account-log-options" } ] }, "l4": { "description": "Configure logging settings for Network firewall.", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_account-log-options" } ] } } } } }, "zero-trust-gateway_gateway-account-logging-settings-response": { "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/zero-trust-gateway_gateway-account-logging-settings" } }, "type": "object" } ] }, "zero-trust-gateway_gateway-account-settings": { "description": "Specify account settings.", "properties": { "settings": { "description": "Specify account settings.", "type": "object", "properties": { "activity_log": { "$ref": "#/components/schemas/zero-trust-gateway_activity-log-settings" }, "antivirus": { "$ref": "#/components/schemas/zero-trust-gateway_anti-virus-settings" }, "block_page": { "$ref": "#/components/schemas/zero-trust-gateway_block-page-settings" }, "body_scanning": { "$ref": "#/components/schemas/zero-trust-gateway_body-scanning-settings" }, "browser_isolation": { "$ref": "#/components/schemas/zero-trust-gateway_browser-isolation-settings" }, "certificate": { "$ref": "#/components/schemas/zero-trust-gateway_certificate-settings" }, "custom_certificate": { "$ref": "#/components/schemas/zero-trust-gateway_custom-certificate-settings" }, "extended_email_matching": { "$ref": "#/components/schemas/zero-trust-gateway_extended-email-matching" }, "fips": { "$ref": "#/components/schemas/zero-trust-gateway_fips-settings" }, "host_selector": { "$ref": "#/components/schemas/zero-trust-gateway_host-selector-settings" }, "inspection": { "$ref": "#/components/schemas/zero-trust-gateway_inspection-settings" }, "max_ttl_secs": { "$ref": "#/components/schemas/zero-trust-gateway_max-ttl-secs" }, "protocol_detection": { "$ref": "#/components/schemas/zero-trust-gateway_protocol-detection" }, "sandbox": { "$ref": "#/components/schemas/zero-trust-gateway_sandbox" }, "tls_decrypt": { "$ref": "#/components/schemas/zero-trust-gateway_tls-settings" } } } } }, "zero-trust-gateway_gateway_account": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "gateway_tag": { "$ref": "#/components/schemas/zero-trust-gateway_gateway_tag" }, "id": { "$ref": "#/components/schemas/zero-trust-gateway_cf_account_id" }, "provider_name": { "$ref": "#/components/schemas/zero-trust-gateway_provider_name" } } } }, "type": "object" } ] }, "zero-trust-gateway_gateway_account_config": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-single" }, { "properties": { "result": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_gateway-account-settings" }, { "properties": { "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "updated_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" } }, "type": "object" } ] } }, "type": "object" } ] }, "zero-trust-gateway_gateway_tag": { "description": "Specify the gateway internal ID.", "type": "string", "example": "f174e90afafe4643bbbc4a0ed4fc8415", "maxLength": 32 }, "zero-trust-gateway_generate-cert-request": { "type": "object", "properties": { "validity_period_days": { "description": "Sets the certificate validity period in days (range: 1-10,950 days / ~30 years). Defaults to 1,825 days (5 years). **Important**: This field is only settable during the certificate creation. Certificates becomes immutable after creation - use the `/activate` and `/deactivate` endpoints to manage certificate lifecycle.", "type": "integer", "example": 1826, "x-auditable": true } } }, "zero-trust-gateway_host-selector-settings": { "description": "Enable host selection in egress policies.", "type": "object", "properties": { "enabled": { "description": "Specify whether to enable filtering via hosts for egress policies.", "type": "boolean", "example": false, "nullable": true, "x-auditable": true } }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_id": { "description": "Identify this category. Only one category per ID.", "type": "integer", "x-auditable": true }, "zero-trust-gateway_identifier": { "type": "string", "example": "699d98642c564d2e855e9661899b7252" }, "zero-trust-gateway_identifier-2": { "type": "string", "example": "699d98642c564d2e855e9661899b7252", "x-auditable": true }, "zero-trust-gateway_identifier-3": { "description": "Provide the identifier string.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "zero-trust-gateway_identity": { "description": "Specify the wirefilter expression used for identity matching. The API automatically formats and sanitizes expressions before storing them. To prevent Terraform state drift, use the formatted expression returned in the API response.", "type": "string", "example": "any(identity.groups.name[*] in {\"finance\"})", "default": "", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "zero-trust-gateway_in_review_apps": { "description": "Contains the ids of the applications in review.", "type": "array", "items": { "type": "integer" }, "x-stainless-collection-type": "set" }, "zero-trust-gateway_inspection-settings": { "description": "Define the proxy inspection mode.", "type": "object", "properties": { "mode": { "description": "Define the proxy inspection mode. 1. static: Gateway applies static inspection to HTTP on TCP(80). With TLS decryption on, Gateway inspects HTTPS traffic on TCP(443) and UDP(443). 2. dynamic: Gateway applies protocol detection to inspect HTTP and HTTPS traffic on any port. TLS decryption must remain on to inspect HTTPS traffic.", "type": "string", "example": "static", "enum": [ "static", "dynamic" ], "x-auditable": true } }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_ip": { "description": "Defines the automatically generated IPv6 destination IP assigned to this location. Gateway counts all DNS requests sent to this IP as requests under this location.", "type": "string", "example": "2001:0db8:85a3:0000:0000:8a2e:0370:7334", "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "zero-trust-gateway_ip_network": { "type": "object", "properties": { "network": { "description": "Specify the IP address or IP CIDR.", "type": "string", "example": "2001:85a3::/64", "x-auditable": true } }, "required": [ "network" ] }, "zero-trust-gateway_ip_networks": { "description": "Specify the list of allowed source IP network ranges for this endpoint. When the list is empty, the endpoint allows all source IPs. The list takes effect only if the endpoint is enabled for this location.", "type": "array", "items": { "$ref": "#/components/schemas/zero-trust-gateway_ip_network" }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_ips": { "description": "Specify the list of CIDRs to restrict ingress connections.", "type": "array", "items": { "description": "Specify an IPv4 or IPv6 CIDR. Limit IPv6 to a maximum of /109 and IPv4 to a maximum of /25.", "example": "192.0.2.1/32", "type": "string", "x-auditable": true } }, "zero-trust-gateway_ipv4_endpoint": { "type": "object", "properties": { "enabled": { "description": "Indicate whether the IPv4 endpoint is enabled for this location.", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" } } }, "zero-trust-gateway_ipv4_network": { "type": "object", "properties": { "network": { "description": "Specify the IPv4 address or IPv4 CIDR. Limit IPv4 CIDRs to a maximum of /24.", "type": "string", "example": "192.0.2.1/32", "x-auditable": true } }, "required": [ "network" ] }, "zero-trust-gateway_ipv4_networks": { "description": "Specify the list of network ranges from which requests at this location originate. The list takes effect only if it is non-empty and the IPv4 endpoint is enabled for this location.", "type": "array", "items": { "$ref": "#/components/schemas/zero-trust-gateway_ipv4_network" }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_ipv6_endpoint": { "type": "object", "properties": { "enabled": { "description": "Indicate whether the IPV6 endpoint is enabled for this location.", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "networks": { "$ref": "#/components/schemas/zero-trust-gateway_ipv6_networks" } } }, "zero-trust-gateway_ipv6_network": { "type": "object", "properties": { "network": { "description": "Specify the IPv6 address or IPv6 CIDR.", "type": "string", "example": "2001:85a3::/64", "x-auditable": true } }, "required": [ "network" ] }, "zero-trust-gateway_ipv6_networks": { "description": "Specify the list of allowed source IPv6 network ranges for this endpoint. When the list is empty, the endpoint allows all source IPs. The list takes effect only if the endpoint is enabled for this location.", "type": "array", "items": { "$ref": "#/components/schemas/zero-trust-gateway_ipv6_network" }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_items": { "description": "Provide the list items.", "type": "array", "items": { "properties": { "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "description": { "$ref": "#/components/schemas/zero-trust-gateway_description_item" }, "value": { "$ref": "#/components/schemas/zero-trust-gateway_value" } }, "type": "object" }, "x-stainless-collection-type": "set" }, "zero-trust-gateway_items-input": { "description": "Add items to the list.", "type": "array", "items": { "properties": { "description": { "$ref": "#/components/schemas/zero-trust-gateway_description_item" }, "value": { "$ref": "#/components/schemas/zero-trust-gateway_value" } }, "type": "object" }, "x-stainless-collection-type": "set" }, "zero-trust-gateway_list_item_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-collection" }, { "properties": { "result": { "$ref": "#/components/schemas/zero-trust-gateway_items" } }, "type": "object" }, { "properties": { "result_info": { "type": "object", "properties": { "count": { "description": "Shows the total results returned based on your search parameters.", "type": "number", "example": 1 }, "page": { "description": "Show the current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Show the number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Show the total results available without any search parameters.", "type": "number", "example": 2000 } } } }, "type": "object" } ] }, "zero-trust-gateway_list_single_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/zero-trust-gateway_lists" } }, "type": "object" } ], "x-auditable": true }, "zero-trust-gateway_lists": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/zero-trust-gateway_count" }, "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "description": { "$ref": "#/components/schemas/zero-trust-gateway_description" }, "id": { "$ref": "#/components/schemas/zero-trust-gateway_uuid-2" }, "items": { "$ref": "#/components/schemas/zero-trust-gateway_items" }, "name": { "$ref": "#/components/schemas/zero-trust-gateway_name" }, "type": { "$ref": "#/components/schemas/zero-trust-gateway_type-2" }, "updated_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" } } }, "zero-trust-gateway_locations": { "type": "object", "properties": { "client_default": { "$ref": "#/components/schemas/zero-trust-gateway_client-default" }, "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "dns_destination_ips_id": { "$ref": "#/components/schemas/zero-trust-gateway_dns-destination-ips-id-read" }, "dns_destination_ipv6_block_id": { "$ref": "#/components/schemas/zero-trust-gateway_dns_destination_ipv6_block_id" }, "doh_subdomain": { "$ref": "#/components/schemas/zero-trust-gateway_subdomain" }, "ecs_support": { "$ref": "#/components/schemas/zero-trust-gateway_ecs-support" }, "endpoints": { "$ref": "#/components/schemas/zero-trust-gateway_endpoints" }, "id": { "$ref": "#/components/schemas/zero-trust-gateway_uuid-3" }, "ip": { "$ref": "#/components/schemas/zero-trust-gateway_ip" }, "ipv4_destination": { "description": "Show the primary destination IPv4 address from the pair identified dns_destination_ips_id. This field read-only.", "type": "string", "example": "172.64.36.1", "readOnly": true, "x-stainless-terraform-configurability": "computed" }, "ipv4_destination_backup": { "description": "Show the backup destination IPv4 address from the pair identified dns_destination_ips_id. This field read-only.", "type": "string", "example": "172.64.36.2", "readOnly": true, "x-stainless-terraform-configurability": "computed" }, "max_ttl": { "$ref": "#/components/schemas/zero-trust-gateway_max-ttl" }, "name": { "$ref": "#/components/schemas/zero-trust-gateway_name-2" }, "networks": { "$ref": "#/components/schemas/zero-trust-gateway_ipv4_networks" }, "updated_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" } } }, "zero-trust-gateway_max-ttl": { "description": "Controls how DNS response TTLs are capped for this location relative to the account `max_ttl_secs` setting. Omitting `max_ttl` on update resets it to `inherit`.", "type": "object", "properties": { "mode": { "description": "`inherit` uses the account `max_ttl_secs`. `override` uses this location's `ttl_secs`. `disabled` leaves returned TTLs unchanged.", "type": "string", "example": "override", "enum": [ "inherit", "override", "disabled" ], "x-auditable": true }, "ttl_secs": { "description": "Location-specific cap on DNS response TTLs, in seconds. Required when `mode` is `override`. Must be omitted when `mode` is `inherit` or `disabled`.", "type": "integer", "example": 3600, "maximum": 36000, "minimum": 60, "nullable": true, "x-auditable": true } }, "default": { "mode": "inherit" }, "nullable": true, "required": [ "mode" ], "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_max-ttl-secs": { "description": "Account-level cap on DNS response TTLs, in seconds. Gateway rewrites DNS responses so returned record TTLs do not exceed this value. Null means no cap. Each DNS location can inherit, override, or disable it through the location `max_ttl` setting.", "type": "integer", "example": 3600, "maximum": 36000, "minimum": 60, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "zero-trust-gateway_name": { "description": "Specify the list name.", "type": "string", "example": "Admin Serial Numbers", "x-auditable": true }, "zero-trust-gateway_name-2": { "description": "Specify the location name.", "type": "string", "example": "Austin Office Location", "x-auditable": true }, "zero-trust-gateway_name-3": { "description": "Specify the rule name.", "type": "string", "example": "block bad websites", "x-auditable": true }, "zero-trust-gateway_name-4": { "description": "Specify the name of the application or application type.", "type": "string", "example": "Facebook", "x-auditable": true }, "zero-trust-gateway_name-5": { "description": "Specify the category name.", "type": "string", "example": "Education" }, "zero-trust-gateway_name-6": { "description": "Specify the name of the proxy endpoint.", "type": "string", "example": "Devops team", "x-auditable": true }, "zero-trust-gateway_name-7": { "description": "Name of the PAC file.", "type": "string", "example": "Devops team", "x-auditable": true }, "zero-trust-gateway_notification_settings": { "description": "Configure the message the user's device shows during an antivirus scan.", "type": "object", "properties": { "enabled": { "description": "Specify whether to enable notifications.", "type": "boolean", "x-auditable": true }, "include_context": { "description": "Specify whether to include context information as query parameters.", "type": "boolean", "x-auditable": true }, "msg": { "description": "Specify the message to show in the notification.", "type": "string", "x-auditable": true }, "support_url": { "description": "Specify a URL that directs users to more information. If unset, the notification opens a block page.", "type": "string", "x-auditable": true } }, "nullable": true, "x-stainless-terraform-configurability": "computed_optional" }, "zero-trust-gateway_operation": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "data": { "$ref": "#/components/schemas/zero-trust-gateway_operation_data" }, "id": { "$ref": "#/components/schemas/zero-trust-gateway_uuid-2" }, "operation_type": { "description": "The type of operation.", "type": "string", "example": "create_list", "enum": [ "create_list" ] }, "processing_error": { "description": "A human-readable error message if the operation failed. Only present when the operation status is `failed`.", "type": "string", "nullable": true }, "result": { "description": "The result of the operation. Only present when the operation has completed successfully.", "type": "string", "nullable": true }, "status": { "description": "The status of the operation.", "type": "string", "example": "pending", "enum": [ "pending", "active", "failed", "complete" ] }, "updated_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" } }, "readOnly": true }, "zero-trust-gateway_operation_data": { "description": "Provide metadata describing the resource the operation acts on. The fields present depend on the `operation_type`.", "type": "object" }, "zero-trust-gateway_pacfile": { "type": "object", "properties": { "contents": { "$ref": "#/components/schemas/zero-trust-gateway_contents" }, "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "description": { "$ref": "#/components/schemas/zero-trust-gateway_description-4" }, "id": { "$ref": "#/components/schemas/zero-trust-gateway_uuid-3" }, "name": { "$ref": "#/components/schemas/zero-trust-gateway_name-7" }, "slug": { "$ref": "#/components/schemas/zero-trust-gateway_slug" }, "updated_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "url": { "$ref": "#/components/schemas/zero-trust-gateway_url" } } }, "zero-trust-gateway_precedence": { "description": "Set the order of your rules. Lower values indicate higher precedence. At each processing phase, evaluate applicable rules in ascending order of this value. Refer to [Order of enforcement](http://developers.cloudflare.com/learning-paths/secure-internet-traffic/understand-policies/order-of-enforcement/#manage-precedence-with-terraform) to manage precedence via Terraform.", "type": "integer", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "zero-trust-gateway_protocol-detection": { "description": "Specify whether to detect protocols from the initial bytes of client traffic.", "type": "object", "properties": { "enabled": { "description": "Specify whether to detect protocols from the initial bytes of client traffic.", "type": "boolean", "example": true, "nullable": true, "x-auditable": true } }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_provider_name": { "description": "Specify the provider name (usually Cloudflare).", "type": "string", "example": "Cloudflare" }, "zero-trust-gateway_proxy-endpoint-identity": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "id": { "$ref": "#/components/schemas/zero-trust-gateway_uuid-3" }, "kind": { "description": "The proxy endpoint kind", "type": "string", "example": "identity", "enum": [ "identity" ], "x-auditable": true }, "name": { "$ref": "#/components/schemas/zero-trust-gateway_name-6" }, "subdomain": { "$ref": "#/components/schemas/zero-trust-gateway_subdomain-2" }, "updated_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" } }, "required": [ "kind", "name" ] }, "zero-trust-gateway_proxy-endpoint-identity-create": { "type": "object", "properties": { "kind": { "description": "The proxy endpoint kind", "type": "string", "example": "identity", "enum": [ "identity" ], "x-auditable": true }, "name": { "$ref": "#/components/schemas/zero-trust-gateway_name-6" } }, "required": [ "kind", "name" ] }, "zero-trust-gateway_proxy-endpoint-ip": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "id": { "$ref": "#/components/schemas/zero-trust-gateway_uuid-3" }, "ips": { "$ref": "#/components/schemas/zero-trust-gateway_ips" }, "kind": { "description": "The proxy endpoint kind", "type": "string", "example": "ip", "enum": [ "ip" ], "x-auditable": true }, "name": { "$ref": "#/components/schemas/zero-trust-gateway_name-6" }, "subdomain": { "$ref": "#/components/schemas/zero-trust-gateway_subdomain-2" }, "updated_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" } }, "required": [ "name", "ips" ] }, "zero-trust-gateway_proxy-endpoint-ip-create": { "type": "object", "properties": { "kind": { "description": "The proxy endpoint kind", "type": "string", "example": "ip", "enum": [ "ip" ], "x-auditable": true }, "name": { "$ref": "#/components/schemas/zero-trust-gateway_name-6" } }, "required": [ "name", "ips" ] }, "zero-trust-gateway_proxy-endpoints": { "discriminator": { "mapping": { "identity": "#/components/schemas/zero-trust-gateway_proxy-endpoint-identity", "ip": "#/components/schemas/zero-trust-gateway_proxy-endpoint-ip" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_proxy-endpoint-ip" }, { "$ref": "#/components/schemas/zero-trust-gateway_proxy-endpoint-identity" } ] }, "zero-trust-gateway_public_key": { "description": "Provide the Base64-encoded HPKE public key that encrypts SSH session logs. See https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/use-cases/ssh/ssh-infrastructure-access/#enable-ssh-command-logging.", "type": "string", "example": "1pyl6I1tL7xfJuFYVzXlUW8uXXlpxegHXBzGCBKaSFA=", "x-auditable": true }, "zero-trust-gateway_read_only": { "description": "Indicate that this rule is shared via the Orgs API and read only.", "type": "boolean", "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "zero-trust-gateway_read_only_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true }, "zero-trust-gateway_response_collection": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/zero-trust-gateway_certificates" } } }, "type": "object" } ] }, "zero-trust-gateway_response_collection-10": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "properties": { "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "description": { "$ref": "#/components/schemas/zero-trust-gateway_description-4" }, "id": { "$ref": "#/components/schemas/zero-trust-gateway_uuid-3" }, "name": { "$ref": "#/components/schemas/zero-trust-gateway_name-7" }, "slug": { "$ref": "#/components/schemas/zero-trust-gateway_slug" }, "updated_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "url": { "$ref": "#/components/schemas/zero-trust-gateway_url" } }, "type": "object" } } }, "type": "object" } ] }, "zero-trust-gateway_response_collection-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/zero-trust-gateway_dns_destination_ip_pair" } } }, "type": "object" } ] }, "zero-trust-gateway_response_collection-3": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/zero-trust-gateway_lists" } } }, "type": "object" } ] }, "zero-trust-gateway_response_collection-4": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/zero-trust-gateway_operation" } } }, "type": "object" } ] }, "zero-trust-gateway_response_collection-5": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/zero-trust-gateway_locations" } } }, "type": "object" } ] }, "zero-trust-gateway_response_collection-6": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/zero-trust-gateway_rules" } } }, "type": "object" } ] }, "zero-trust-gateway_response_collection-7": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/zero-trust-gateway_app-types" } } }, "type": "object" } ] }, "zero-trust-gateway_response_collection-8": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/zero-trust-gateway_categories" } } }, "type": "object" } ] }, "zero-trust-gateway_response_collection-9": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/zero-trust-gateway_proxy-endpoints" } } }, "type": "object" } ] }, "zero-trust-gateway_result_info": { "type": "object", "properties": { "count": { "description": "Indicate the total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Indicate the current page within a paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Indicate the number of results per page.", "type": "number", "example": 20 }, "total_count": { "description": "Indicate the total results available without any search parameters.", "type": "number", "example": 2000 } } }, "zero-trust-gateway_rule-settings": { "description": "Defines settings for this rule. Settings apply only to specific rule types and must use compatible selectors. If Terraform detects drift, confirm the setting supports your rule type and check whether the API modifies the value. Use API-returned values in your configuration to prevent drift.", "type": "object", "properties": { "add_headers": { "description": "Add custom headers to allowed requests as key-value pairs. Use header names as keys that map to arrays of header values. Header values may contain `@{selector.name}` variable references that are interpolated at the edge. Use `@@{` to escape a literal `@{`. A maximum of 20 header operations (add + set + delete) is allowed per policy. Each header name may not exceed 256 bytes and each header value may not exceed 4 KB. Settable only for `http` rules with the action set to `allow`.", "type": "object", "example": { "My-Next-Header": [ "foo", "bar" ], "X-Custom-Header-Name": [ "somecustomvalue" ] }, "additionalProperties": { "items": { "type": "string" }, "type": "array", "x-auditable": true }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "allow_child_bypass": { "description": "Set to enable MSP children to bypass this rule. Only parent MSP accounts can set this. this rule. Settable for all types of rules.", "type": "boolean", "example": false, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "optional" }, "audit_ssh": { "description": "Define the settings for the Audit SSH action. Settable only for `l4` rules with `audit_ssh` action.", "type": "object", "nullable": true, "properties": { "command_logging": { "description": "Enable SSH command logging.", "type": "boolean", "example": false, "x-auditable": true } }, "x-stainless-terraform-configurability": "optional" }, "biso_admin_controls": { "description": "Configure browser isolation behavior. Settable only for `http` rules with the action set to `isolate`.", "type": "object", "properties": { "copy": { "description": "Configure copy behavior. If set to remote_only, users cannot copy isolated content from the remote browser to the local clipboard. If this field is absent, copying remains enabled. Applies only when version == \"v2\".", "type": "string", "example": "remote_only", "enum": [ "enabled", "disabled", "remote_only" ], "x-auditable": true }, "dcp": { "description": "Set to false to enable copy-pasting. Only applies when `version == \"v1\"`.", "type": "boolean", "x-auditable": true }, "dd": { "description": "Set to false to enable downloading. Only applies when `version == \"v1\"`.", "type": "boolean", "x-auditable": true }, "dk": { "description": "Set to false to enable keyboard usage. Only applies when `version == \"v1\"`.", "type": "boolean", "x-auditable": true }, "download": { "description": "Configure download behavior. When set to remote_only, users can view downloads but cannot save them. If this field is absent, downloading remains enabled. Applies only when version == \"v2\".", "type": "string", "example": "enabled", "enum": [ "enabled", "disabled", "remote_only" ], "x-auditable": true }, "dp": { "description": "Set to false to enable printing. Only applies when `version == \"v1\"`.", "type": "boolean", "example": false, "x-auditable": true }, "du": { "description": "Set to false to enable uploading. Only applies when `version == \"v1\"`.", "type": "boolean", "x-auditable": true }, "keyboard": { "description": "Configure keyboard usage behavior. If this field is absent, keyboard usage remains enabled. Applies only when version == \"v2\".", "type": "string", "example": "enabled", "enum": [ "enabled", "disabled" ], "x-auditable": true }, "paste": { "description": "Configure paste behavior. If set to remote_only, users cannot paste content from the local clipboard into isolated pages. If this field is absent, pasting remains enabled. Applies only when version == \"v2\".", "type": "string", "example": "enabled", "enum": [ "enabled", "disabled", "remote_only" ], "x-auditable": true }, "printing": { "description": "Configure print behavior. Default, Printing is enabled. Applies only when version == \"v2\".", "type": "string", "example": "enabled", "enum": [ "enabled", "disabled" ], "x-auditable": true }, "upload": { "description": "Configure upload behavior. If this field is absent, uploading remains enabled. Applies only when version == \"v2\".", "type": "string", "example": "enabled", "enum": [ "enabled", "disabled" ], "x-auditable": true }, "version": { "description": "Indicate which version of the browser isolation controls should apply.", "type": "string", "default": "v1", "enum": [ "v1", "v2" ], "x-auditable": true }, "wm_id": { "description": "Specify the watermark ID (UUID) to apply to the isolated browser session. When present, enables watermark rendering in the isolated browser.", "type": "string", "format": "uuid", "example": "475345dc-5299-4b6e-8f6a-3d3e4c8e9f1a", "maxLength": 36, "minLength": 1, "x-auditable": true } }, "x-stainless-terraform-configurability": "optional" }, "block_page": { "description": "Configure custom block page settings. If missing or null, use the account settings. Settable only for `http` rules with the action set to `block`.", "type": "object", "nullable": true, "properties": { "include_context": { "description": "Specify whether to pass the context information as query parameters.", "type": "boolean", "x-auditable": true }, "target_uri": { "description": "Specify the URI to which the user is redirected.", "type": "string", "format": "uri", "x-auditable": true } }, "required": [ "target_uri" ], "x-stainless-terraform-configurability": "optional" }, "block_page_enabled": { "description": "Enable the custom block page. Settable only for `dns` rules with action `block`.", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "optional" }, "block_reason": { "description": "Explain why the rule blocks the request. The custom block page shows this text (if enabled). Settable only for `dns`, `l4`, and `http` rules when the action set to `block`.", "type": "string", "example": "This website is a security risk", "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "optional" }, "bypass_parent_rule": { "description": "Set to enable MSP accounts to bypass their parent's rules. Only MSP child accounts can set this. Settable for all types of rules.", "type": "boolean", "example": false, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "optional" }, "check_session": { "description": "Configure session check behavior. Settable only for `l4` and `http` rules with the action set to `allow`.", "type": "object", "nullable": true, "properties": { "duration": { "description": "Sets the required session freshness threshold. The API returns a normalized version of this value.", "type": "string", "example": "300s", "x-auditable": true }, "enforce": { "description": "Enable session enforcement.", "type": "boolean", "example": true, "x-auditable": true } }, "x-stainless-terraform-configurability": "optional" }, "delete_headers": { "description": "Remove headers from allowed requests by name. A maximum of 20 header operations (add + set + delete) is allowed per policy. Each header name may not exceed 256 bytes. Settable only for `http` rules with the action set to `allow`.", "type": "array", "items": { "type": "string", "x-auditable": true }, "example": [ "X-Old-Header", "X-Remove-Me" ], "nullable": true, "x-stainless-terraform-configurability": "optional" }, "dns_resolvers": { "description": "Configure custom resolvers to route queries that match the resolver policy. Unused with 'resolve_dns_through_cloudflare' or 'resolve_dns_internally' settings. DNS queries get routed to the address closest to their origin. Only valid when a rule's action set to 'resolve'. Settable only for `dns_resolver` rules.", "type": "object", "nullable": true, "properties": { "ipv4": { "type": "array", "items": { "$ref": "#/components/schemas/zero-trust-gateway_dns_resolver_settings_v4" } }, "ipv6": { "type": "array", "items": { "$ref": "#/components/schemas/zero-trust-gateway_dns_resolver_settings_v6" } } }, "x-stainless-terraform-configurability": "optional" }, "egress": { "description": "Configure how Gateway Proxy traffic egresses. You can enable this setting for rules with Egress actions and filters, or omit it to indicate local egress via WARP IPs. Settable only for `egress` rules.", "type": "object", "nullable": true, "properties": { "ipv4": { "description": "Specify the IPv4 address to use for egress.", "type": "string", "example": "192.0.2.2", "x-auditable": true }, "ipv4_fallback": { "description": "Specify the fallback IPv4 address to use for egress when the primary IPv4 fails. Set '0.0.0.0' to indicate local egress via WARP IPs.", "type": "string", "example": "192.0.2.3", "x-auditable": true }, "ipv6": { "description": "Specify the IPv6 range to use for egress.", "type": "string", "example": "2001:DB8::/64", "x-auditable": true } }, "x-stainless-terraform-configurability": "optional" }, "forensic_copy": { "description": "Configure whether a copy of the HTTP request will be sent to storage when the rule matches.", "type": "object", "nullable": true, "properties": { "enabled": { "description": "Enable sending the copy to storage.", "type": "boolean", "x-auditable": true } }, "x-stainless-terraform-configurability": "optional" }, "ignore_cname_category_matches": { "description": "Ignore category matches at CNAME domains in a response. When off, evaluate categories in this rule against all CNAME domain categories in the response. Settable only for `dns` and `dns_resolver` rules.", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "optional" }, "insecure_disable_dnssec_validation": { "description": "Specify whether to disable DNSSEC validation (for Allow actions) [INSECURE]. Settable only for `dns` rules.", "type": "boolean", "example": false, "x-auditable": true, "x-stainless-terraform-configurability": "optional" }, "ip_categories": { "description": "Enable IPs in DNS resolver category blocks. The system blocks only domain name categories unless you enable this setting. Settable only for `dns` and `dns_resolver` rules.", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "optional" }, "ip_indicator_feeds": { "description": "Indicates whether to include IPs in DNS resolver indicator feed blocks. Default, indicator feeds block only domain names. Settable only for `dns` and `dns_resolver` rules.", "type": "boolean", "example": true, "x-auditable": true, "x-stainless-terraform-configurability": "optional" }, "l4override": { "description": "Send matching traffic to the supplied destination IP address and port. Settable only for `l4` rules with the action set to `l4_override`.", "type": "object", "nullable": true, "properties": { "ip": { "description": "Defines the IPv4 or IPv6 address.", "type": "string", "example": "1.1.1.1", "x-auditable": true }, "port": { "description": "Defines a port number to use for TCP/UDP overrides.", "type": "integer", "x-auditable": true } }, "x-stainless-terraform-configurability": "optional" }, "notification_settings": { "description": "Configure a notification to display on the user's device when this rule matched. Settable for all types of rules with the action set to `block`.", "type": "object", "nullable": true, "properties": { "enabled": { "description": "Enable notification.", "type": "boolean", "x-auditable": true }, "include_context": { "description": "Indicates whether to pass the context information as query parameters.", "type": "boolean", "x-auditable": true }, "msg": { "description": "Customize the message shown in the notification.", "type": "string", "x-auditable": true }, "support_url": { "description": "Defines an optional URL to direct users to additional information. If unset, the notification opens a block page.", "type": "string", "x-auditable": true } }, "x-stainless-terraform-configurability": "optional" }, "override_host": { "description": "Defines a hostname for override, for the matching DNS queries. Settable only for `dns` rules with the action set to `override`.", "type": "string", "example": "example.com", "x-auditable": true, "x-stainless-terraform-configurability": "optional" }, "override_ips": { "description": "Defines a an IP or set of IPs for overriding matched DNS queries. Settable only for `dns` rules with the action set to `override`.", "type": "array", "items": { "description": "Defines the IPv4 or IPv6 address.", "example": "1.1.1.1", "type": "string", "x-auditable": true }, "example": [ "1.1.1.1", "2.2.2.2" ], "nullable": true, "x-stainless-terraform-configurability": "optional" }, "payload_log": { "description": "Configure DLP payload logging. Settable only for `http` rules.", "type": "object", "nullable": true, "properties": { "enabled": { "description": "Enable DLP payload logging for this rule.", "type": "boolean", "example": true, "x-auditable": true } }, "x-stainless-terraform-configurability": "optional" }, "quarantine": { "description": "Configure settings that apply to quarantine rules. Settable only for `http` rules.", "type": "object", "nullable": true, "properties": { "file_types": { "description": "Specify the types of files to sandbox.", "type": "array", "items": { "enum": [ "exe", "pdf", "doc", "docm", "docx", "rtf", "ppt", "pptx", "xls", "xlsm", "xlsx", "zip", "rar" ], "type": "string", "x-auditable": true } } }, "x-stainless-terraform-configurability": "optional" }, "redirect": { "description": "Apply settings to redirect rules. Settable only for `http` rules with the action set to `redirect`.", "type": "object", "nullable": true, "properties": { "include_context": { "description": "Specify whether to pass the context information as query parameters.", "type": "boolean", "x-auditable": true }, "preserve_path_and_query": { "description": "Specify whether to append the path and query parameters from the original request to target_uri.", "type": "boolean", "x-auditable": true }, "target_uri": { "description": "Specify the URI to which the user is redirected.", "type": "string", "format": "uri", "x-auditable": true } }, "required": [ "target_uri" ], "x-stainless-terraform-configurability": "optional" }, "resolve_dns_internally": { "description": "Configure to forward the query to the internal DNS service, passing the specified 'view_id' as input. Not used when 'dns_resolvers' is specified or 'resolve_dns_through_cloudflare' is set. Only valid when a rule's action set to 'resolve'. Settable only for `dns_resolver` rules.", "type": "object", "nullable": true, "properties": { "fallback": { "description": "Specify the fallback behavior to apply when the internal DNS response code differs from 'NOERROR' or when the response data contains only CNAME records for 'A' or 'AAAA' queries.", "type": "string", "enum": [ "none", "public_dns" ], "x-auditable": true }, "view_id": { "description": "Specify the internal DNS view identifier to pass to the internal DNS service.", "type": "string", "x-auditable": true } }, "x-stainless-terraform-configurability": "optional" }, "resolve_dns_through_cloudflare": { "description": "Enable to send queries that match the policy to Cloudflare's default 1.1.1.1 DNS resolver. Cannot set when 'dns_resolvers' specified or 'resolve_dns_internally' is set. Only valid when a rule's action set to 'resolve'. Settable only for `dns_resolver` rules.", "type": "boolean", "example": true, "nullable": true, "x-auditable": true, "x-stainless-terraform-configurability": "optional" }, "set_headers": { "description": "Replace existing headers on allowed requests with the specified key-value pairs. If a header does not exist, it is added. Header values may contain `@{selector.name}` variable references that are interpolated at the edge. Use `@@{` to escape a literal `@{`. A maximum of 20 header operations (add + set + delete) is allowed per policy. Each header name may not exceed 256 bytes and each header value may not exceed 4 KB. Settable only for `http` rules with the action set to `allow`.", "type": "object", "example": { "X-User-Identity": [ "user=@{identity.name}" ] }, "additionalProperties": { "items": { "type": "string" }, "type": "array", "x-auditable": true }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "untrusted_cert": { "description": "Configure behavior when an upstream certificate is invalid or an SSL error occurs. Settable only for `http` rules with the action set to `allow`.", "type": "object", "nullable": true, "properties": { "action": { "description": "Defines the action performed when an untrusted certificate seen. The default action an error with HTTP code 526.", "type": "string", "example": "error", "enum": [ "pass_through", "block", "error" ], "x-auditable": true } }, "x-stainless-terraform-configurability": "optional" } }, "x-stainless-terraform-configurability": "computed_optional" }, "zero-trust-gateway_rules": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/zero-trust-gateway_action" }, "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "deleted_at": { "$ref": "#/components/schemas/zero-trust-gateway_deleted_at" }, "description": { "$ref": "#/components/schemas/zero-trust-gateway_description-2" }, "device_posture": { "$ref": "#/components/schemas/zero-trust-gateway_device_posture" }, "enabled": { "$ref": "#/components/schemas/zero-trust-gateway_enabled" }, "expiration": { "$ref": "#/components/schemas/zero-trust-gateway_expiration" }, "filters": { "$ref": "#/components/schemas/zero-trust-gateway_filters" }, "id": { "$ref": "#/components/schemas/zero-trust-gateway_uuid-2" }, "identity": { "$ref": "#/components/schemas/zero-trust-gateway_identity" }, "name": { "$ref": "#/components/schemas/zero-trust-gateway_name-3" }, "precedence": { "$ref": "#/components/schemas/zero-trust-gateway_precedence" }, "read_only": { "$ref": "#/components/schemas/zero-trust-gateway_read_only" }, "rule_settings": { "$ref": "#/components/schemas/zero-trust-gateway_rule-settings" }, "schedule": { "$ref": "#/components/schemas/zero-trust-gateway_schedule" }, "sharable": { "$ref": "#/components/schemas/zero-trust-gateway_sharable" }, "source_account": { "$ref": "#/components/schemas/zero-trust-gateway_source_account" }, "traffic": { "$ref": "#/components/schemas/zero-trust-gateway_traffic" }, "updated_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "version": { "$ref": "#/components/schemas/zero-trust-gateway_version" }, "warning_status": { "$ref": "#/components/schemas/zero-trust-gateway_warning_status" } }, "required": [ "name", "precedence", "enabled", "action", "traffic", "filters" ] }, "zero-trust-gateway_sandbox": { "description": "Specify whether to enable the sandbox.", "type": "object", "properties": { "enabled": { "description": "Specify whether to enable the sandbox.", "type": "boolean", "example": true, "nullable": true, "x-auditable": true }, "fallback_action": { "description": "Specify the action to take when the system cannot scan the file.", "type": "string", "enum": [ "allow", "block" ], "x-auditable": true } }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_schedule": { "description": "Defines the schedule for activating DNS policies. Settable only for `dns` and `dns_resolver` rules.", "type": "object", "properties": { "fri": { "description": "Specify the time intervals when the rule is active on Fridays, in the increasing order from 00:00-24:00. If this parameter omitted, the rule is deactivated on Fridays. API returns a formatted version of this string, which may cause Terraform drift if a unformatted value is used.", "type": "string", "example": "08:00-12:30,13:30-17:00", "x-auditable": true }, "mon": { "description": "Specify the time intervals when the rule is active on Mondays, in the increasing order from 00:00-24:00(capped at maximum of 6 time splits). If this parameter omitted, the rule is deactivated on Mondays. API returns a formatted version of this string, which may cause Terraform drift if a unformatted value is used.", "type": "string", "example": "08:00-12:30,13:30-17:00", "x-auditable": true }, "sat": { "description": "Specify the time intervals when the rule is active on Saturdays, in the increasing order from 00:00-24:00. If this parameter omitted, the rule is deactivated on Saturdays. API returns a formatted version of this string, which may cause Terraform drift if a unformatted value is used.", "type": "string", "example": "08:00-12:30,13:30-17:00", "x-auditable": true }, "sun": { "description": "Specify the time intervals when the rule is active on Sundays, in the increasing order from 00:00-24:00. If this parameter omitted, the rule is deactivated on Sundays. API returns a formatted version of this string, which may cause Terraform drift if a unformatted value is used.", "type": "string", "example": "08:00-12:30,13:30-17:00", "x-auditable": true }, "thu": { "description": "Specify the time intervals when the rule is active on Thursdays, in the increasing order from 00:00-24:00. If this parameter omitted, the rule is deactivated on Thursdays. API returns a formatted version of this string, which may cause Terraform drift if a unformatted value is used.", "type": "string", "example": "08:00-12:30,13:30-17:00", "x-auditable": true }, "time_zone": { "description": "Specify the time zone for rule evaluation. When a [valid time zone city name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) is provided, Gateway always uses the current time for that time zone. When this parameter is omitted, Gateway uses the time zone determined from the user's IP address. Colo time zone is used when the user's IP address does not resolve to a location.", "type": "string", "example": "America/New York", "x-auditable": true }, "tue": { "description": "Specify the time intervals when the rule is active on Tuesdays, in the increasing order from 00:00-24:00. If this parameter omitted, the rule is deactivated on Tuesdays. API returns a formatted version of this string, which may cause Terraform drift if a unformatted value is used.", "type": "string", "example": "08:00-12:30,13:30-17:00", "x-auditable": true }, "wed": { "description": "Specify the time intervals when the rule is active on Wednesdays, in the increasing order from 00:00-24:00. If this parameter omitted, the rule is deactivated on Wednesdays. API returns a formatted version of this string, which may cause Terraform drift if a unformatted value is used.", "type": "string", "example": "08:00-12:30,13:30-17:00", "x-auditable": true } }, "nullable": true, "x-stainless-terraform-configurability": "computed_optional" }, "zero-trust-gateway_settings": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "public_key": { "$ref": "#/components/schemas/zero-trust-gateway_public_key" }, "seed_id": { "$ref": "#/components/schemas/zero-trust-gateway_uuid-4" }, "updated_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" } } }, "zero-trust-gateway_sharable": { "description": "Indicate that this rule is sharable via the Orgs API.", "type": "boolean", "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "zero-trust-gateway_single_response": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/zero-trust-gateway_certificates" } }, "type": "object" } ] }, "zero-trust-gateway_single_response-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/zero-trust-gateway_operation" } }, "type": "object" } ] }, "zero-trust-gateway_single_response-3": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/zero-trust-gateway_locations" } }, "type": "object" } ] }, "zero-trust-gateway_single_response-4": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/zero-trust-gateway_rules" } }, "type": "object" } ] }, "zero-trust-gateway_single_response-5": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/zero-trust-gateway_proxy-endpoints" } }, "type": "object" } ] }, "zero-trust-gateway_single_response-6": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/zero-trust-gateway_settings" } }, "type": "object" } ] }, "zero-trust-gateway_single_response-7": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/zero-trust-gateway_pacfile" } }, "type": "object" } ] }, "zero-trust-gateway_single_response_with_list_items": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zero-trust-gateway_api-response-single" }, { "properties": { "result": { "type": "object", "properties": { "created_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" }, "description": { "$ref": "#/components/schemas/zero-trust-gateway_description" }, "id": { "$ref": "#/components/schemas/zero-trust-gateway_uuid-2" }, "items": { "$ref": "#/components/schemas/zero-trust-gateway_items" }, "name": { "$ref": "#/components/schemas/zero-trust-gateway_name" }, "type": { "$ref": "#/components/schemas/zero-trust-gateway_type-2" }, "updated_at": { "$ref": "#/components/schemas/zero-trust-gateway_read_only_timestamp" } } } }, "type": "object" } ] }, "zero-trust-gateway_slug": { "description": "URL-friendly version of the PAC file name.", "type": "string", "example": "pac_devops", "x-auditable": true }, "zero-trust-gateway_source_account": { "description": "Provide the account tag of the account that created the rule.", "type": "string", "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "zero-trust-gateway_subcategory": { "type": "object", "properties": { "beta": { "$ref": "#/components/schemas/zero-trust-gateway_beta" }, "class": { "$ref": "#/components/schemas/zero-trust-gateway_class" }, "description": { "$ref": "#/components/schemas/zero-trust-gateway_description-3" }, "id": { "$ref": "#/components/schemas/zero-trust-gateway_id" }, "name": { "$ref": "#/components/schemas/zero-trust-gateway_name-5" } } }, "zero-trust-gateway_subdomain": { "description": "Specify the DNS over HTTPS domain that receives DNS requests. Gateway automatically generates this value.", "type": "string", "example": "oli3n9zkz5", "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "zero-trust-gateway_subdomain-2": { "description": "Specify the subdomain to use as the destination in the proxy client.", "type": "string", "example": "oli3n9zkz5.proxy.cloudflare-gateway.com", "readOnly": true, "x-auditable": true }, "zero-trust-gateway_timestamp": { "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z" }, "zero-trust-gateway_tls-settings": { "description": "Specify whether to inspect encrypted HTTP traffic.", "type": "object", "properties": { "enabled": { "description": "Specify whether to inspect encrypted HTTP traffic.", "type": "boolean", "example": true, "x-auditable": true } }, "nullable": true, "x-stainless-terraform-configurability": "optional" }, "zero-trust-gateway_traffic": { "description": "Specify the wirefilter expression used for traffic matching. The API automatically formats and sanitizes expressions before storing them. To prevent Terraform state drift, use the formatted expression returned in the API response.", "type": "string", "example": "http.request.uri matches \".*a/partial/uri.*\" and http.request.host in $01302951-49f9-47c9-a400-0297e60b6a10", "default": "", "x-auditable": true, "x-stainless-terraform-configurability": "computed_optional" }, "zero-trust-gateway_type": { "description": "Indicate the read-only certificate type, BYO-PKI (custom) or Gateway-managed.", "type": "string", "example": "gateway_managed", "enum": [ "custom", "gateway_managed" ], "readOnly": true, "x-auditable": true }, "zero-trust-gateway_type-2": { "description": "Specify the list type.", "type": "string", "example": "SERIAL", "enum": [ "SERIAL", "URL", "DOMAIN", "EMAIL", "IP", "CATEGORY", "LOCATION", "DEVICE", "AAGUID" ], "x-auditable": true }, "zero-trust-gateway_unapproved_apps": { "description": "Contains the ids of the unapproved applications.", "type": "array", "items": { "type": "integer" }, "x-stainless-collection-type": "set" }, "zero-trust-gateway_url": { "description": "Unique URL to download the PAC file.", "type": "string", "example": "https://pac.cloudflare-gateway.com/699d98642c564d2e855e9661899b7252/pac_devops", "readOnly": true, "x-auditable": true }, "zero-trust-gateway_uuid": { "description": "Identify the certificate with a UUID.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "x-auditable": true }, "zero-trust-gateway_uuid-2": { "description": "Identify the API resource with a UUID.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "x-auditable": true }, "zero-trust-gateway_uuid-3": { "type": "string", "example": "ed35569b41ce4d1facfe683550f54086", "x-auditable": true }, "zero-trust-gateway_uuid-4": { "description": "Identify the seed ID.", "type": "string", "example": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415", "maxLength": 36, "x-auditable": true }, "zero-trust-gateway_value": { "description": "Specify the item value.", "type": "string", "example": "8GE8721REF", "x-auditable": true }, "zero-trust-gateway_version": { "description": "Indicate the version number of the rule(read-only).", "type": "integer", "example": 1, "readOnly": true, "x-auditable": true, "x-stainless-terraform-configurability": "computed" }, "zero-trust-gateway_warning_status": { "description": "Indicate a warning for a misconfigured rule, if any.", "type": "string", "nullable": true, "readOnly": true, "x-stainless-terraform-configurability": "computed" }, "zone-activation_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/zone-activation_messages" }, "messages": { "$ref": "#/components/schemas/zone-activation_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "zone-activation_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/zone-activation_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/zone-activation_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "zone-activation_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zone-activation_api-response-common" } ] }, "zone-activation_identifier": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "zone-activation_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "zone-analytics-api_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/zone-analytics-api_messages" }, "messages": { "$ref": "#/components/schemas/zone-analytics-api_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": {}, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "zone-analytics-api_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/zone-analytics-api_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/zone-analytics-api_messages" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "zone-analytics-api_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zone-analytics-api_api-response-common" }, { "properties": { "result": { "anyOf": [ { "nullable": true, "type": "object" }, { "nullable": true, "type": "string" } ] } } } ] }, "zone-analytics-api_bandwidth": { "description": "Breakdown of totals for bandwidth in the form of bytes.", "type": "object", "properties": { "all": { "description": "The total number of bytes served within the time frame.", "type": "integer" }, "cached": { "description": "The number of bytes that were cached (and served) by Cloudflare.", "type": "integer" }, "content_type": { "description": "A variable list of key/value pairs where the key represents the type of content served, and the value is the number in bytes served.", "type": "object", "example": { "css": 237421, "gif": 1234242, "html": 1231290, "javascript": 123245, "jpeg": 784278 } }, "country": { "description": "A variable list of key/value pairs where the key is a two-digit country code and the value is the number of bytes served to that country.", "type": "object", "example": { "AG": 2342483, "GI": 984753, "US": 123145433 } }, "ssl": { "description": "A break down of bytes served over HTTPS.", "type": "object", "properties": { "encrypted": { "description": "The number of bytes served over HTTPS.", "type": "integer" }, "unencrypted": { "description": "The number of bytes served over HTTP.", "type": "integer" } } }, "ssl_protocols": { "description": "A breakdown of requests by their SSL protocol.", "type": "object", "properties": { "TLSv1": { "description": "The number of requests served over TLS v1.0.", "type": "integer" }, "TLSv1.1": { "description": "The number of requests served over TLS v1.1.", "type": "integer" }, "TLSv1.2": { "description": "The number of requests served over TLS v1.2.", "type": "integer" }, "TLSv1.3": { "description": "The number of requests served over TLS v1.3.", "type": "integer" }, "none": { "description": "The number of requests served over HTTP.", "type": "integer" } } }, "uncached": { "description": "The number of bytes that were fetched and served from the origin server.", "type": "integer" } } }, "zone-analytics-api_bandwidth_by_colo": { "description": "Breakdown of totals for bandwidth in the form of bytes.", "type": "object", "properties": { "all": { "description": "The total number of bytes served within the time frame.", "type": "integer" }, "cached": { "description": "The number of bytes that were cached (and served) by Cloudflare.", "type": "integer" }, "uncached": { "description": "The number of bytes that were fetched and served from the origin server.", "type": "integer" } } }, "zone-analytics-api_colo_response": { "allOf": [ { "$ref": "#/components/schemas/zone-analytics-api_api-response-single" }, { "properties": { "query": { "$ref": "#/components/schemas/zone-analytics-api_query_response" }, "result": { "$ref": "#/components/schemas/zone-analytics-api_datacenters" } } } ] }, "zone-analytics-api_dashboard": { "description": "Totals and timeseries data.", "type": "object", "properties": { "timeseries": { "$ref": "#/components/schemas/zone-analytics-api_timeseries" }, "totals": { "$ref": "#/components/schemas/zone-analytics-api_totals" } }, "title": "Dashboard response" }, "zone-analytics-api_dashboard_response": { "allOf": [ { "$ref": "#/components/schemas/zone-analytics-api_api-response-single" }, { "properties": { "query": { "$ref": "#/components/schemas/zone-analytics-api_query_response" }, "result": { "$ref": "#/components/schemas/zone-analytics-api_dashboard" } } } ] }, "zone-analytics-api_datacenters": { "description": "A breakdown of all dashboard analytics data by co-locations. This is limited to Enterprise zones only.", "type": "array", "items": { "properties": { "colo_id": { "description": "The airport code identifer for the co-location.", "type": "string", "example": "SFO" }, "timeseries": { "$ref": "#/components/schemas/zone-analytics-api_timeseries_by_colo" }, "totals": { "$ref": "#/components/schemas/zone-analytics-api_totals_by_colo" } }, "type": "object" }, "title": "Analytics data by datacenter" }, "zone-analytics-api_identifier": { "description": "Identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true }, "zone-analytics-api_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "zone-analytics-api_pageviews": { "description": "Breakdown of totals for pageviews.", "type": "object", "properties": { "all": { "description": "The total number of pageviews served within the time range.", "type": "integer" }, "search_engine": { "description": "A variable list of key/value pairs representing the search engine and number of hits.", "type": "object", "example": { "baidubot": 1345, "bingbot": 5372, "googlebot": 35272, "pingdom": 13435 } } } }, "zone-analytics-api_query_response": { "description": "The exact parameters/timestamps the analytics service used to return data.", "type": "object", "properties": { "since": { "$ref": "#/components/schemas/zone-analytics-api_since" }, "time_delta": { "description": "The amount of time (in minutes) that each data point in the timeseries represents. The granularity of the time-series returned (e.g. each bucket in the time series representing 1-minute vs 1-day) is calculated by the API based on the time-range provided to the API.", "type": "integer" }, "until": { "$ref": "#/components/schemas/zone-analytics-api_until" } }, "readOnly": true }, "zone-analytics-api_requests": { "description": "Breakdown of totals for requests.", "type": "object", "properties": { "all": { "description": "Total number of requests served.", "type": "integer" }, "cached": { "description": "Total number of cached requests served.", "type": "integer" }, "content_type": { "description": "A variable list of key/value pairs where the key represents the type of content served, and the value is the number of requests.", "type": "object", "example": { "css": 15343, "gif": 23178, "html": 1234213, "javascript": 318236, "jpeg": 1982048 } }, "country": { "description": "A variable list of key/value pairs where the key is a two-digit country code and the value is the number of requests served to that country.", "type": "object", "example": { "AG": 37298, "GI": 293846, "US": 4181364 } }, "http_status": { "description": "Key/value pairs where the key is a HTTP status code and the value is the number of requests served with that code.", "type": "object", "example": { "200": 13496983, "301": 283, "400": 187936, "402": 1828, "404": 1293 }, "additionalProperties": true }, "ssl": { "description": "A break down of requests served over HTTPS.", "type": "object", "properties": { "encrypted": { "description": "The number of requests served over HTTPS.", "type": "integer" }, "unencrypted": { "description": "The number of requests served over HTTP.", "type": "integer" } } }, "ssl_protocols": { "description": "A breakdown of requests by their SSL protocol.", "type": "object", "properties": { "TLSv1": { "description": "The number of requests served over TLS v1.0.", "type": "integer" }, "TLSv1.1": { "description": "The number of requests served over TLS v1.1.", "type": "integer" }, "TLSv1.2": { "description": "The number of requests served over TLS v1.2.", "type": "integer" }, "TLSv1.3": { "description": "The number of requests served over TLS v1.3.", "type": "integer" }, "none": { "description": "The number of requests served over HTTP.", "type": "integer" } } }, "uncached": { "description": "Total number of requests served from the origin.", "type": "integer" } } }, "zone-analytics-api_requests_by_colo": { "description": "Breakdown of totals for requests.", "type": "object", "properties": { "all": { "description": "Total number of requests served.", "type": "integer" }, "cached": { "description": "Total number of cached requests served.", "type": "integer" }, "country": { "description": "Key/value pairs where the key is a two-digit country code and the value is the number of requests served to that country.", "type": "object", "example": { "AG": 37298, "GI": 293846, "US": 4181364 }, "additionalProperties": true }, "http_status": { "description": "A variable list of key/value pairs where the key is a HTTP status code and the value is the number of requests with that code served.", "type": "object", "example": { "200": 13496983, "301": 283, "400": 187936, "402": 1828, "404": 1293 } }, "uncached": { "description": "Total number of requests served from the origin.", "type": "integer" } } }, "zone-analytics-api_since": { "description": "The (inclusive) beginning of the requested time frame. This value can be a negative integer representing the number of minutes in the past relative to time the request is made, or can be an absolute timestamp that conforms to RFC 3339. At this point in time, it cannot exceed a time in the past greater than one year.\n\nRanges that the Cloudflare web application provides will provide the following period length for each point:\n- Last 60 minutes (from -59 to -1): 1 minute resolution\n- Last 7 hours (from -419 to -60): 15 minutes resolution\n- Last 15 hours (from -899 to -420): 30 minutes resolution\n- Last 72 hours (from -4320 to -900): 1 hour resolution\n- Older than 3 days (-525600 to -4320): 1 day resolution.", "example": "2015-01-01T12:23:00Z", "default": -10080, "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "zone-analytics-api_threats": { "description": "Breakdown of totals for threats.", "type": "object", "properties": { "all": { "description": "The total number of identifiable threats received over the time frame.", "type": "integer" }, "country": { "description": "A list of key/value pairs where the key is a two-digit country code and the value is the number of malicious requests received from that country.", "type": "object", "example": { "AU": 91, "CN": 523423, "US": 123 } }, "type": { "description": "The list of key/value pairs where the key is a threat category and the value is the number of requests.", "type": "object", "example": { "hot.ban.unknown": 5324, "macro.chl.captchaErr": 1341, "macro.chl.jschlErr": 5323, "user.ban.ip": 123 } } } }, "zone-analytics-api_timeseries": { "description": "Time deltas containing metadata about each bucket of time. The number of buckets (resolution) is determined by the amount of time between the since and until parameters.", "type": "array", "items": { "properties": { "bandwidth": { "$ref": "#/components/schemas/zone-analytics-api_bandwidth" }, "pageviews": { "$ref": "#/components/schemas/zone-analytics-api_pageviews" }, "requests": { "$ref": "#/components/schemas/zone-analytics-api_requests" }, "since": { "$ref": "#/components/schemas/zone-analytics-api_since" }, "threats": { "$ref": "#/components/schemas/zone-analytics-api_threats" }, "uniques": { "$ref": "#/components/schemas/zone-analytics-api_uniques" }, "until": { "$ref": "#/components/schemas/zone-analytics-api_until" } }, "type": "object" } }, "zone-analytics-api_timeseries_by_colo": { "description": "Time deltas containing metadata about each bucket of time. The number of buckets (resolution) is determined by the amount of time between the since and until parameters.", "type": "array", "items": { "properties": { "bandwidth": { "$ref": "#/components/schemas/zone-analytics-api_bandwidth_by_colo" }, "requests": { "$ref": "#/components/schemas/zone-analytics-api_requests_by_colo" }, "since": { "$ref": "#/components/schemas/zone-analytics-api_since" }, "threats": { "$ref": "#/components/schemas/zone-analytics-api_threats" }, "until": { "$ref": "#/components/schemas/zone-analytics-api_until" } }, "type": "object" } }, "zone-analytics-api_totals": { "description": "Breakdown of totals by data type.", "type": "object", "properties": { "bandwidth": { "$ref": "#/components/schemas/zone-analytics-api_bandwidth" }, "pageviews": { "$ref": "#/components/schemas/zone-analytics-api_pageviews" }, "requests": { "$ref": "#/components/schemas/zone-analytics-api_requests" }, "since": { "$ref": "#/components/schemas/zone-analytics-api_since" }, "threats": { "$ref": "#/components/schemas/zone-analytics-api_threats" }, "uniques": { "$ref": "#/components/schemas/zone-analytics-api_uniques" }, "until": { "$ref": "#/components/schemas/zone-analytics-api_until" } } }, "zone-analytics-api_totals_by_colo": { "description": "Breakdown of totals by data type.", "type": "object", "properties": { "bandwidth": { "$ref": "#/components/schemas/zone-analytics-api_bandwidth_by_colo" }, "requests": { "$ref": "#/components/schemas/zone-analytics-api_requests_by_colo" }, "since": { "$ref": "#/components/schemas/zone-analytics-api_since" }, "threats": { "$ref": "#/components/schemas/zone-analytics-api_threats" }, "until": { "$ref": "#/components/schemas/zone-analytics-api_until" } } }, "zone-analytics-api_uniques": { "type": "object", "properties": { "all": { "description": "Total number of unique IP addresses within the time range.", "type": "integer" } } }, "zone-analytics-api_until": { "description": "The (exclusive) end of the requested time frame. This value can be a negative integer representing the number of minutes in the past relative to time the request is made, or can be an absolute timestamp that conforms to RFC 3339. If omitted, the time of the request is used.", "example": "2015-01-02T12:23:00Z", "default": 0, "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "zone-analytics-api_user_dashboard_response": { "allOf": [ { "$ref": "#/components/schemas/zone-analytics-api_api-response-common" }, { "properties": { "query": { "$ref": "#/components/schemas/zone-analytics-api_query_response" }, "result": { "description": "Per-zone analytics data for all zones accessible to the user.", "type": "array", "items": { "$ref": "#/components/schemas/zone-analytics-api_user_zone" } } } } ] }, "zone-analytics-api_user_period": { "description": "Analytics data for a single time period bucket.", "type": "object", "properties": { "bandwidth": { "$ref": "#/components/schemas/zone-analytics-api_user_period_bandwidth" }, "requests": { "$ref": "#/components/schemas/zone-analytics-api_user_period_requests" }, "since": { "$ref": "#/components/schemas/zone-analytics-api_since" }, "until": { "$ref": "#/components/schemas/zone-analytics-api_until" } } }, "zone-analytics-api_user_period_bandwidth": { "description": "Breakdown of bandwidth totals for a time period, in bytes.", "type": "object", "properties": { "all": { "description": "The total number of bytes served.", "type": "integer", "example": 190290 }, "cached": { "description": "The number of bytes served from cache.", "type": "integer", "example": 97717 }, "uncached": { "description": "The number of bytes served from the origin.", "type": "integer", "example": 92573 } } }, "zone-analytics-api_user_period_requests": { "description": "Breakdown of request totals for a time period.", "type": "object", "properties": { "all": { "description": "Total number of requests served.", "type": "integer", "example": 51440 } } }, "zone-analytics-api_user_zone": { "description": "Analytics data for a single zone owned by the user.", "type": "object", "properties": { "timeseries": { "description": "Time deltas containing analytics data for each bucket. The number of\nbuckets (resolution) is determined by the time range between since and until.", "type": "array", "items": { "$ref": "#/components/schemas/zone-analytics-api_user_period" } }, "totals": { "$ref": "#/components/schemas/zone-analytics-api_user_period" }, "zone_id": { "description": "The zone identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "readOnly": true } } }, "zones_0rtt": { "description": "0-RTT session resumption enabled for this zone.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "0rtt", "enum": [ "0rtt" ] }, "value": { "$ref": "#/components/schemas/zones_0rtt_value" } } } ], "title": "0-RTT Value" }, "zones_0rtt_value": { "description": "Value of the 0-RTT setting.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_actions": { "description": "The set of actions to perform if the targets of this rule match the\nrequest. Actions can redirect to another URL or override settings, but\nnot both.\n", "type": "array", "items": { "discriminator": { "propertyName": "id" }, "oneOf": [ { "$ref": "#/components/schemas/zones_always_use_https" }, { "$ref": "#/components/schemas/zones_automatic_https_rewrites" }, { "$ref": "#/components/schemas/zones_browser_cache_ttl" }, { "$ref": "#/components/schemas/zones_browser_check" }, { "$ref": "#/components/schemas/zones_bypass_cache_on_cookie" }, { "$ref": "#/components/schemas/zones_cache_by_device_type" }, { "$ref": "#/components/schemas/zones_cache_deception_armor" }, { "$ref": "#/components/schemas/zones_cache_key_fields" }, { "$ref": "#/components/schemas/zones_cache_level" }, { "$ref": "#/components/schemas/zones_cache_on_cookie" }, { "$ref": "#/components/schemas/zones_cache_ttl_by_status" }, { "$ref": "#/components/schemas/zones_disable_apps" }, { "$ref": "#/components/schemas/zones_disable_performance" }, { "$ref": "#/components/schemas/zones_disable_security" }, { "$ref": "#/components/schemas/zones_disable_zaraz" }, { "$ref": "#/components/schemas/zones_edge_cache_ttl" }, { "$ref": "#/components/schemas/zones_email_obfuscation" }, { "$ref": "#/components/schemas/zones_explicit_cache_control" }, { "$ref": "#/components/schemas/zones_forwarding_url" }, { "$ref": "#/components/schemas/zones_host_header_override" }, { "$ref": "#/components/schemas/zones_ip_geolocation" }, { "$ref": "#/components/schemas/zones_mirage" }, { "$ref": "#/components/schemas/zones_opportunistic_encryption" }, { "$ref": "#/components/schemas/zones_origin_error_page_pass_thru" }, { "$ref": "#/components/schemas/zones_polish" }, { "$ref": "#/components/schemas/zones_resolve_override" }, { "$ref": "#/components/schemas/zones_respect_strong_etag" }, { "$ref": "#/components/schemas/zones_response_buffering" }, { "$ref": "#/components/schemas/zones_rocket_loader" }, { "$ref": "#/components/schemas/zones_security_level" }, { "$ref": "#/components/schemas/zones_sort_query_string_for_cache" }, { "$ref": "#/components/schemas/zones_ssl" }, { "$ref": "#/components/schemas/zones_true_client_ip_header" }, { "$ref": "#/components/schemas/zones_waf" } ] }, "example": [ { "id": "browser_check", "value": "on" } ], "x-stainless-skip": [ "terraform" ] }, "zones_advanced_ddos": { "description": "Advanced protection from Distributed Denial of Service (DDoS) attacks on your website. This is an uneditable value that is 'on' in the case of Business and Enterprise zones.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "advanced_ddos", "enum": [ "advanced_ddos" ] }, "value": { "$ref": "#/components/schemas/zones_advanced_ddos_value" } } } ], "title": "Advanced DDoS Protection" }, "zones_advanced_ddos_value": { "description": "Value of the zone setting.\nNotes: Defaults to on for Business+ plans", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_always_online": { "description": "When enabled, Cloudflare serves limited copies of web pages available from the [Internet Archive's Wayback Machine](https://archive.org/web/) if your server is offline. Refer to [Always Online](https://developers.cloudflare.com/cache/about/always-online) for more information.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "always_online", "enum": [ "always_online" ] }, "value": { "$ref": "#/components/schemas/zones_always_online_value" } } } ], "title": "Always Online Mode" }, "zones_always_online_value": { "description": "Value of the zone setting.", "type": "string", "default": "on", "enum": [ "on", "off" ] }, "zones_always_use_https": { "type": "object", "properties": { "id": { "description": "If enabled, any `http://`` URL is converted to `https://` through a\n301 redirect.\n", "type": "string", "enum": [ "always_use_https" ], "x-auditable": true } }, "title": "Always Use HTTPS", "x-stainless-skip": [ "terraform" ] }, "zones_always_use_https-2": { "description": "Reply to all requests for URLs that use \"http\" with a 301 redirect to the equivalent \"https\" URL. If you only want to redirect for a subset of requests, consider creating an \"Always use HTTPS\" page rule.", "default": "off", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "always_use_https", "enum": [ "always_use_https" ] }, "value": { "$ref": "#/components/schemas/zones_always_use_https_value" } } } ], "title": "Zone Enable Always Use HTTPS" }, "zones_always_use_https_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_api-response-common": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/zones_messages" }, "messages": { "$ref": "#/components/schemas/zones_messages" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages" ] }, "zones_api-response-common-2": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/zones_messages-2" }, "messages": { "$ref": "#/components/schemas/zones_messages-2" }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages" ] }, "zones_api-response-common-3": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/zones_messages" }, "messages": { "$ref": "#/components/schemas/zones_messages" }, "result": { "anyOf": [ { "type": "object" }, { "items": {}, "type": "array" }, { "type": "string" } ] }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true, "enum": [ true ] } }, "required": [ "success", "errors", "messages", "result" ] }, "zones_api-response-common-4": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/zones_messages" }, "messages": { "$ref": "#/components/schemas/zones_messages" }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": true } }, "required": [ "success", "errors", "messages" ] }, "zones_api-response-common-failure": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/zones_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/zones_messages" } ] }, "result": { "type": "object", "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false } }, "required": [ "success", "errors", "messages", "result" ] }, "zones_api-response-common-failure-2": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/zones_messages-2" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/zones_messages-2" } ] }, "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "description": "Whether the API call was successful.", "type": "boolean", "example": false, "enum": [ false ] } }, "required": [ "success", "errors", "messages", "result" ] }, "zones_api-response-common-failure-3": { "type": "object", "properties": { "errors": { "example": [ { "code": 7003, "message": "No route for the URI" } ], "allOf": [ { "$ref": "#/components/schemas/zones_messages" } ], "minLength": 1 }, "messages": { "example": [], "allOf": [ { "$ref": "#/components/schemas/zones_messages" } ] }, "result": { "type": "object", "nullable": true }, "success": { "description": "Whether the API call was successful", "type": "boolean", "example": false } }, "required": [ "success", "errors", "messages", "result" ] }, "zones_api-response-single": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common-2" } ] }, "zones_api-response-single-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common-3" }, { "properties": { "result": { "anyOf": [ { "type": "object" }, { "type": "string" } ] } } } ] }, "zones_api-response-single-id": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common" }, { "properties": { "result": { "type": "object", "nullable": true, "properties": { "id": { "$ref": "#/components/schemas/zones_identifier" } }, "required": [ "id" ] } } } ] }, "zones_api-response-single-id-2": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common-2" }, { "properties": { "result": { "type": "object", "nullable": true, "properties": { "id": { "$ref": "#/components/schemas/zones_identifier-2" } }, "required": [ "id" ] } }, "type": "object" } ] }, "zones_automatic_https_rewrites": { "type": "object", "properties": { "id": { "description": "Turn on or off Automatic HTTPS Rewrites.", "type": "string", "enum": [ "automatic_https_rewrites" ], "x-auditable": true }, "value": { "description": "The status of Automatic HTTPS Rewrites.\n", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "title": "Automatic HTTPS Rewrites", "x-stainless-skip": [ "terraform" ] }, "zones_automatic_https_rewrites-2": { "description": "Enable the Automatic HTTPS Rewrites feature for this zone.", "default": "off", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "automatic_https_rewrites", "enum": [ "automatic_https_rewrites" ] }, "value": { "$ref": "#/components/schemas/zones_automatic_https_rewrites_value" } } } ], "title": "Zone Enable Automatic HTTPS Rewrites" }, "zones_automatic_https_rewrites_value": { "description": "Value of the zone setting.\nNotes: Default value depends on the zone's plan level.", "type": "string", "default": "on", "enum": [ "on", "off" ] }, "zones_automatic_platform_optimization": { "type": "object", "properties": { "cache_by_device_type": { "description": "Indicates whether or not [cache by device type](https://developers.cloudflare.com/automatic-platform-optimization/reference/cache-device-type/) is enabled.", "type": "boolean", "example": false }, "cf": { "description": "Indicates whether or not Cloudflare proxy is enabled.", "type": "boolean", "example": true, "default": false }, "enabled": { "description": "Indicates whether or not Automatic Platform Optimization is enabled.", "type": "boolean", "example": true, "default": false }, "hostnames": { "description": "An array of hostnames where Automatic Platform Optimization for WordPress is activated.", "type": "array", "items": { "format": "hostname", "type": "string" }, "example": [ "www.example.com", "example.com", "shop.example.com" ] }, "wordpress": { "description": "Indicates whether or not site is powered by WordPress.", "type": "boolean", "example": true, "default": false }, "wp_plugin": { "description": "Indicates whether or not [Cloudflare for WordPress plugin](https://wordpress.org/plugins/cloudflare/) is installed.", "type": "boolean", "example": true, "default": false } }, "required": [ "enabled", "cf", "wordpress", "wp_plugin", "hostnames", "cache_by_device_type" ] }, "zones_base": { "properties": { "editable": { "description": "Whether or not this setting can be modified for this zone (based on your Cloudflare plan level).", "type": "boolean", "enum": [ true, false ], "readOnly": true }, "id": { "description": "Identifier of the zone setting.", "type": "string", "example": "development_mode" }, "modified_on": { "description": "last time this setting was modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "nullable": true, "readOnly": true }, "value": { "description": "Current value of the zone setting.", "example": "on" } }, "required": [ "id", "value" ] }, "zones_brotli": { "description": "When the client requesting an asset supports the Brotli compression algorithm, Cloudflare will serve a Brotli compressed version of the asset.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "brotli", "enum": [ "brotli" ] }, "value": { "$ref": "#/components/schemas/zones_brotli_value" } } } ], "title": "Brotli Compression" }, "zones_brotli_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "off", "on" ] }, "zones_browser_cache_ttl": { "type": "object", "properties": { "id": { "description": "Control how long resources cached by client browsers remain valid.\n", "type": "string", "enum": [ "browser_cache_ttl" ], "x-auditable": true }, "value": { "description": "The number of seconds to cache resources for.\nSetting this to 0 enables \"Respect Existing Headers\".\n", "type": "integer", "example": 3600, "maximum": 31536000, "minimum": 0, "x-auditable": true } }, "title": "Browser Cache TTL", "x-stainless-skip": [ "terraform" ] }, "zones_browser_cache_ttl-2": { "description": "Browser Cache TTL (in seconds) specifies how long Cloudflare-cached resources will remain on your visitors' computers. Cloudflare will honor any larger times specified by your server. (https://support.cloudflare.com/hc/en-us/articles/200168276).", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "browser_cache_ttl", "enum": [ "browser_cache_ttl" ] }, "value": { "$ref": "#/components/schemas/zones_browser_cache_ttl_value" } } } ], "title": "Browser Cache TTL" }, "zones_browser_cache_ttl_value": { "description": "Value of the zone setting in seconds.\nMinimum values by plan:\n- Free: 1 second\n- Pro: 1 second\n- Business: 1 second\n- Enterprise: 1 second\nSetting a TTL of 0 is equivalent to selecting `Respect Existing Headers` and is allowed for all plans.", "type": "integer", "default": 14400, "maximum": 31536000, "minimum": 0 }, "zones_browser_check": { "type": "object", "properties": { "id": { "description": "Inspect the visitor's browser for headers commonly associated with\nspammers and certain bots.\n", "type": "string", "enum": [ "browser_check" ], "x-auditable": true }, "value": { "description": "The status of Browser Integrity Check.\n", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "title": "Browser Integrity Check", "x-stainless-skip": [ "terraform" ] }, "zones_browser_check-2": { "description": "Browser Integrity Check is similar to Bad Behavior and looks for common HTTP headers abused most commonly by spammers and denies access to your page. It will also challenge visitors that do not have a user agent or a non standard user agent (also commonly used by abuse bots, crawlers or visitors). (https://support.cloudflare.com/hc/en-us/articles/200170086).", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "browser_check", "enum": [ "browser_check" ] }, "value": { "$ref": "#/components/schemas/zones_browser_check_value" } } } ], "title": "Browser Check" }, "zones_browser_check_value": { "description": "Value of the zone setting.", "type": "string", "default": "on", "enum": [ "on", "off" ] }, "zones_bypass_cache_on_cookie": { "type": "object", "properties": { "id": { "description": "Bypass cache and fetch resources from the origin server if a regular\nexpression matches against a cookie name present in the request.\n", "type": "string", "enum": [ "bypass_cache_on_cookie" ], "x-auditable": true }, "value": { "description": "The regular expression to use for matching cookie names in the\nrequest. Refer to [Bypass Cache on Cookie\nsetting](https://developers.cloudflare.com/rules/page-rules/reference/additional-reference/#bypass-cache-on-cookie-setting)\nto learn about limited regular expression support.\n", "type": "string", "example": "bypass=.*|PHPSESSID=.*", "maxLength": 150, "minLength": 1, "x-auditable": true } }, "title": "Bypass Cache on Cookie", "x-stainless-skip": [ "terraform" ] }, "zones_cache-rules_aegis": { "description": "Aegis provides dedicated egress IPs (from Cloudflare to your origin) for your layer 7 WAF and CDN services. The egress IPs are reserved exclusively for your account so that you can increase your origin security by only allowing traffic from a small list of IP addresses.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/zones_cache-rules_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "type": "string", "example": "aegis", "enum": [ "aegis" ], "x-auditable": true }, "value": { "$ref": "#/components/schemas/zones_cache-rules_aegis_value" } }, "type": "object" } ], "title": "Aegis" }, "zones_cache-rules_aegis_value": { "description": "Value of the zone setting.", "type": "object", "properties": { "enabled": { "description": "Whether the feature is enabled or not.", "type": "boolean", "x-auditable": true }, "pool_id": { "description": "Egress pool id which refers to a grouping of dedicated egress IPs through which Cloudflare will connect to origin.", "type": "string", "example": "pool-id", "x-auditable": true } } }, "zones_cache-rules_base": { "type": "object", "properties": { "id": { "description": "Identifier of the zone setting.", "type": "string", "x-auditable": true }, "modified_on": { "description": "Last time this setting was modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "nullable": true, "readOnly": true, "x-auditable": true } }, "required": [ "id" ] }, "zones_cache-rules_origin_h2_max_streams": { "description": "Origin H2 Max Streams configures the max number of concurrent requests that Cloudflare will send within the same connection when communicating with the origin server, if the origin supports it. Note that if your origin does not support H2 multiplexing, 5xx errors may be observed, particularly 520s. Also note that the default value is `100` for all plan types except Enterprise where it is `1`. `1` means that H2 multiplexing is disabled.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/zones_cache-rules_base" }, { "properties": { "id": { "description": "Value of the zone setting.", "type": "string", "example": "origin_h2_max_streams", "enum": [ "origin_h2_max_streams" ], "x-auditable": true }, "value": { "$ref": "#/components/schemas/zones_cache-rules_origin_h2_max_streams_value" } }, "type": "object" } ], "title": "Origin H2 Max Streams" }, "zones_cache-rules_origin_h2_max_streams_value": { "description": "Value of the Origin H2 Max Streams Setting.", "type": "integer", "example": 50, "maximum": 1000, "minimum": 1, "x-auditable": true }, "zones_cache-rules_origin_max_http_version": { "description": "Origin Max HTTP Setting Version sets the highest HTTP version Cloudflare will attempt to use with your origin. This setting allows Cloudflare to make HTTP/2 requests to your origin. (Refer to [Enable HTTP/2 to Origin](https://developers.cloudflare.com/cache/how-to/enable-http2-to-origin/), for more information.). The default value is \"2\" for all plan types except Enterprise where it is \"1\".", "type": "object", "allOf": [ { "$ref": "#/components/schemas/zones_cache-rules_base" }, { "properties": { "id": { "description": "Value of the zone setting.", "type": "string", "example": "origin_max_http_version", "enum": [ "origin_max_http_version" ], "x-auditable": true }, "value": { "$ref": "#/components/schemas/zones_cache-rules_origin_max_http_version_value" } }, "type": "object" } ], "title": "Origin Max HTTP Version" }, "zones_cache-rules_origin_max_http_version_value": { "description": "Value of the Origin Max HTTP Version Setting.", "type": "string", "enum": [ "2", "1" ], "x-auditable": true }, "zones_cache_by_device_type": { "type": "object", "properties": { "id": { "description": "Separate cached content based on the visitor's device type.\n", "type": "string", "enum": [ "cache_by_device_type" ], "x-auditable": true }, "value": { "description": "The status of Cache By Device Type.\n", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "title": "Cache By Device Type", "x-stainless-skip": [ "terraform" ] }, "zones_cache_deception_armor": { "type": "object", "properties": { "id": { "description": "Protect from web cache deception attacks while still allowing static\nassets to be cached. This setting verifies that the URL's extension\nmatches the returned `Content-Type`.\n", "type": "string", "enum": [ "cache_deception_armor" ], "x-auditable": true }, "value": { "description": "The status of Cache Deception Armor.\n", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "title": "Cache Deception Armor", "x-stainless-skip": [ "terraform" ] }, "zones_cache_key_fields": { "type": "object", "properties": { "id": { "description": "Control specifically what variables to include when deciding which\nresources to cache. This allows customers to determine what to cache\nbased on something other than just the URL.\n", "type": "string", "enum": [ "cache_key_fields" ] }, "value": { "type": "object", "properties": { "cookie": { "description": "Controls which cookies appear in the Cache Key.\n", "properties": { "check_presence": { "description": "A list of cookies to check for the presence of, without\nincluding their actual values.\n", "type": "array", "items": { "example": "foo", "minLength": 1, "type": "string" }, "example": [ "foo", "bar" ], "maxItems": 50, "minItems": 1 }, "include": { "description": "A list of cookies to include.\n", "type": "array", "items": { "example": "foo", "minLength": 1, "type": "string" }, "example": [ "foo", "bar" ], "maxItems": 50, "minItems": 1 } }, "type": "object" }, "header": { "description": "Controls which headers go into the Cache Key. Exactly one of\n`include` or `exclude` is expected.\n", "properties": { "check_presence": { "description": "A list of headers to check for the presence of, without\nincluding their actual values.\n", "type": "array", "items": { "example": "foo", "minLength": 1, "type": "string" }, "example": [ "foo", "bar" ], "maxItems": 50, "minItems": 1 }, "exclude": { "description": "A list of headers to ignore.\n", "type": "array", "items": { "example": "foo", "minLength": 1, "type": "string" }, "example": [ "foo", "bar" ], "maxItems": 50, "minItems": 1 }, "include": { "description": "A list of headers to include.\n", "type": "array", "items": { "example": "foo", "minLength": 1, "type": "string" }, "example": [ "foo", "bar" ], "maxItems": 50, "minItems": 1 } }, "type": "object" }, "host": { "description": "Determines which host header to include in the Cache Key.\n", "properties": { "resolved": { "description": "Whether to include the Host header in the HTTP request sent\nto the origin.\n", "type": "boolean" } }, "type": "object" }, "query_string": { "description": "Controls which URL query string parameters go into the Cache\nKey. Exactly one of `include` or `exclude` is expected.\n", "properties": { "exclude": { "oneOf": [ { "description": "Ignore all query string parameters.\n", "enum": [ "*" ], "type": "string" }, { "description": "A list of query string parameters to ignore.\n", "example": [ "foo", "bar" ], "items": { "example": "foo", "minLength": 1, "type": "string" }, "maxItems": 50, "minItems": 1, "type": "array" } ] }, "include": { "oneOf": [ { "description": "Include all query string parameters.\n", "enum": [ "*" ], "type": "string" }, { "description": "A list of query string parameters to include.\n", "example": [ "foo", "bar" ], "items": { "example": "foo", "minLength": 1, "type": "string" }, "maxItems": 50, "minItems": 1, "type": "array" } ] } }, "type": "object" }, "user": { "description": "Feature fields to add features about the end-user (client) into\nthe Cache Key.\n", "properties": { "device_type": { "description": "Classifies a request as `mobile`, `desktop`, or `tablet`\nbased on the User Agent.\n", "type": "boolean" }, "geo": { "description": "Includes the client's country, derived from the IP address.\n", "type": "boolean" }, "lang": { "description": "Includes the first language code contained in the\n`Accept-Language` header sent by the client.\n", "type": "boolean" } }, "type": "object" } } } }, "title": "Custom Cache Key", "x-stainless-skip": [ "terraform" ] }, "zones_cache_level": { "type": "object", "properties": { "id": { "description": "Apply custom caching based on the option selected.\n", "type": "string", "enum": [ "cache_level" ], "x-auditable": true }, "value": { "description": "* `bypass`: Cloudflare does not cache.\n* `basic`: Delivers resources from cache when there is no query\n string.\n* `simplified`: Delivers the same resource to everyone independent\n of the query string.\n* `aggressive`: Caches all static content that has a query string.\n* `cache_everything`: Treats all content as static and caches all\n file types beyond the [Cloudflare default cached\n content](https://developers.cloudflare.com/cache/concepts/default-cache-behavior/#default-cached-file-extensions).\n", "type": "string", "example": "bypass", "enum": [ "bypass", "basic", "simplified", "aggressive", "cache_everything" ], "x-auditable": true } }, "title": "Cache Level", "x-stainless-skip": [ "terraform" ] }, "zones_cache_level-2": { "description": "Cache Level functions based off the setting level. The basic setting will cache most static resources (i.e., css, images, and JavaScript). The simplified setting will ignore the query string when delivering a cached resource. The aggressive setting will cache all static resources, including ones with a query string. (https://support.cloudflare.com/hc/en-us/articles/200168256).", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "cache_level", "enum": [ "cache_level" ] }, "value": { "$ref": "#/components/schemas/zones_cache_level_value" } } } ], "title": "Cloudflare Cache Level" }, "zones_cache_level_value": { "description": "Value of the zone setting.", "type": "string", "default": "aggressive", "enum": [ "aggressive", "basic", "simplified" ] }, "zones_cache_on_cookie": { "type": "object", "properties": { "id": { "description": "Apply the Cache Everything option (Cache Level setting) based on a\nregular expression match against a cookie name.\n", "type": "string", "enum": [ "cache_on_cookie" ], "x-auditable": true }, "value": { "description": "The regular expression to use for matching cookie names in the\nrequest.\n", "type": "string", "example": "bypass=.*|PHPSESSID=.*", "maxLength": 150, "minLength": 1, "x-auditable": true } }, "title": "Cache on Cookie", "x-stainless-skip": [ "terraform" ] }, "zones_cache_ttl_by_status": { "type": "object", "properties": { "id": { "description": "Enterprise customers can set cache time-to-live (TTL) based on the\nresponse status from the origin web server. Cache TTL refers to the\nduration of a resource in the Cloudflare network before being\nmarked as stale or discarded from cache. Status codes are returned\nby a resource's origin. Setting cache TTL based on response status\noverrides the default cache behavior (standard caching) for static\nfiles and overrides cache instructions sent by the origin web\nserver. To cache non-static assets, set a Cache Level of Cache\nEverything using a Page Rule. Setting no-store Cache-Control or a\nlow TTL (using `max-age`/`s-maxage`) increases requests to origin\nweb servers and decreases performance.\n", "type": "string", "enum": [ "cache_ttl_by_status" ], "x-auditable": true }, "value": { "description": "A JSON object containing status codes and their corresponding TTLs.\nEach key-value pair in the cache TTL by status cache rule has the\nfollowing syntax\n- `status_code`: An integer value such as 200 or 500. status_code\n matches the exact status code from the origin web server. Valid\n status codes are between 100-999.\n- `status_code_range`: Integer values for from and to.\n status_code_range matches any status code from the origin web\n server within the specified range.\n- `value`: An integer value that defines the duration an asset is\n valid in seconds or one of the following strings: no-store\n (equivalent to -1), no-cache (equivalent to 0).\n", "type": "object", "example": { "200-299": 86400, "300-499": "no-cache", "500-599": "no-store" }, "additionalProperties": { "anyOf": [ { "description": "`no-store` (equivalent to -1), `no-cache` (equivalent to 0)\n", "enum": [ "no-cache", "no-store" ], "example": "no-cache", "type": "string" }, { "description": "An integer value that defines the duration an asset is valid in\nseconds.\n", "example": 86400, "type": "integer" } ] } } }, "title": "Cache TTL by Status Code", "x-stainless-skip": [ "terraform" ] }, "zones_challenge_ttl": { "description": "Specify how long a visitor is allowed access to your site after successfully completing a challenge (such as a CAPTCHA). After the TTL has expired the visitor will have to complete a new challenge. We recommend a 15 - 45 minute setting and will attempt to honor any setting above 45 minutes. (https://support.cloudflare.com/hc/en-us/articles/200170136).", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "challenge_ttl", "enum": [ "challenge_ttl" ] }, "value": { "$ref": "#/components/schemas/zones_challenge_ttl_value" } } } ], "title": "Challenge Page TTL" }, "zones_challenge_ttl_value": { "description": "Value of the zone setting.", "type": "number", "default": 1800, "enum": [ 300, 900, 1800, 2700, 3600, 7200, 10800, 14400, 28800, 57600, 86400, 604800, 2592000, 31536000 ] }, "zones_china_network_enabled": { "description": "Determines whether or not the china network is enabled.\n", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "china_network_enabled", "enum": [ "china_network_enabled" ] }, "value": { "$ref": "#/components/schemas/zones_china_network_enabled_value" } } } ], "title": "China Network Enabled" }, "zones_china_network_enabled_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ], "readOnly": true }, "zones_ciphers": { "description": "An allowlist of ciphers for TLS termination. These ciphers must be in the BoringSSL format.", "default": [], "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "ciphers", "enum": [ "ciphers" ] }, "value": { "$ref": "#/components/schemas/zones_ciphers_value" } } } ], "title": "Zone ciphers allowed for TLS termination" }, "zones_ciphers_value": { "description": "Value of the zone setting.", "type": "array", "items": { "type": "string" }, "example": [ "ECDHE-RSA-AES128-GCM-SHA256", "AES128-SHA" ], "default": [], "uniqueItems": true }, "zones_cname_flattening": { "description": "Whether or not cname flattening is on.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "How to flatten the cname destination.", "enum": [ "cname_flattening" ] }, "value": { "$ref": "#/components/schemas/zones_cname_flattening_value" } } } ], "deprecated": true, "title": "Cloudflare CNAME Flattening", "x-stainless-deprecation-message": "This zone setting is deprecated; please use the DNS Settings route instead. More information at https://developers.cloudflare.com/fundamentals/api/reference/deprecations/#2025-03-21" }, "zones_cname_flattening_value": { "description": "Value of the cname flattening setting.", "type": "string", "default": "flatten_at_root", "deprecated": true, "enum": [ "flatten_at_root", "flatten_all" ], "x-stainless-deprecation-message": "This zone setting is deprecated; please use the DNS Settings route instead. More information at https://developers.cloudflare.com/fundamentals/api/reference/deprecations/#2025-03-21" }, "zones_content_converter": { "description": "When enabled and the client sends an Accept header requesting text/markdown,\nCloudflare will convert HTML responses to Markdown format using the toMarkdown() service.\nRefer to the [developer documentation](https://developers.cloudflare.com/workers-ai/features/markdown-conversion/) for more information.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "content_converter", "enum": [ "content_converter" ] }, "value": { "$ref": "#/components/schemas/zones_content_converter_value" } } } ], "title": "Content Converter" }, "zones_content_converter_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "off", "on" ] }, "zones_created_on": { "description": "The timestamp of when the Page Rule was created.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true, "x-auditable": true }, "zones_development_mode": { "description": "Development Mode temporarily allows you to enter development mode for your websites if you need to make changes to your site. This will bypass Cloudflare's accelerated cache and slow down your site, but is useful if you are making changes to cacheable content (like images, css, or JavaScript) and would like to see those changes right away. Once entered, development mode will last for 3 hours and then automatically toggle off.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "development_mode", "enum": [ "development_mode" ] }, "time_remaining": { "description": "Value of the zone setting.\nNotes: The interval (in seconds) from when development mode expires (positive integer) or last expired (negative integer) for the domain. If development mode has never been enabled, this value is false.", "type": "number", "example": 3600, "readOnly": true }, "value": { "$ref": "#/components/schemas/zones_development_mode_value" } } } ], "title": "Development Mode" }, "zones_development_mode_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_disable_apps": { "type": "object", "properties": { "id": { "description": "Turn off all active [Cloudflare Apps](https://developers.cloudflare.com/support/more-dashboard-apps/cloudflare-apps/)\n(deprecated).\n", "type": "string", "enum": [ "disable_apps" ], "x-auditable": true } }, "title": "Disable Apps", "x-stainless-skip": [ "terraform" ] }, "zones_disable_performance": { "type": "object", "properties": { "id": { "description": "Turn off\n[Rocket Loader](https://developers.cloudflare.com/speed/optimization/content/rocket-loader/), and\n[Polish](https://developers.cloudflare.com/images/polish/).\n", "type": "string", "enum": [ "disable_performance" ], "x-auditable": true } }, "title": "Disable Performance", "x-stainless-skip": [ "terraform" ] }, "zones_disable_security": { "type": "object", "properties": { "id": { "description": "Turn off\n[Email Obfuscation](https://developers.cloudflare.com/waf/tools/scrape-shield/email-address-obfuscation/),\n[Rate Limiting (previous version, deprecated)](https://developers.cloudflare.com/waf/reference/legacy/old-rate-limiting/),\n[Scrape Shield](https://developers.cloudflare.com/waf/tools/scrape-shield/),\n[URL (Zone) Lockdown](https://developers.cloudflare.com/waf/tools/zone-lockdown/), and\n[WAF managed rules (previous version, deprecated)](https://developers.cloudflare.com/waf/reference/legacy/old-waf-managed-rules/).\n", "type": "string", "enum": [ "disable_security" ], "x-auditable": true } }, "title": "Disable Security", "x-stainless-skip": [ "terraform" ] }, "zones_disable_zaraz": { "type": "object", "properties": { "id": { "description": "Turn off [Zaraz](https://developers.cloudflare.com/zaraz/).\n", "type": "string", "enum": [ "disable_zaraz" ], "x-auditable": true } }, "title": "Disable Zaraz", "x-stainless-skip": [ "terraform" ] }, "zones_early_hints": { "description": "When enabled, Cloudflare will attempt to speed up overall page loads by serving `103` responses with `Link` headers from the final response. Refer to [Early Hints](https://developers.cloudflare.com/cache/about/early-hints) for more information.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "early_hints", "enum": [ "early_hints" ] }, "value": { "$ref": "#/components/schemas/zones_early_hints_value" } } } ], "title": "Early Hints" }, "zones_early_hints_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_edge_cache_ttl": { "type": "object", "properties": { "id": { "description": "Specify how long to cache a resource in the Cloudflare global\nnetwork. *Edge Cache TTL* is not visible in response headers.\n", "type": "string", "enum": [ "edge_cache_ttl" ], "x-auditable": true }, "value": { "type": "integer", "maximum": 31536000, "minimum": 1, "x-auditable": true } }, "title": "Edge Cache TTL", "x-stainless-skip": [ "terraform" ] }, "zones_edge_cache_ttl-2": { "description": "Time (in seconds) that a resource will be ensured to remain on Cloudflare's cache servers.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "edge_cache_ttl", "enum": [ "edge_cache_ttl" ] }, "value": { "$ref": "#/components/schemas/zones_edge_cache_ttl_value" } } } ], "title": "Edge Cache TTL" }, "zones_edge_cache_ttl_value": { "description": "Value of the zone setting.\nNotes: The minimum TTL available depends on the plan level of the zone. (Enterprise = 30, Business = 1800, Pro = 3600, Free = 7200)", "type": "number", "default": 7200, "enum": [ 30, 60, 300, 1200, 1800, 3600, 7200, 10800, 14400, 18000, 28800, 43200, 57600, 72000, 86400, 172800, 259200, 345600, 432000, 518400, 604800 ] }, "zones_email_obfuscation": { "type": "object", "properties": { "id": { "description": "Turn on or off **Email Obfuscation**.", "type": "string", "enum": [ "email_obfuscation" ], "x-auditable": true }, "value": { "description": "The status of Email Obfuscation.\n", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "title": "Email Obfuscation", "x-stainless-skip": [ "terraform" ] }, "zones_email_obfuscation-2": { "description": "Encrypt email adresses on your web page from bots, while keeping them visible to humans. (https://support.cloudflare.com/hc/en-us/articles/200170016).", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "email_obfuscation", "enum": [ "email_obfuscation" ] }, "value": { "$ref": "#/components/schemas/zones_email_obfuscation_value" } } } ], "title": "Email Obfuscation" }, "zones_email_obfuscation_value": { "description": "Value of the zone setting.", "type": "string", "default": "on", "enum": [ "on", "off" ] }, "zones_explicit_cache_control": { "type": "object", "properties": { "id": { "description": "Origin Cache Control is enabled by default for Free, Pro, and\nBusiness domains and disabled by default for Enterprise domains.\n", "type": "string", "enum": [ "explicit_cache_control" ], "x-auditable": true }, "value": { "description": "The status of Origin Cache Control.\n", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "title": "Origin Cache Control", "x-stainless-skip": [ "terraform" ] }, "zones_forwarding_url": { "type": "object", "properties": { "id": { "description": "Redirects one URL to another using an `HTTP 301/302` redirect. Refer\nto [Wildcard matching and referencing](https://developers.cloudflare.com/rules/page-rules/reference/wildcard-matching/).\n", "type": "string", "example": "forwarding_url", "enum": [ "forwarding_url" ], "x-auditable": true }, "value": { "properties": { "status_code": { "description": "The status code to use for the URL redirect. 301 is a permanent\nredirect. 302 is a temporary redirect.\n", "enum": [ 301, 302 ], "example": "temporary", "type": "integer", "x-auditable": true }, "url": { "description": "The URL to redirect the request to.\nNotes: ${num} refers to the position of '*' in the constraint value.", "example": "http://www.example.com/somewhere/$1/astring/$2/anotherstring/$3", "maxLength": 1500, "type": "string", "x-auditable": true } } } }, "title": "Forwarding URL", "x-stainless-skip": [ "terraform" ] }, "zones_h2_prioritization": { "description": "HTTP/2 Edge Prioritization optimises the delivery of resources served through HTTP/2 to improve page load performance. It also supports fine control of content delivery when used in conjunction with Workers.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "h2_prioritization", "enum": [ "h2_prioritization" ] }, "value": { "$ref": "#/components/schemas/zones_h2_prioritization_value" } } } ], "title": "HTTP/2 Edge Prioritization" }, "zones_h2_prioritization_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "on", "off", "custom" ] }, "zones_host_header_override": { "type": "object", "properties": { "id": { "description": "Apply a specific host header.", "type": "string", "enum": [ "host_header_override" ], "x-auditable": true }, "value": { "description": "The hostname to use in the `Host` header", "type": "string", "example": "example.com", "minLength": 1, "x-auditable": true } }, "title": "Host Header Override", "x-stainless-skip": [ "terraform" ] }, "zones_hotlink_protection": { "description": "When enabled, the Hotlink Protection option ensures that other sites cannot suck up your bandwidth by building pages that use images hosted on your site. Anytime a request for an image on your site hits Cloudflare, we check to ensure that it's not another site requesting them. People will still be able to download and view images from your page, but other sites won't be able to steal them for use on their own pages. (https://support.cloudflare.com/hc/en-us/articles/200170026).", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "hotlink_protection", "enum": [ "hotlink_protection" ] }, "value": { "$ref": "#/components/schemas/zones_hotlink_protection_value" } } } ], "title": "Hotlink Protection" }, "zones_hotlink_protection_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_http2": { "description": "HTTP2 enabled for this zone.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "http2", "enum": [ "http2" ] }, "value": { "$ref": "#/components/schemas/zones_http2_value" } } } ], "title": "HTTP2 Value" }, "zones_http2_value": { "description": "Value of the HTTP2 setting.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_http3": { "description": "HTTP3 enabled for this zone.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "http3", "enum": [ "http3" ] }, "value": { "$ref": "#/components/schemas/zones_http3_value" } } } ], "title": "HTTP3 Value" }, "zones_http3_value": { "description": "Value of the HTTP3 setting.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_identifier": { "description": "Identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32 }, "zones_identifier-2": { "description": "Identifier.", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "zones_image_resizing": { "description": "Image Transformations provides on-demand resizing, conversion and optimization for images served through Cloudflare's network. Refer to the [Image Transformations documentation](https://developers.cloudflare.com/images/) for more information.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "image_resizing", "enum": [ "image_resizing" ] }, "value": { "$ref": "#/components/schemas/zones_image_resizing_value" } } } ], "title": "Image Transformations" }, "zones_image_resizing_value": { "description": "Whether the feature is enabled, disabled, or enabled in `open proxy` mode.", "type": "string", "default": "off", "enum": [ "on", "off", "open" ] }, "zones_ip_geolocation": { "type": "object", "properties": { "id": { "description": "Cloudflare adds a CF-IPCountry HTTP header containing the country code that corresponds to the visitor.\n", "type": "string", "example": "ip_geolocation", "enum": [ "ip_geolocation" ], "x-auditable": true }, "value": { "description": "The status of adding the IP Geolocation Header.\n", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "title": "IP Geolocation Header", "x-stainless-skip": [ "terraform" ] }, "zones_ip_geolocation-2": { "description": "Enable IP Geolocation to have Cloudflare geolocate visitors to your website and pass the country code to you. (https://support.cloudflare.com/hc/en-us/articles/200168236).", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "ip_geolocation", "enum": [ "ip_geolocation" ] }, "value": { "$ref": "#/components/schemas/zones_ip_geolocation_value" } } } ], "title": "IP Geolocation" }, "zones_ip_geolocation_value": { "description": "Value of the zone setting.", "type": "string", "default": "on", "enum": [ "on", "off" ] }, "zones_ipv6": { "description": "Enable IPv6 on all subdomains that are Cloudflare enabled. (https://support.cloudflare.com/hc/en-us/articles/200168586).", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "ipv6", "enum": [ "ipv6" ] }, "value": { "$ref": "#/components/schemas/zones_ipv6_value" } } } ], "title": "IPv6" }, "zones_ipv6_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "off", "on" ] }, "zones_max_upload": { "description": "Maximum size of an allowable upload.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "identifier of the zone setting.", "example": "max_upload", "enum": [ "max_upload" ] }, "value": { "$ref": "#/components/schemas/zones_max_upload_value" } } } ], "title": "Max Upload" }, "zones_max_upload_value": { "description": "Value of the zone setting.\nNotes: The size depends on the plan level of the zone. (Enterprise = 5000, Business = 200, Pro = 100, Free = 100)", "type": "integer", "default": 100, "enum": [ 100, 125, 150, 175, 200, 225, 250, 275, 300, 325, 350, 375, 400, 425, 450, 475, 500, 1000, 1500, 2000, 2500, 3000, 3500, 4000, 4500, 5000 ] }, "zones_messages": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "zones_messages-2": { "type": "array", "items": { "properties": { "code": { "type": "integer", "minimum": 1000 }, "documentation_url": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" } } } }, "required": [ "code", "message" ], "type": "object", "uniqueItems": true }, "example": [] }, "zones_min_tls_version": { "description": "Only accepts HTTPS requests that use at least the TLS protocol version specified. For example, if TLS 1.1 is selected, TLS 1.0 connections will be rejected, while 1.1, 1.2, and 1.3 (if enabled) will be permitted.", "default": "1.0", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "min_tls_version", "enum": [ "min_tls_version" ] }, "value": { "$ref": "#/components/schemas/zones_min_tls_version_value" } } } ], "title": "Zone Minimum TLS Version value" }, "zones_min_tls_version_value": { "description": "Value of the zone setting.", "type": "string", "default": "1.0", "enum": [ "1.0", "1.1", "1.2", "1.3" ] }, "zones_mirage": { "type": "object", "properties": { "id": { "description": "Cloudflare Mirage reduces bandwidth used by images in mobile browsers.\nIt can accelerate loading of image-heavy websites on very slow mobile connections and HTTP/1.\n", "type": "string", "example": "mirage", "enum": [ "mirage" ], "x-auditable": true }, "value": { "description": "The status of Mirage.\n", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "deprecated": true, "title": "Mirage", "x-stainless-deprecation-message": "Mirage is deprecated. This functionality is no longer supported. \nSee https://developers.cloudflare.com/fundamentals/api/reference/deprecations/#2025-11-03 for further details.\n", "x-stainless-skip": [ "terraform" ] }, "zones_mirage-2": { "description": "Automatically optimize image loading for website visitors on mobile\ndevices. Refer to [our blog post](http://blog.cloudflare.com/mirage2-solving-mobile-speed)\nfor more information.\n", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "mirage", "enum": [ "mirage" ] }, "value": { "$ref": "#/components/schemas/zones_mirage_value" } } } ], "deprecated": true, "title": "Mirage Image Optimization", "x-stainless-deprecation-message": "Mirage is being deprecated. More information at https://developers.cloudflare.com/speed/optimization/images/mirage/" }, "zones_mirage_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "deprecated": true, "enum": [ "on", "off" ], "x-stainless-deprecation-message": "Mirage is being deprecated. More information at https://developers.cloudflare.com/speed/optimization/images/mirage/" }, "zones_modified_on": { "description": "The timestamp of when the Page Rule was last modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true, "x-auditable": true }, "zones_multiple_settings": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/zones_0rtt" }, { "$ref": "#/components/schemas/zones_advanced_ddos" }, { "$ref": "#/components/schemas/zones_cache-rules_aegis" }, { "$ref": "#/components/schemas/zones_always_online" }, { "$ref": "#/components/schemas/zones_always_use_https-2" }, { "$ref": "#/components/schemas/zones_automatic_https_rewrites-2" }, { "$ref": "#/components/schemas/zones_brotli" }, { "$ref": "#/components/schemas/zones_browser_cache_ttl-2" }, { "$ref": "#/components/schemas/zones_browser_check-2" }, { "$ref": "#/components/schemas/zones_cache_level-2" }, { "$ref": "#/components/schemas/zones_challenge_ttl" }, { "$ref": "#/components/schemas/zones_china_network_enabled" }, { "$ref": "#/components/schemas/zones_content_converter" }, { "$ref": "#/components/schemas/zones_ciphers" }, { "$ref": "#/components/schemas/zones_cname_flattening" }, { "$ref": "#/components/schemas/zones_development_mode" }, { "$ref": "#/components/schemas/zones_early_hints" }, { "$ref": "#/components/schemas/zones_edge_cache_ttl-2" }, { "$ref": "#/components/schemas/zones_email_obfuscation-2" }, { "$ref": "#/components/schemas/zones_h2_prioritization" }, { "$ref": "#/components/schemas/zones_hotlink_protection" }, { "$ref": "#/components/schemas/zones_http2" }, { "$ref": "#/components/schemas/zones_http3" }, { "$ref": "#/components/schemas/zones_ip_geolocation-2" }, { "$ref": "#/components/schemas/zones_ipv6" }, { "$ref": "#/components/schemas/zones_max_upload" }, { "$ref": "#/components/schemas/zones_min_tls_version" }, { "$ref": "#/components/schemas/zones_mirage-2" }, { "$ref": "#/components/schemas/zones_nel" }, { "$ref": "#/components/schemas/zones_opportunistic_encryption-2" }, { "$ref": "#/components/schemas/zones_opportunistic_onion" }, { "$ref": "#/components/schemas/zones_orange_to_orange" }, { "$ref": "#/components/schemas/zones_origin_error_page_pass_thru-2" }, { "$ref": "#/components/schemas/zones_cache-rules_origin_h2_max_streams" }, { "$ref": "#/components/schemas/zones_cache-rules_origin_max_http_version" }, { "$ref": "#/components/schemas/zones_polish-2" }, { "$ref": "#/components/schemas/zones_prefetch_preload" }, { "$ref": "#/components/schemas/zones_pre_render" }, { "$ref": "#/components/schemas/zones_privacy_pass" }, { "$ref": "#/components/schemas/zones_proxy_read_timeout" }, { "$ref": "#/components/schemas/zones_pseudo_ipv4" }, { "$ref": "#/components/schemas/zones_redirects_for_ai_training" }, { "$ref": "#/components/schemas/zones_replace_insecure_js" }, { "$ref": "#/components/schemas/zones_response_buffering-2" }, { "$ref": "#/components/schemas/zones_rocket_loader-2" }, { "$ref": "#/components/schemas/zones_schemas-automatic_platform_optimization" }, { "$ref": "#/components/schemas/zones_search_for_agents" }, { "$ref": "#/components/schemas/zones_security_header" }, { "$ref": "#/components/schemas/zones_security_level-2" }, { "$ref": "#/components/schemas/zones_server_side_exclude" }, { "$ref": "#/components/schemas/zones_sha1_support" }, { "$ref": "#/components/schemas/zones_sort_query_string_for_cache-2" }, { "$ref": "#/components/schemas/zones_ssl-2" }, { "$ref": "#/components/schemas/zones_ssl_recommender" }, { "$ref": "#/components/schemas/zones_tls_1_2_only" }, { "$ref": "#/components/schemas/zones_tls_1_3" }, { "$ref": "#/components/schemas/zones_tls_client_auth" }, { "$ref": "#/components/schemas/zones_true_client_ip_header-2" }, { "$ref": "#/components/schemas/zones_waf-2" }, { "$ref": "#/components/schemas/zones_webmcp_enabled" }, { "$ref": "#/components/schemas/zones_webmcp_packs" }, { "$ref": "#/components/schemas/zones_webp" }, { "$ref": "#/components/schemas/zones_websockets" } ] } }, "zones_name": { "description": "The domain name. Per [RFC 1035](https://datatracker.ietf.org/doc/html/rfc1035#section-2.3.4) the overall zone name can be up to 253 characters, with each segment (\"label\") not exceeding 63 characters.", "type": "string", "example": "example.com", "maxLength": 253, "pattern": "^([a-zA-Z0-9][\\-a-zA-Z0-9]*\\.)+[\\-a-zA-Z0-9]{2,20}$", "x-auditable": true }, "zones_nel": { "description": "Enable Network Error Logging reporting on your zone. (Beta) ", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "Zone setting identifier.", "example": "nel", "enum": [ "nel" ] }, "value": { "$ref": "#/components/schemas/zones_nel_value" } } } ], "title": "Network Error Logging" }, "zones_nel_value": { "description": "Value of the zone setting.", "type": "object", "properties": { "enabled": { "type": "boolean", "example": false, "default": false } }, "default": { "enabled": false } }, "zones_opportunistic_encryption": { "type": "object", "properties": { "id": { "description": "Opportunistic Encryption allows browsers to access HTTP URIs over an encrypted TLS channel.\nIt's not a substitute for HTTPS, but provides additional security for otherwise vulnerable requests.\n", "type": "string", "example": "opportunistic_encryption", "enum": [ "opportunistic_encryption" ], "x-auditable": true }, "value": { "description": "The status of Opportunistic Encryption.\n", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "title": "Opportunistic Encryption", "x-stainless-skip": [ "terraform" ] }, "zones_opportunistic_encryption-2": { "description": "Enables the Opportunistic Encryption feature for a zone.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "opportunistic_encryption", "enum": [ "opportunistic_encryption" ] }, "value": { "$ref": "#/components/schemas/zones_opportunistic_encryption_value" } } } ], "title": "Enable Opportunistic Encryption for a zone" }, "zones_opportunistic_encryption_value": { "description": "Value of the zone setting.\nNotes: Default value depends on the zone's plan level.", "type": "string", "default": "on", "enum": [ "on", "off" ] }, "zones_opportunistic_onion": { "description": "Add an Alt-Svc header to all legitimate requests from Tor, allowing the connection to use our onion services instead of exit nodes.", "default": "off", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "opportunistic_onion", "enum": [ "opportunistic_onion" ] }, "value": { "$ref": "#/components/schemas/zones_opportunistic_onion_value" } } } ], "title": "Zone Enable Onion Routing" }, "zones_opportunistic_onion_value": { "description": "Value of the zone setting.\nNotes: Default value depends on the zone's plan level.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_orange_to_orange": { "description": "Orange to Orange (O2O) allows zones on Cloudflare to CNAME to other zones also on Cloudflare.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "orange_to_orange", "enum": [ "orange_to_orange" ] }, "value": { "$ref": "#/components/schemas/zones_orange_to_orange_value" } } } ], "deprecated": true, "title": "Orange to Orange", "x-stainless-deprecation-message": "This setting is deprecated. Orange to Orange (O2O) is applied automatically for eligible zones and no longer requires configuration; this setting only controlled the legacy O2O v1 (Managed CNAME) path. More information at https://developers.cloudflare.com/fundamentals/api/reference/deprecations/" }, "zones_orange_to_orange_value": { "description": "Value of the zone setting.", "type": "string", "default": "on", "deprecated": true, "enum": [ "on", "off" ], "x-stainless-deprecation-message": "This setting is deprecated. Orange to Orange (O2O) is applied automatically for eligible zones and no longer requires configuration; this setting only controlled the legacy O2O v1 (Managed CNAME) path. More information at https://developers.cloudflare.com/fundamentals/api/reference/deprecations/" }, "zones_origin_error_page_pass_thru": { "type": "object", "properties": { "id": { "description": "Turn on or off Cloudflare error pages generated from issues sent from the origin server. If enabled, this setting triggers error pages issued by the origin.\n", "type": "string", "example": "origin_error_page_pass_thru", "enum": [ "origin_error_page_pass_thru" ], "x-auditable": true }, "value": { "description": "The status of Origin Error Page Passthru.\n", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "title": "Origin Error Page Passthru", "x-stainless-skip": [ "terraform" ] }, "zones_origin_error_page_pass_thru-2": { "description": "Cloudflare will proxy customer error pages on any 502,504 errors on origin server instead of showing a default Cloudflare error page. This does not apply to 522 errors and is limited to Enterprise Zones.", "default": "off", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "origin_error_page_pass_thru", "enum": [ "origin_error_page_pass_thru" ] }, "value": { "$ref": "#/components/schemas/zones_origin_error_page_pass_thru_value" } } } ], "title": "Error Pages On" }, "zones_origin_error_page_pass_thru_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_page_rule": { "type": "object", "properties": { "actions": { "$ref": "#/components/schemas/zones_actions" }, "created_on": { "$ref": "#/components/schemas/zones_created_on" }, "id": { "$ref": "#/components/schemas/zones_identifier-2" }, "modified_on": { "$ref": "#/components/schemas/zones_modified_on" }, "priority": { "$ref": "#/components/schemas/zones_priority" }, "status": { "$ref": "#/components/schemas/zones_status" }, "targets": { "$ref": "#/components/schemas/zones_targets" } }, "required": [ "id", "targets", "actions", "priority", "status", "modified_on", "created_on" ] }, "zones_paused": { "description": "Indicates whether the zone is only using Cloudflare DNS services. A\ntrue value means the zone will not receive security or performance\nbenefits.\n", "type": "boolean", "default": false }, "zones_polish": { "type": "object", "properties": { "id": { "description": "Apply options from the Polish feature of the Cloudflare Speed app.\n", "type": "string", "example": "polish", "enum": [ "polish" ], "x-auditable": true }, "value": { "description": "The level of Polish you want applied to your origin.\n", "type": "string", "example": "lossless", "enum": [ "off", "lossless", "lossy" ], "x-auditable": true } }, "title": "Polish", "x-stainless-skip": [ "terraform" ] }, "zones_polish-2": { "description": "Removes metadata and compresses your images for faster page load times. Basic (Lossless): Reduce the size of PNG, JPEG, and GIF files - no impact on visual quality. Basic + JPEG (Lossy): Further reduce the size of JPEG files for faster image loading. Larger JPEGs are converted to progressive images, loading a lower-resolution image first and ending in a higher-resolution version. Not recommended for hi-res photography sites.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "polish", "enum": [ "polish" ] }, "value": { "$ref": "#/components/schemas/zones_polish_value" } } } ], "title": "Polish Image Optimization" }, "zones_polish_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "off", "lossless", "lossy" ] }, "zones_pre_render": { "description": "When enabled, Cloudflare serves pre-rendered HTML to eligible search and\nAI crawlers instead of the origin's unrendered response.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "pre_render", "enum": [ "pre_render" ] }, "value": { "$ref": "#/components/schemas/zones_pre_render_value" } } } ], "title": "Pre-render" }, "zones_pre_render_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "off", "on" ] }, "zones_prefetch_preload": { "description": "Cloudflare will prefetch any URLs that are included in the response headers. This is limited to Enterprise Zones.", "default": "off", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "prefetch_preload", "enum": [ "prefetch_preload" ] }, "value": { "$ref": "#/components/schemas/zones_prefetch_preload_value" } } } ], "title": "Prefetch preload" }, "zones_prefetch_preload_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_priority": { "description": "The priority of the rule, used to define which Page Rule is processed\nover another. A higher number indicates a higher priority. For example,\nif you have a catch-all Page Rule (rule A: `/images/*`) but want a more\nspecific Page Rule to take precedence (rule B: `/images/special/*`),\nspecify a higher priority for rule B so it overrides rule A.\n", "type": "integer", "default": 1, "x-auditable": true }, "zones_privacy_pass": { "description": "Privacy Pass v1 was a browser extension developed by the Privacy Pass Team to improve the browsing experience for your visitors by allowing users to reduce the number of CAPTCHAs shown. (https://support.cloudflare.com/hc/en-us/articles/115001992652-Privacy-Pass).", "default": "off", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "privacy_pass", "enum": [ "privacy_pass" ] }, "value": { "$ref": "#/components/schemas/zones_privacy_pass_value" } } } ], "deprecated": true, "title": "Privacy Pass v1 (deprecated)", "x-stainless-deprecation-message": "Privacy Pass v1 was deprecated in 2023. (Announcement - https://blog.cloudflare.com/privacy-pass-standard/) and (API deprecation details - https://developers.cloudflare.com/fundamentals/api/reference/deprecations/#2024-03-31)" }, "zones_privacy_pass_value": { "description": "Value of the Privacy Pass v1 (deprecated) zone setting", "type": "string", "default": "off", "deprecated": true, "enum": [ "on", "off" ], "x-stainless-deprecation-message": "Privacy Pass v1 was deprecated in 2023. (Announcement - https://blog.cloudflare.com/privacy-pass-standard/) and (API deprecation details - https://developers.cloudflare.com/fundamentals/api/reference/deprecations/#2024-03-31)" }, "zones_proxy_read_timeout": { "description": "Maximum time between two read operations from origin.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "proxy_read_timeout", "enum": [ "proxy_read_timeout" ] }, "value": { "$ref": "#/components/schemas/zones_proxy_read_timeout_value" } } } ], "title": "Proxy Read Timeout" }, "zones_proxy_read_timeout_value": { "description": "Value of the zone setting.\nNotes: Value must be between 1 and 6000", "type": "number", "default": 125 }, "zones_pseudo_ipv4": { "description": "The value set for the Pseudo IPv4 setting.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "Value of the Pseudo IPv4 setting.", "default": "pseudo_ipv4", "enum": [ "pseudo_ipv4" ] }, "value": { "$ref": "#/components/schemas/zones_pseudo_ipv4_value" } } } ], "title": "Pseudo IPv4 Value" }, "zones_pseudo_ipv4_value": { "description": "Value of the Pseudo IPv4 setting.", "type": "string", "default": "off", "enum": [ "off", "add_header", "overwrite_header" ] }, "zones_redirects_for_ai_training": { "description": "When enabled, Cloudflare will redirect verified AI training crawlers to canonical URLs\nfound in the HTML response, ensuring AI models train on authoritative content.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "redirects_for_ai_training", "enum": [ "redirects_for_ai_training" ] }, "value": { "$ref": "#/components/schemas/zones_redirects_for_ai_training_value" } } } ], "title": "Redirects for AI Training" }, "zones_redirects_for_ai_training_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "off", "on" ] }, "zones_replace_insecure_js": { "description": "Automatically replace insecure JavaScript libraries with safer and faster alternatives provided under cdnjs and powered by Cloudflare. Currently supports the following libraries: Polyfill under polyfill.io.\n", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "replace_insecure_js", "enum": [ "replace_insecure_js" ] }, "value": { "$ref": "#/components/schemas/zones_replace_insecure_js_value" } } } ], "title": "Replace insecure JavaScript libraries" }, "zones_replace_insecure_js_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_resolve_override": { "type": "object", "properties": { "id": { "description": "Change the origin address to the value specified in this setting.\n", "type": "string", "example": "resolve_override", "enum": [ "resolve_override" ], "x-auditable": true }, "value": { "description": "The origin address you want to override with.\n", "type": "string", "example": "example.com", "x-auditable": true } }, "title": "Resolve Override", "x-stainless-skip": [ "terraform" ] }, "zones_respect_strong_etag": { "type": "object", "properties": { "id": { "description": "Turn on or off byte-for-byte equivalency checks between the\nCloudflare cache and the origin server.\n", "type": "string", "enum": [ "respect_strong_etag" ], "x-auditable": true }, "value": { "description": "The status of Respect Strong ETags\n", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "title": "Respect Strong ETags", "x-stainless-skip": [ "terraform" ] }, "zones_response_buffering": { "type": "object", "properties": { "id": { "description": "Turn on or off whether Cloudflare should wait for an entire file\nfrom the origin server before forwarding it to the site visitor. By\ndefault, Cloudflare sends packets to the client as they arrive from\nthe origin server.\n", "type": "string", "enum": [ "response_buffering" ], "x-auditable": true }, "value": { "description": "The status of Response Buffering\n", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "deprecated": true, "title": "Response Buffering", "x-stainless-deprecation-message": "This page rule is deprecated. This functionality is no longer supported.", "x-stainless-skip": [ "terraform" ] }, "zones_response_buffering-2": { "description": "Enables or disables buffering of responses from the proxied server. Cloudflare may buffer the whole payload to deliver it at once to the client versus allowing it to be delivered in chunks. By default, the proxied server streams directly and is not buffered by Cloudflare. This is limited to Enterprise Zones.", "default": "off", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "response_buffering", "enum": [ "response_buffering" ] }, "value": { "$ref": "#/components/schemas/zones_response_buffering_value" } } } ], "deprecated": true, "title": "Response Buffering", "x-stainless-deprecation-message": "This zone setting is deprecated. This functionality is no longer supported." }, "zones_response_buffering_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_result_info": { "type": "object", "properties": { "count": { "description": "Total number of results for the requested service.", "type": "number", "example": 1 }, "page": { "description": "Current page within paginated list of results.", "type": "number", "example": 1 }, "per_page": { "description": "Number of results per page of results.", "type": "number", "example": 20 }, "total_count": { "description": "Total results available without any search parameters.", "type": "number", "example": 2000 }, "total_pages": { "description": "Total number of pages", "type": "number", "example": 100 } } }, "zones_rocket_loader": { "type": "object", "properties": { "id": { "description": "Turn on or off Rocket Loader in the Cloudflare Speed app.\n", "type": "string", "enum": [ "rocket_loader" ], "x-auditable": true }, "value": { "description": "The status of Rocket Loader\n", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "title": "Rocket Loader", "x-stainless-skip": [ "terraform" ] }, "zones_rocket_loader-2": { "description": "Rocket Loader is a general-purpose asynchronous JavaScript optimisation that prioritises rendering your content while loading your site's Javascript asynchronously. Turning on Rocket Loader will immediately improve a web page's rendering time sometimes measured as Time to First Paint (TTFP), and also the `window.onload` time (assuming there is JavaScript on the page). This can have a positive impact on your Google search ranking. When turned on, Rocket Loader will automatically defer the loading of all Javascript referenced in your HTML, with no configuration required. Refer to [Understanding Rocket Loader](https://support.cloudflare.com/hc/articles/200168056) for more information.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "rocket_loader", "enum": [ "rocket_loader" ] }, "value": { "$ref": "#/components/schemas/zones_rocket_loader_value" } } } ], "title": "Rocket Loader" }, "zones_rocket_loader_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_schemas-automatic_platform_optimization": { "description": "[Automatic Platform Optimization for WordPress](https://developers.cloudflare.com/automatic-platform-optimization/) serves your WordPress site from Cloudflare's edge network and caches third-party fonts.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "automatic_platform_optimization", "enum": [ "automatic_platform_optimization" ] }, "value": { "$ref": "#/components/schemas/zones_automatic_platform_optimization" } } } ], "title": "Automatic Platform Optimization for WordPress" }, "zones_search_for_agents": { "description": "When enabled, Cloudflare provisions an AI Search instance for the zone\nand exposes a /.well-known/ai-search endpoint that AI agents can query.\nMarkdown responses also receive an agent: YAML capability block advertising\nthe search endpoint.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "search_for_agents", "enum": [ "search_for_agents" ] }, "value": { "$ref": "#/components/schemas/zones_search_for_agents_value" } } } ], "title": "Search for Agents" }, "zones_search_for_agents_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "off", "on" ] }, "zones_security_header": { "description": "Cloudflare security header for a zone.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone's security header.", "example": "security_header", "enum": [ "security_header" ] }, "value": { "$ref": "#/components/schemas/zones_security_header_value" } } } ], "title": "Security Header" }, "zones_security_header_value": { "type": "object", "properties": { "strict_transport_security": { "description": "Strict Transport Security.", "type": "object", "properties": { "enabled": { "description": "Whether or not strict transport security is enabled.", "type": "boolean", "example": true }, "include_subdomains": { "description": "Include all subdomains for strict transport security.", "type": "boolean", "example": true }, "max_age": { "description": "Max age in seconds of the strict transport security.", "type": "number", "example": 86400 }, "nosniff": { "description": "Whether or not to include 'X-Content-Type-Options: nosniff' header.", "type": "boolean", "example": true }, "preload": { "description": "Enable automatic preload of the HSTS configuration.", "type": "boolean", "example": true } } } }, "default": { "strict_transport_security": { "enabled": true, "include_subdomains": true, "max_age": 86400, "nosniff": true, "preload": false } } }, "zones_security_level": { "type": "object", "properties": { "id": { "description": "Control options for the **Security Level** feature from the **Security** app.\n", "type": "string", "enum": [ "security_level" ], "x-auditable": true }, "value": { "type": "string", "example": "under_attack", "enum": [ "off", "essentially_off", "low", "medium", "high", "under_attack" ], "x-auditable": true } }, "title": "Security Level", "x-stainless-skip": [ "terraform" ] }, "zones_security_level-2": { "description": "Choose the appropriate security profile for your website, which will automatically adjust each of the security settings. If you choose to customize an individual security setting, the profile will become Custom. (https://support.cloudflare.com/hc/en-us/articles/200170056).", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "security_level", "enum": [ "security_level" ] }, "value": { "$ref": "#/components/schemas/zones_security_level_value" } } } ], "title": "Security Level" }, "zones_security_level_value": { "description": "Value of the zone setting.", "type": "string", "default": "medium", "enum": [ "off", "essentially_off", "low", "medium", "high", "under_attack" ] }, "zones_server_side_exclude": { "description": "If there is sensitive content on your website that you want visible to real visitors, but that you want to hide from suspicious visitors, all you have to do is wrap the content with Cloudflare SSE tags. Wrap any content that you want to be excluded from suspicious visitors in the following SSE tags: . For example: Bad visitors won't see my phone number, 555-555-5555 . Note: SSE only will work with HTML. If you have HTML minification enabled, you won't see the SSE tags in your HTML source when it's served through Cloudflare. SSE will still function in this case, as Cloudflare's HTML minification and SSE functionality occur on-the-fly as the resource moves through our network to the visitor's computer. (https://support.cloudflare.com/hc/en-us/articles/200170036).", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "server_side_exclude", "enum": [ "server_side_exclude" ] }, "value": { "$ref": "#/components/schemas/zones_server_side_exclude_value" } } } ], "title": "Server Side Exclude" }, "zones_server_side_exclude_value": { "description": "Value of the zone setting.", "type": "string", "default": "on", "enum": [ "on", "off" ] }, "zones_setting": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/zones_0rtt" }, { "$ref": "#/components/schemas/zones_advanced_ddos" }, { "$ref": "#/components/schemas/zones_cache-rules_aegis" }, { "$ref": "#/components/schemas/zones_always_online" }, { "$ref": "#/components/schemas/zones_always_use_https-2" }, { "$ref": "#/components/schemas/zones_automatic_https_rewrites-2" }, { "$ref": "#/components/schemas/zones_brotli" }, { "$ref": "#/components/schemas/zones_browser_cache_ttl-2" }, { "$ref": "#/components/schemas/zones_browser_check-2" }, { "$ref": "#/components/schemas/zones_cache_level-2" }, { "$ref": "#/components/schemas/zones_challenge_ttl" }, { "$ref": "#/components/schemas/zones_china_network_enabled" }, { "$ref": "#/components/schemas/zones_content_converter" }, { "$ref": "#/components/schemas/zones_ciphers" }, { "$ref": "#/components/schemas/zones_cname_flattening" }, { "$ref": "#/components/schemas/zones_development_mode" }, { "$ref": "#/components/schemas/zones_early_hints" }, { "$ref": "#/components/schemas/zones_edge_cache_ttl-2" }, { "$ref": "#/components/schemas/zones_email_obfuscation-2" }, { "$ref": "#/components/schemas/zones_h2_prioritization" }, { "$ref": "#/components/schemas/zones_hotlink_protection" }, { "$ref": "#/components/schemas/zones_http2" }, { "$ref": "#/components/schemas/zones_http3" }, { "$ref": "#/components/schemas/zones_image_resizing" }, { "$ref": "#/components/schemas/zones_ip_geolocation-2" }, { "$ref": "#/components/schemas/zones_ipv6" }, { "$ref": "#/components/schemas/zones_max_upload" }, { "$ref": "#/components/schemas/zones_min_tls_version" }, { "$ref": "#/components/schemas/zones_mirage-2" }, { "$ref": "#/components/schemas/zones_nel" }, { "$ref": "#/components/schemas/zones_opportunistic_encryption-2" }, { "$ref": "#/components/schemas/zones_opportunistic_onion" }, { "$ref": "#/components/schemas/zones_orange_to_orange" }, { "$ref": "#/components/schemas/zones_origin_error_page_pass_thru-2" }, { "$ref": "#/components/schemas/zones_cache-rules_origin_h2_max_streams" }, { "$ref": "#/components/schemas/zones_cache-rules_origin_max_http_version" }, { "$ref": "#/components/schemas/zones_polish-2" }, { "$ref": "#/components/schemas/zones_prefetch_preload" }, { "$ref": "#/components/schemas/zones_pre_render" }, { "$ref": "#/components/schemas/zones_privacy_pass" }, { "$ref": "#/components/schemas/zones_proxy_read_timeout" }, { "$ref": "#/components/schemas/zones_pseudo_ipv4" }, { "$ref": "#/components/schemas/zones_redirects_for_ai_training" }, { "$ref": "#/components/schemas/zones_replace_insecure_js" }, { "$ref": "#/components/schemas/zones_response_buffering-2" }, { "$ref": "#/components/schemas/zones_rocket_loader-2" }, { "$ref": "#/components/schemas/zones_schemas-automatic_platform_optimization" }, { "$ref": "#/components/schemas/zones_search_for_agents" }, { "$ref": "#/components/schemas/zones_security_header" }, { "$ref": "#/components/schemas/zones_security_level-2" }, { "$ref": "#/components/schemas/zones_server_side_exclude" }, { "$ref": "#/components/schemas/zones_sha1_support" }, { "$ref": "#/components/schemas/zones_sort_query_string_for_cache-2" }, { "$ref": "#/components/schemas/zones_ssl-2" }, { "$ref": "#/components/schemas/zones_ssl_recommender" }, { "$ref": "#/components/schemas/zones_tls_1_2_only" }, { "$ref": "#/components/schemas/zones_tls_1_3" }, { "$ref": "#/components/schemas/zones_tls_client_auth" }, { "$ref": "#/components/schemas/zones_transformations" }, { "$ref": "#/components/schemas/zones_transformations_allowed_origins" }, { "$ref": "#/components/schemas/zones_true_client_ip_header-2" }, { "$ref": "#/components/schemas/zones_waf-2" }, { "$ref": "#/components/schemas/zones_webmcp_enabled" }, { "$ref": "#/components/schemas/zones_webmcp_packs" }, { "$ref": "#/components/schemas/zones_webp" }, { "$ref": "#/components/schemas/zones_websockets" } ] }, "zones_setting_name": { "description": "Setting name", "type": "string", "example": "always_online" }, "zones_setting_readonly": { "type": "boolean", "enum": [ false ] }, "zones_setting_toggle": { "description": "Value of the zone setting.", "type": "string", "enum": [ "on", "off" ] }, "zones_setting_value": { "oneOf": [ { "$ref": "#/components/schemas/zones_0rtt_value" }, { "$ref": "#/components/schemas/zones_advanced_ddos_value" }, { "$ref": "#/components/schemas/zones_cache-rules_aegis_value" }, { "$ref": "#/components/schemas/zones_always_online_value" }, { "$ref": "#/components/schemas/zones_always_use_https_value" }, { "$ref": "#/components/schemas/zones_automatic_https_rewrites_value" }, { "$ref": "#/components/schemas/zones_brotli_value" }, { "$ref": "#/components/schemas/zones_browser_cache_ttl_value" }, { "$ref": "#/components/schemas/zones_browser_check_value" }, { "$ref": "#/components/schemas/zones_cache_level_value" }, { "$ref": "#/components/schemas/zones_challenge_ttl_value" }, { "$ref": "#/components/schemas/zones_china_network_enabled_value" }, { "$ref": "#/components/schemas/zones_content_converter_value" }, { "$ref": "#/components/schemas/zones_ciphers_value" }, { "$ref": "#/components/schemas/zones_cname_flattening_value" }, { "$ref": "#/components/schemas/zones_development_mode_value" }, { "$ref": "#/components/schemas/zones_early_hints_value" }, { "$ref": "#/components/schemas/zones_edge_cache_ttl_value" }, { "$ref": "#/components/schemas/zones_email_obfuscation_value" }, { "$ref": "#/components/schemas/zones_h2_prioritization_value" }, { "$ref": "#/components/schemas/zones_hotlink_protection_value" }, { "$ref": "#/components/schemas/zones_http2_value" }, { "$ref": "#/components/schemas/zones_http3_value" }, { "$ref": "#/components/schemas/zones_image_resizing_value" }, { "$ref": "#/components/schemas/zones_ip_geolocation_value" }, { "$ref": "#/components/schemas/zones_ipv6_value" }, { "$ref": "#/components/schemas/zones_max_upload_value" }, { "$ref": "#/components/schemas/zones_min_tls_version_value" }, { "$ref": "#/components/schemas/zones_mirage_value" }, { "$ref": "#/components/schemas/zones_nel_value" }, { "$ref": "#/components/schemas/zones_opportunistic_encryption_value" }, { "$ref": "#/components/schemas/zones_opportunistic_onion_value" }, { "$ref": "#/components/schemas/zones_orange_to_orange_value" }, { "$ref": "#/components/schemas/zones_origin_error_page_pass_thru_value" }, { "$ref": "#/components/schemas/zones_cache-rules_origin_h2_max_streams_value" }, { "$ref": "#/components/schemas/zones_cache-rules_origin_max_http_version_value" }, { "$ref": "#/components/schemas/zones_polish_value" }, { "$ref": "#/components/schemas/zones_prefetch_preload_value" }, { "$ref": "#/components/schemas/zones_pre_render_value" }, { "$ref": "#/components/schemas/zones_privacy_pass_value" }, { "$ref": "#/components/schemas/zones_proxy_read_timeout_value" }, { "$ref": "#/components/schemas/zones_pseudo_ipv4_value" }, { "$ref": "#/components/schemas/zones_redirects_for_ai_training_value" }, { "$ref": "#/components/schemas/zones_replace_insecure_js_value" }, { "$ref": "#/components/schemas/zones_response_buffering_value" }, { "$ref": "#/components/schemas/zones_rocket_loader_value" }, { "$ref": "#/components/schemas/zones_automatic_platform_optimization" }, { "$ref": "#/components/schemas/zones_search_for_agents_value" }, { "$ref": "#/components/schemas/zones_security_header_value" }, { "$ref": "#/components/schemas/zones_security_level_value" }, { "$ref": "#/components/schemas/zones_server_side_exclude_value" }, { "$ref": "#/components/schemas/zones_sha1_support_value" }, { "$ref": "#/components/schemas/zones_sort_query_string_for_cache_value" }, { "$ref": "#/components/schemas/zones_ssl_value" }, { "$ref": "#/components/schemas/zones_tls_1_2_only_value" }, { "$ref": "#/components/schemas/zones_tls_1_3_value" }, { "$ref": "#/components/schemas/zones_tls_client_auth_value" }, { "$ref": "#/components/schemas/zones_true_client_ip_header_value" }, { "$ref": "#/components/schemas/zones_waf_value" }, { "$ref": "#/components/schemas/zones_webmcp_enabled_value" }, { "$ref": "#/components/schemas/zones_webmcp_packs_value" }, { "$ref": "#/components/schemas/zones_webp_value" }, { "$ref": "#/components/schemas/zones_websockets_value" } ] }, "zones_setting_writable": { "type": "boolean", "enum": [ true ] }, "zones_settings": { "description": "Settings available for the zone.", "type": "array", "items": { "type": "object" }, "example": [ { "id": "browser_check", "properties": [ { "type": "toggle", "name": "value" } ] }, { "id": "browser_cache_ttl", "properties": [ { "type": "range", "max": 31536000, "min": 1800, "name": "value", "suggested_values": [ 1800, 3600, 7200, 10800, 14400, 18000, 28800, 43200, 57600, 72000, 86400, 172800, 259200, 345600, 432000, 691200, 1382400, 2073600, 2678400, 5356800, 16070400, 31536000 ] } ] }, { "id": "browser_check", "properties": [ { "type": "toggle", "name": "value" } ] }, { "id": "cache_key_fields", "properties": [ { "type": "object", "name": "value", "properties": [ { "type": "select", "allowEmpty": true, "choices": [ "include", "exclude" ], "multiple": false, "name": "query_string" }, { "type": "select", "allowEmpty": true, "choices": [ "include", "exclude", "check_presence" ], "multiple": true, "name": "header" }, { "type": "select", "allowEmpty": false, "choices": [ "resolved" ], "multiple": true, "name": "host" }, { "type": "select", "allowEmpty": true, "choices": [ "include", "check_presence" ], "multiple": true, "name": "cookie" }, { "type": "select", "allowEmpty": false, "choices": [ "device_type", "geo", "lang" ], "multiple": true, "name": "user" } ] } ] }, { "id": "cache_deception_armor", "properties": [ { "type": "toggle", "name": "value" } ] }, { "id": "cache_level", "properties": [ { "type": "select", "choices": [ "bypass", "basic", "simplified", "aggressive", "cache_everything" ], "multiple": false, "name": "value" } ] }, { "id": "cache_ttl_by_status", "properties": [ { "type": "object", "allowEmpty": false, "name": "value" } ] }, { "id": "disable_apps", "properties": [] }, { "id": "disable_performance", "properties": [] }, { "id": "disable_security", "properties": [] }, { "id": "edge_cache_ttl", "properties": [ { "type": "range", "max": 31536000, "min": 7200, "name": "value", "suggested_values": [ 7200, 10800, 14400, 18000, 28800, 43200, 57600, 72000, 86400, 172800, 259200, 345600, 432000, 518400, 604800, 1209600, 2419200, 31536000 ] } ] }, { "id": "email_obfuscation", "properties": [ { "type": "toggle", "name": "value" } ] }, { "id": "forwarding_url", "properties": [ { "type": "choice", "choices": [ 301, 302 ], "multiple": false, "name": "status_code" }, { "type": "forwardingUrl", "name": "url" } ] }, { "id": "ip_geolocation", "properties": [ { "type": "toggle", "name": "value" } ] }, { "id": "explicit_cache_control", "properties": [ { "type": "toggle", "name": "value" } ] }, { "id": "rocket_loader", "properties": [ { "type": "toggle", "name": "value" } ] }, { "id": "security_level", "properties": [ { "type": "select", "choices": [ "essentially_off", "low", "medium", "high", "under_attack" ], "multiple": false, "name": "value" } ] }, { "id": "server_side_exclude", "properties": [ { "type": "toggle", "name": "value" } ] }, { "id": "ssl", "properties": [ { "type": "choice", "choices": [ "off", "flexible", "full", "strict" ], "multiple": false, "name": "value" } ] } ] }, "zones_sha1_support": { "description": "Allow SHA1 support.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "Zone setting identifier.", "example": "sha1_support", "enum": [ "sha1_support" ] }, "value": { "$ref": "#/components/schemas/zones_sha1_support_value" } } } ], "title": "Toggle SHA1 support" }, "zones_sha1_support_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "off", "on" ] }, "zones_sort_query_string_for_cache": { "type": "object", "properties": { "id": { "description": "Turn on or off the reordering of query strings. When query strings have the same structure, caching improves.\n", "type": "string", "example": "sort_query_string_for_cache", "enum": [ "sort_query_string_for_cache" ], "x-auditable": true }, "value": { "description": "The status of Query String Sort\n", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "title": "Query String Sort", "x-stainless-skip": [ "terraform" ] }, "zones_sort_query_string_for_cache-2": { "description": "Cloudflare will treat files with the same query strings as the same file in cache, regardless of the order of the query strings. This is limited to Enterprise Zones.", "default": "off", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "sort_query_string_for_cache", "enum": [ "sort_query_string_for_cache" ] }, "value": { "$ref": "#/components/schemas/zones_sort_query_string_for_cache_value" } } } ], "title": "Get String Sort" }, "zones_sort_query_string_for_cache_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_ssl": { "type": "object", "properties": { "id": { "description": "Control options for the SSL feature of the Edge Certificates tab in the Cloudflare SSL/TLS app.\n", "type": "string", "enum": [ "ssl" ], "x-auditable": true }, "value": { "description": "The encryption mode that Cloudflare uses to connect to your origin server.\n", "type": "string", "example": "full", "enum": [ "off", "flexible", "full", "strict", "origin_pull" ], "x-auditable": true } }, "title": "SSL", "x-stainless-skip": [ "terraform" ] }, "zones_ssl-2": { "description": "SSL encrypts your visitor's connection and safeguards credit card numbers and other personal data to and from your website. SSL can take up to 5 minutes to fully activate. Requires Cloudflare active on your root domain or www domain. Off: no SSL between the visitor and Cloudflare, and no SSL between Cloudflare and your web server (all HTTP traffic). Flexible: SSL between the visitor and Cloudflare -- visitor sees HTTPS on your site, but no SSL between Cloudflare and your web server. You don't need to have an SSL cert on your web server, but your vistors will still see the site as being HTTPS enabled. Full: SSL between the visitor and Cloudflare -- visitor sees HTTPS on your site, and SSL between Cloudflare and your web server. You'll need to have your own SSL cert or self-signed cert at the very least. Full (Strict): SSL between the visitor and Cloudflare -- visitor sees HTTPS on your site, and SSL between Cloudflare and your web server. You'll need to have a valid SSL certificate installed on your web server. This certificate must be signed by a certificate authority, have an expiration date in the future, and respond for the request domain name (hostname). (https://support.cloudflare.com/hc/en-us/articles/200170416).", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "ssl", "enum": [ "ssl" ] }, "value": { "$ref": "#/components/schemas/zones_ssl_value" } } } ], "title": "SSL" }, "zones_ssl_recommender": { "description": "Enrollment in the SSL/TLS Recommender service which tries to detect and recommend (by sending periodic emails) the most secure SSL/TLS setting your origin servers support.", "allOf": [ { "properties": { "enabled": { "$ref": "#/components/schemas/zones_ssl_recommender_enabled" }, "id": { "description": "Enrollment value for SSL/TLS Recommender.", "example": "ssl_recommender", "enum": [ "ssl_recommender" ] } } } ], "title": "SSL/TLS Recommender" }, "zones_ssl_recommender_enabled": { "description": "ssl-recommender enrollment setting.", "type": "boolean", "default": false }, "zones_ssl_value": { "description": "Value of the zone setting.\nNotes: Depends on the zone's plan level", "type": "string", "default": "off", "enum": [ "off", "flexible", "full", "strict" ] }, "zones_status": { "description": "The status of the Page Rule.", "type": "string", "example": "active", "default": "disabled", "enum": [ "active", "disabled" ], "x-auditable": true }, "zones_string_constraint": { "description": "String constraint.", "type": "object", "properties": { "operator": { "description": "The matches operator can use asterisks and pipes as wildcard and 'or' operators.", "default": "contains", "enum": [ "matches", "contains", "equals", "not_equal", "not_contain" ], "x-auditable": true }, "value": { "description": "The value to apply the operator to.", "type": "string", "x-auditable": true } }, "required": [ "operator", "value" ] }, "zones_target": { "description": "A request condition target.", "oneOf": [ { "$ref": "#/components/schemas/zones_url_target" } ], "required": [ "target", "constraint" ] }, "zones_targets": { "description": "The rule targets to evaluate on each request.", "type": "array", "items": { "$ref": "#/components/schemas/zones_target" }, "example": [ { "constraint": { "operator": "matches", "value": "*example.com/images/*" }, "target": "url" } ], "x-stainless-skip": [ "terraform" ] }, "zones_tls_1_2_only": { "description": "Only allows TLS1.2.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "Zone setting identifier.", "example": "tls_1_2_only", "enum": [ "tls_1_2_only" ] }, "value": { "$ref": "#/components/schemas/zones_tls_1_2_only_value" } } } ], "title": "TLS1.2 only" }, "zones_tls_1_2_only_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "off", "on" ] }, "zones_tls_1_3": { "description": "Enables Crypto TLS 1.3 feature for a zone.", "default": "off", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "tls_1_3", "enum": [ "tls_1_3" ] }, "value": { "$ref": "#/components/schemas/zones_tls_1_3_value" } } } ], "title": "Enable TLS 1.3 value for a zone" }, "zones_tls_1_3_value": { "description": "Value of the zone setting.\nNotes: Default value depends on the zone's plan level.", "type": "string", "default": "off", "enum": [ "on", "off", "zrt" ] }, "zones_tls_client_auth": { "description": "TLS Client Auth requires Cloudflare to connect to your origin server using a client certificate (Enterprise Only).", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "tls_client_auth", "enum": [ "tls_client_auth" ] }, "value": { "$ref": "#/components/schemas/zones_tls_client_auth_value" } } } ], "title": "TLS Client Authentication" }, "zones_tls_client_auth_value": { "description": "value of the zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_transformations": { "description": "Media Transformations provides on-demand resizing, conversion and optimization for images and video served through Cloudflare's network. Refer to the [Image Transformations](https://developers.cloudflare.com/images/) and [Video Transformations](https://developers.cloudflare.com/stream/transform-videos/#getting-started) documentation for more information.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting. Shared between Image Transformations and Video Transformations.", "example": "transformations", "enum": [ "transformations" ] }, "value": { "$ref": "#/components/schemas/zones_image_resizing_value" } } } ], "title": "Media Transformations" }, "zones_transformations_allowed_origins": { "description": "Media Transformations Allowed Origins restricts transformations for images and video served through Cloudflare's network. Refer to the [Image Transformations](https://developers.cloudflare.com/images/) and [Video Transformations](https://developers.cloudflare.com/stream/transform-videos/#getting-started) documentation for more information.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting. Shared between Image Transformations and Video Transformations.", "example": "transformations_allowed_origins", "enum": [ "transformations_allowed_origins" ] }, "value": { "$ref": "#/components/schemas/zones_transformations_allowed_origins_value" } } } ], "title": "Media Transformations Allowed Origins" }, "zones_transformations_allowed_origins_value": { "description": "Comma-separated list of allowed origins.\nRefer to the [Image Transformations](https://developers.cloudflare.com/images/transform-images/sources/) and [Video Transformations](https://developers.cloudflare.com/stream/transform-videos/#getting-started) documentation for more information.", "type": "string" }, "zones_true_client_ip_header": { "type": "object", "properties": { "id": { "description": "Turn on or off the True-Client-IP Header feature of the Cloudflare Network app.\n", "type": "string", "example": "true_client_ip_header", "enum": [ "true_client_ip_header" ], "x-auditable": true }, "value": { "description": "The status of True Client IP Header.\n", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "title": "True Client IP Header", "x-stainless-skip": [ "terraform" ] }, "zones_true_client_ip_header-2": { "description": "Allows customer to continue to use True Client IP (Akamai feature) in the headers we send to the origin. This is limited to Enterprise Zones.", "default": "off", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "true_client_ip_header", "enum": [ "true_client_ip_header" ] }, "value": { "$ref": "#/components/schemas/zones_true_client_ip_header_value" } } } ], "title": "True Client IP Header" }, "zones_true_client_ip_header_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_type": { "description": "A full zone implies that DNS is hosted with Cloudflare. A partial zone is\ntypically a partner-hosted zone or a CNAME setup.\n", "type": "string", "example": "full", "default": "full", "enum": [ "full", "partial", "secondary", "internal" ] }, "zones_url_target": { "description": "URL target.", "type": "object", "properties": { "constraint": { "description": "The constraint of a target.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/zones_string_constraint" }, { "properties": { "value": { "description": "The URL pattern to match against the current request. The pattern may contain up to four asterisks ('*') as placeholders.", "type": "string", "example": "*example.com/images/*", "pattern": "^(https?://)?(([-a-zA-Z0-9*]*\\.)+[-a-zA-Z0-9]{2,20})(:(8080|8443|443|80))?(/[\\S]+)?$", "x-auditable": true } } } ] }, "target": { "description": "A target based on the URL of the request.", "example": "url", "enum": [ "url" ], "x-auditable": true } } }, "zones_vanity_name_servers": { "description": "An array of domains used for custom name servers. This is only\navailable for Business and Enterprise plans.", "type": "array", "items": { "format": "hostname", "maxLength": 253, "type": "string" }, "example": [ "ns1.example.com", "ns2.example.com" ], "default": [] }, "zones_waf": { "type": "object", "properties": { "id": { "description": "Turn on or off [WAF managed rules (previous version, deprecated)](https://developers.cloudflare.com/waf/reference/legacy/old-waf-managed-rules/).\nYou cannot enable or disable individual WAF managed rules via Page Rules.\n", "type": "string", "example": "waf", "enum": [ "waf" ], "x-auditable": true }, "value": { "description": "The status of WAF managed rules (previous version).\n", "type": "string", "example": "on", "enum": [ "on", "off" ], "x-auditable": true } }, "title": "WAF", "x-stainless-skip": [ "terraform" ] }, "zones_waf-2": { "description": "The WAF examines HTTP requests to your website. It inspects both GET and POST requests and applies rules to help filter out illegitimate traffic from legitimate website visitors. The Cloudflare WAF inspects website addresses or URLs to detect anything out of the ordinary. If the Cloudflare WAF determines suspicious user behavior, then the WAF will 'challenge' the web visitor with a page that asks them to submit a CAPTCHA successfully to continue their action. If the challenge is failed, the action will be stopped. What this means is that Cloudflare's WAF will block any traffic identified as illegitimate before it reaches your origin web server. (https://support.cloudflare.com/hc/en-us/articles/200172016).", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "waf", "enum": [ "waf" ] }, "value": { "$ref": "#/components/schemas/zones_waf_value" } } } ], "title": "Web Application Firewall" }, "zones_waf_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "on", "off" ] }, "zones_webmcp_enabled": { "description": "When enabled, Cloudflare injects the WebMCP bridge (bridge.js) into HTML\nresponses for this zone, exposing DOM and Content Credentials tools to an\nin-browser AI agent via navigator.modelContext. No origin-side code\nchanges are required. This setting is currently in beta and its behavior\nmay change.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "webmcp_enabled", "enum": [ "webmcp_enabled" ] }, "value": { "$ref": "#/components/schemas/zones_webmcp_enabled_value" } } } ], "title": "WebMCP Enabled" }, "zones_webmcp_enabled_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "off", "on" ] }, "zones_webmcp_packs": { "description": "Optional per-zone override of which bundled WebMCP tool packs the\ninjected bridge.js activates. Only takes effect when webmcp_enabled is\non. Leave empty to use the bridge's default pack set. Unknown pack names\nare ignored by the bridge. This setting is currently in beta and its\nbehavior may change.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "webmcp_packs", "enum": [ "webmcp_packs" ] }, "value": { "$ref": "#/components/schemas/zones_webmcp_packs_value" } } } ], "title": "WebMCP Tool Packs" }, "zones_webmcp_packs_value": { "description": "Comma-separated list of WebMCP tool-pack names to activate for this\nzone (for example, \"c2pa,mcp-server-client\"), surfaced to the injected\nbridge as the data-packs attribute. An empty value clears the override\nso the bridge uses its built-in default pack set.", "type": "string", "default": "", "maxLength": 256, "pattern": "^([a-z0-9]+(-[a-z0-9]+)*(,[a-z0-9]+(-[a-z0-9]+)*)*)?$" }, "zones_webp": { "description": "When the client requesting the image supports the WebP image codec, and WebP offers a performance advantage over the original image format, Cloudflare will serve a WebP version of the original image.", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "webp", "enum": [ "webp" ] }, "value": { "$ref": "#/components/schemas/zones_webp_value" } } } ], "title": "Polish WebP Conversion" }, "zones_webp_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "off", "on" ] }, "zones_websockets": { "description": "WebSockets are open connections sustained between the client and the origin server. Inside a WebSockets connection, the client and the origin can pass data back and forth without having to reestablish sessions. This makes exchanging data within a WebSockets connection fast. WebSockets are often used for real-time applications such as live chat and gaming. For more information refer to [Can I use Cloudflare with Websockets](https://support.cloudflare.com/hc/en-us/articles/200169466-Can-I-use-Cloudflare-with-WebSockets-).", "allOf": [ { "$ref": "#/components/schemas/zones_base" }, { "properties": { "id": { "description": "ID of the zone setting.", "example": "websockets", "enum": [ "websockets" ] }, "value": { "$ref": "#/components/schemas/zones_websockets_value" } } } ], "title": "WebSockets" }, "zones_websockets_value": { "description": "Value of the zone setting.", "type": "string", "default": "off", "enum": [ "off", "on" ] }, "zones_zone": { "type": "object", "properties": { "account": { "description": "The account the zone belongs to.", "type": "object", "properties": { "id": { "description": "Identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "name": { "description": "The name of the account.", "type": "string", "example": "Example Account Name" } } }, "activated_on": { "description": "The last time proof of ownership was detected and the zone was made\nactive.", "type": "string", "format": "date-time", "example": "2014-01-02T00:01:00.12345Z", "nullable": true, "readOnly": true }, "cname_suffix": { "description": "Allows the customer to use a custom apex.\n*Tenants Only Configuration*.", "type": "string", "example": "cdn.cloudflare.com" }, "created_on": { "description": "When the zone was created.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true }, "development_mode": { "description": "The interval (in seconds) from when development mode expires\n(positive integer) or last expired (negative integer) for the\ndomain. If development mode has never been enabled, this value is 0.", "type": "number", "example": 7200, "readOnly": true }, "id": { "description": "Identifier", "type": "string", "example": "023e105f4ecef8ad9ca31a8372d0c353", "maxLength": 32, "x-auditable": true }, "meta": { "description": "Metadata about the zone.", "type": "object", "properties": { "cdn_only": { "description": "The zone is only configured for CDN.", "type": "boolean", "example": true }, "custom_certificate_quota": { "description": "Number of Custom Certificates the zone can have.", "type": "integer", "example": 1 }, "dns_only": { "description": "The zone is only configured for DNS.", "type": "boolean", "example": true }, "foundation_dns": { "description": "The zone is setup with Foundation DNS.", "type": "boolean", "example": true }, "page_rule_quota": { "description": "Number of Page Rules a zone can have.", "type": "integer", "example": 100 }, "phishing_detected": { "description": "The zone has been flagged for phishing.", "type": "boolean", "example": false }, "step": { "type": "integer", "example": 2 } } }, "modified_on": { "description": "When the zone was last modified.", "type": "string", "format": "date-time", "example": "2014-01-01T05:20:00.12345Z", "readOnly": true }, "name": { "description": "The domain name. Per [RFC 1035](https://datatracker.ietf.org/doc/html/rfc1035#section-2.3.4) the overall zone name can be up to 253 characters, with each segment (\"label\") not exceeding 63 characters.", "type": "string", "example": "example.com", "maxLength": 253, "pattern": "^([a-zA-Z0-9][\\-a-zA-Z0-9]*\\.)+[\\-a-zA-Z0-9]{2,20}$", "x-auditable": true }, "name_servers": { "description": "The name servers Cloudflare assigns to a zone.", "type": "array", "items": { "format": "hostname", "type": "string" }, "example": [ "bob.ns.cloudflare.com", "lola.ns.cloudflare.com" ], "readOnly": true }, "original_dnshost": { "description": "DNS host at the time of switching to Cloudflare.", "type": "string", "example": "NameCheap", "maxLength": 50, "nullable": true, "readOnly": true }, "original_name_servers": { "description": "Original name servers before moving to Cloudflare.", "type": "array", "items": { "format": "hostname", "type": "string" }, "example": [ "ns1.originaldnshost.com", "ns2.originaldnshost.com" ], "nullable": true, "readOnly": true }, "original_registrar": { "description": "Registrar for the domain at the time of switching to Cloudflare.", "type": "string", "example": "GoDaddy", "nullable": true, "readOnly": true }, "owner": { "description": "The owner of the zone.", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/zones_identifier" }, "name": { "description": "Name of the owner.", "type": "string", "example": "Example Org" }, "type": { "description": "The type of owner.", "type": "string", "example": "organization" } } }, "paused": { "$ref": "#/components/schemas/zones_paused" }, "permissions": { "description": "Legacy permissions based on legacy user membership information.", "type": "array", "items": { "example": "#worker:read", "type": "string" }, "deprecated": true, "x-stainless-deprecation-message": "This has been replaced by Account memberships." }, "plan": { "description": "A Zones subscription information.", "deprecated": true, "properties": { "can_subscribe": { "description": "States if the subscription can be activated.", "type": "boolean", "example": false }, "currency": { "description": "The denomination of the customer.", "type": "string", "example": "USD" }, "externally_managed": { "description": "If this Zone is managed by another company.", "type": "boolean", "example": false }, "frequency": { "description": "How often the customer is billed.", "type": "string", "example": "monthly" }, "id": { "$ref": "#/components/schemas/zones_identifier" }, "is_subscribed": { "description": "States if the subscription active.", "type": "boolean", "example": false }, "legacy_discount": { "description": "If the legacy discount applies to this Zone.", "type": "boolean", "example": false }, "legacy_id": { "description": "The legacy name of the plan.", "type": "string", "example": "free" }, "name": { "description": "Name of the owner.", "type": "string", "example": "Example Org" }, "price": { "description": "How much the customer is paying.", "type": "number", "example": 10.99 } }, "x-stainless-deprecation-message": "Please use the `/zones/{zone_id}/subscription` API\nto update a zone's plan. Changing this value will create/cancel\nassociated subscriptions. To view available plans for this zone,\nsee [Zone Plans](https://developers.cloudflare.com/api/resources/zones/subresources/plans/)." }, "status": { "description": "The zone status on Cloudflare.", "type": "string", "example": "active", "enum": [ "initializing", "pending", "active", "moved" ], "readOnly": true }, "tenant": { "description": "The root organizational unit that this zone belongs to (such as a tenant or organization).", "properties": { "id": { "$ref": "#/components/schemas/zones_identifier" }, "name": { "description": "The name of the Tenant account.", "type": "string", "example": "Example Account Name" } } }, "tenant_unit": { "description": "The immediate parent organizational unit that this zone belongs to (such as under a tenant or sub-organization).", "properties": { "id": { "$ref": "#/components/schemas/zones_identifier" } } }, "type": { "$ref": "#/components/schemas/zones_type" }, "vanity_name_servers": { "description": "An array of domains used for custom name servers. This is only available for Business and Enterprise plans.", "type": "array", "items": { "format": "hostname", "maxLength": 253, "type": "string" }, "example": [ "ns1.example.com", "ns2.example.com" ], "default": [] }, "verification_key": { "description": "Verification key for partial zone setup.", "type": "string", "example": "284344499-1084221259", "readOnly": true } }, "required": [ "id", "name", "development_mode", "owner", "account", "meta", "name_servers", "original_name_servers", "original_registrar", "original_dnshost", "created_on", "modified_on", "activated_on", "plan" ] }, "zones_zone_settings_response_collection": { "allOf": [ { "$ref": "#/components/schemas/zones_api-response-common-4" }, { "properties": { "result": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/zones_0rtt" }, { "$ref": "#/components/schemas/zones_advanced_ddos" }, { "$ref": "#/components/schemas/zones_cache-rules_aegis" }, { "$ref": "#/components/schemas/zones_always_online" }, { "$ref": "#/components/schemas/zones_always_use_https-2" }, { "$ref": "#/components/schemas/zones_automatic_https_rewrites-2" }, { "$ref": "#/components/schemas/zones_brotli" }, { "$ref": "#/components/schemas/zones_browser_cache_ttl-2" }, { "$ref": "#/components/schemas/zones_browser_check-2" }, { "$ref": "#/components/schemas/zones_cache_level-2" }, { "$ref": "#/components/schemas/zones_challenge_ttl" }, { "$ref": "#/components/schemas/zones_ciphers" }, { "$ref": "#/components/schemas/zones_content_converter" }, { "$ref": "#/components/schemas/zones_cname_flattening" }, { "$ref": "#/components/schemas/zones_development_mode" }, { "$ref": "#/components/schemas/zones_early_hints" }, { "$ref": "#/components/schemas/zones_edge_cache_ttl-2" }, { "$ref": "#/components/schemas/zones_email_obfuscation-2" }, { "$ref": "#/components/schemas/zones_h2_prioritization" }, { "$ref": "#/components/schemas/zones_hotlink_protection" }, { "$ref": "#/components/schemas/zones_http2" }, { "$ref": "#/components/schemas/zones_http3" }, { "$ref": "#/components/schemas/zones_image_resizing" }, { "$ref": "#/components/schemas/zones_ip_geolocation-2" }, { "$ref": "#/components/schemas/zones_ipv6" }, { "$ref": "#/components/schemas/zones_max_upload" }, { "$ref": "#/components/schemas/zones_min_tls_version" }, { "$ref": "#/components/schemas/zones_mirage-2" }, { "$ref": "#/components/schemas/zones_nel" }, { "$ref": "#/components/schemas/zones_opportunistic_encryption-2" }, { "$ref": "#/components/schemas/zones_opportunistic_onion" }, { "$ref": "#/components/schemas/zones_orange_to_orange" }, { "$ref": "#/components/schemas/zones_origin_error_page_pass_thru-2" }, { "$ref": "#/components/schemas/zones_cache-rules_origin_h2_max_streams" }, { "$ref": "#/components/schemas/zones_cache-rules_origin_max_http_version" }, { "$ref": "#/components/schemas/zones_polish-2" }, { "$ref": "#/components/schemas/zones_prefetch_preload" }, { "$ref": "#/components/schemas/zones_pre_render" }, { "$ref": "#/components/schemas/zones_privacy_pass" }, { "$ref": "#/components/schemas/zones_proxy_read_timeout" }, { "$ref": "#/components/schemas/zones_pseudo_ipv4" }, { "$ref": "#/components/schemas/zones_redirects_for_ai_training" }, { "$ref": "#/components/schemas/zones_replace_insecure_js" }, { "$ref": "#/components/schemas/zones_response_buffering-2" }, { "$ref": "#/components/schemas/zones_rocket_loader-2" }, { "$ref": "#/components/schemas/zones_schemas-automatic_platform_optimization" }, { "$ref": "#/components/schemas/zones_search_for_agents" }, { "$ref": "#/components/schemas/zones_security_header" }, { "$ref": "#/components/schemas/zones_security_level-2" }, { "$ref": "#/components/schemas/zones_server_side_exclude" }, { "$ref": "#/components/schemas/zones_sha1_support" }, { "$ref": "#/components/schemas/zones_sort_query_string_for_cache-2" }, { "$ref": "#/components/schemas/zones_ssl-2" }, { "$ref": "#/components/schemas/zones_ssl_recommender" }, { "$ref": "#/components/schemas/zones_tls_1_2_only" }, { "$ref": "#/components/schemas/zones_tls_1_3" }, { "$ref": "#/components/schemas/zones_tls_client_auth" }, { "$ref": "#/components/schemas/zones_transformations" }, { "$ref": "#/components/schemas/zones_transformations_allowed_origins" }, { "$ref": "#/components/schemas/zones_true_client_ip_header-2" }, { "$ref": "#/components/schemas/zones_waf-2" }, { "$ref": "#/components/schemas/zones_webmcp_enabled" }, { "$ref": "#/components/schemas/zones_webmcp_packs" }, { "$ref": "#/components/schemas/zones_webp" }, { "$ref": "#/components/schemas/zones_websockets" } ] } } } } ] }, "zones_zone_settings_single_request": { "oneOf": [ { "properties": { "enabled": { "$ref": "#/components/schemas/zones_ssl_recommender_enabled" } }, "type": "object" }, { "properties": { "value": { "$ref": "#/components/schemas/zones_setting_value" } }, "type": "object" } ] } }, "examples": { "cache-rules_cache_reserve_clear_completed": { "value": { "errors": [], "messages": [], "result": { "end_ts": "2023-10-02T12:00:00.12345Z", "id": "cache_reserve_clear", "start_ts": "2023-10-02T10:00:00.12345Z", "state": "Completed" }, "success": true } }, "cache-rules_cache_reserve_clear_in_progress": { "value": { "errors": [], "messages": [], "result": { "id": "cache_reserve_clear", "start_ts": "2023-10-02T10:00:00.12345Z", "state": "In-progress" }, "success": true } }, "cache-rules_cache_reserve_clear_not_found": { "value": { "errors": [ { "code": 1142, "message": "Unable to retrieve cache_reserve_clear setting value. The zone setting does not exist because you never performed a Cache Reserve Clear operation." } ], "messages": [], "result": null, "success": false } }, "cache-rules_cache_reserve_clear_rejected_cr_on": { "value": { "errors": [ { "code": 1152, "message": "Turn off Cache Reserve sync to proceed with deletion." } ], "messages": [], "result": null, "success": false } }, "cache-rules_cache_reserve_denied_clearing": { "value": { "errors": [ { "code": 1153, "message": "Cache Reserve cannot be enabled because a deletion is already in progress." } ], "messages": [], "result": null, "success": false } }, "cache-rules_cache_reserve_off": { "value": { "errors": [], "messages": [], "result": { "editable": true, "id": "cache_reserve", "value": "off" }, "success": true } }, "cache-rules_cache_reserve_on": { "value": { "errors": [], "messages": [], "result": { "editable": true, "id": "cache_reserve", "value": "on" }, "success": true } }, "cache-rules_dummy_error_response": { "value": { "errors": [ { "code": 12345, "message": "Some error message" } ], "messages": [], "result": null, "success": false } }, "cache-rules_origin_cloud_region_already_exists": { "value": { "errors": [ { "code": 1145, "message": "Unable to create new origin_public_cloud_region setting. The zone setting already exists." } ], "messages": [], "result": null, "success": false } }, "cache-rules_origin_cloud_region_batch_delete_internal_error": { "value": { "errors": [ { "code": 1141, "message": "Unable to delete origin_public_cloud_region setting. Internal error." } ], "messages": [], "result": null, "success": false } }, "cache-rules_origin_cloud_region_batch_delete_request": { "value": [ "192.0.2.1", "2001:db8::1" ] }, "cache-rules_origin_cloud_region_batch_delete_response": { "value": { "errors": [], "messages": [], "result": { "editable": true, "id": "origin_public_cloud_region", "modified_on": "2026-03-01T12:00:00Z", "value": { "failed": [], "succeeded": [ { "origin-ip": "192.0.2.1", "region": "us-east-1", "vendor": "aws" }, { "origin-ip": "2001:db8::1", "region": "us-central1", "vendor": "gcp" } ] } }, "success": true } }, "cache-rules_origin_cloud_region_batch_patch_internal_error": { "value": { "errors": [ { "code": 1140, "message": "Unable to update origin_public_cloud_region setting value. Internal error." } ], "messages": [], "result": null, "success": false } }, "cache-rules_origin_cloud_region_batch_patch_request": { "value": [ { "ip": "192.0.2.1", "region": "us-east-1", "vendor": "aws" }, { "ip": "2001:db8::1", "region": "us-central1", "vendor": "gcp" } ] }, "cache-rules_origin_cloud_region_batch_patch_response": { "value": { "errors": [], "messages": [], "result": { "editable": true, "id": "origin_public_cloud_region", "modified_on": "2026-03-01T12:00:00Z", "value": { "failed": [], "succeeded": [ { "origin-ip": "192.0.2.1", "region": "us-east-1", "vendor": "aws" }, { "origin-ip": "2001:db8::1", "region": "us-central1", "vendor": "gcp" } ] } }, "success": true } }, "cache-rules_origin_cloud_region_invalid_ip": { "value": { "errors": [ { "code": 1146, "message": "Invalid or missing origin IP address." } ], "messages": [], "result": null, "success": false } }, "cache-rules_origin_cloud_region_invalid_vendor_region": { "value": { "errors": [ { "code": 1157, "message": "The vendor provided doesn't exist or the region provided does not exist for the specified cloud vendor" } ], "messages": [], "result": null, "success": false } }, "cache-rules_origin_cloud_region_not_found": { "value": { "errors": [ { "code": 1142, "message": "Unable to retrieve origin_public_cloud_region setting value. The zone setting does not exist." } ], "messages": [], "result": null, "success": false } }, "cache-rules_origin_cloud_region_region_validation_error": { "value": { "errors": [ { "code": 1156, "message": "Failed to validate region against cloud vendor" } ], "messages": [], "result": null, "success": false } }, "cache-rules_origin_cloud_region_request_aws": { "value": { "ip": "192.0.2.1", "region": "us-east-1", "vendor": "aws" } }, "cache-rules_origin_cloud_region_request_gcp": { "value": { "ip": "2001:db8::1", "region": "us-central1", "vendor": "gcp" } }, "cache-rules_origin_cloud_region_single": { "value": { "errors": [], "messages": [], "result": { "editable": true, "id": "origin_public_cloud_region", "modified_on": "2026-03-01T12:00:00Z", "value": { "modified_on": "2026-03-01T12:00:00Z", "origin-ip": "192.0.2.1", "region": "us-east-1", "vendor": "aws" } }, "success": true } }, "cache-rules_origin_cloud_region_too_many_mappings": { "value": { "errors": [ { "code": 1164, "message": "Maximum number of IP mappings configured for zone." } ], "messages": [], "result": null, "success": false } }, "cache-rules_origin_cloud_region_v2_batch_delete_request": { "value": [ "192.0.2.1", "2001:db8::1" ] }, "cache-rules_origin_cloud_region_v2_batch_delete_response": { "value": { "errors": [], "messages": [], "result": { "failed": [], "succeeded": [ { "origin_ip": "192.0.2.1", "region": "us-east-1", "vendor": "aws" }, { "origin_ip": "2001:db8::1", "region": "us-central1", "vendor": "gcp" } ] }, "success": true } }, "cache-rules_origin_cloud_region_v2_batch_put_request": { "value": [ { "origin_ip": "192.0.2.1", "region": "us-east-1", "vendor": "aws" }, { "origin_ip": "2001:db8::1", "region": "us-central1", "vendor": "gcp" } ] }, "cache-rules_origin_cloud_region_v2_batch_put_response": { "value": { "errors": [], "messages": [], "result": { "failed": [], "succeeded": [ { "origin_ip": "192.0.2.1", "region": "us-east-1", "vendor": "aws" }, { "origin_ip": "2001:db8::1", "region": "us-central1", "vendor": "gcp" } ] }, "success": true } }, "cache-rules_origin_cloud_region_v2_delete": { "value": { "errors": [], "messages": [], "result": { "origin_ip": "192.0.2.1" }, "success": true } }, "cache-rules_origin_cloud_region_v2_invalid_pagination": { "value": { "errors": [ { "code": 1146, "message": "invalid per_page parameter, must be between 1 and 100" } ], "messages": [], "result": null, "success": false } }, "cache-rules_origin_cloud_region_v2_invalid_vendor_region": { "value": { "errors": [ { "code": 1157, "message": "The vendor provided doesn't exist or the region provided does not exist for the specified cloud vendor" } ], "messages": [], "result": null, "success": false } }, "cache-rules_origin_cloud_region_v2_ip_mismatch": { "value": { "errors": [ { "code": 1146, "message": "body origin_ip does not match URL" } ], "messages": [], "result": null, "success": false } }, "cache-rules_origin_cloud_region_v2_list": { "value": { "errors": [], "messages": [], "result": [ { "modified_on": "2026-03-01T12:00:00Z", "origin_ip": "192.0.2.1", "region": "us-east-1", "vendor": "aws" }, { "modified_on": "2026-03-01T12:30:00Z", "origin_ip": "2001:db8::1", "region": "us-central1", "vendor": "gcp" } ], "result_info": { "count": 2, "page": 1, "per_page": 20, "total_count": 2, "total_pages": 1 }, "success": true } }, "cache-rules_origin_cloud_region_v2_list_empty": { "value": { "errors": [], "messages": [], "result": [], "result_info": { "count": 0, "page": 1, "per_page": 20, "total_count": 0, "total_pages": 0 }, "success": true } }, "cache-rules_origin_cloud_region_v2_not_found": { "value": { "errors": [ { "code": 1142, "message": "Unable to retrieve origin_public_cloud_region setting value. The zone setting does not exist." } ], "messages": [], "result": null, "success": false } }, "cache-rules_origin_cloud_region_v2_request_aws": { "value": { "origin_ip": "192.0.2.1", "region": "us-east-1", "vendor": "aws" } }, "cache-rules_origin_cloud_region_v2_single": { "value": { "errors": [], "messages": [], "result": { "modified_on": "2026-03-01T12:00:00Z", "origin_ip": "192.0.2.1", "region": "us-east-1", "vendor": "aws" }, "success": true } }, "cache-rules_origin_cloud_region_v2_too_many_mappings": { "value": { "errors": [ { "code": 1164, "message": "Maximum number of IP mappings configured for zone." } ], "messages": [], "result": null, "success": false } }, "cache-rules_origin_cloud_regions_empty": { "value": { "errors": [], "messages": [], "result": { "editable": true, "id": "origin_public_cloud_region", "modified_on": null, "value": [] }, "success": true } }, "cache-rules_origin_cloud_regions_list": { "value": { "errors": [], "messages": [], "result": { "editable": true, "id": "origin_public_cloud_region", "modified_on": "2026-03-01T12:00:00Z", "value": [ { "modified_on": "2026-03-01T12:00:00Z", "origin-ip": "192.0.2.1", "region": "us-east-1", "vendor": "aws" }, { "modified_on": "2026-03-01T12:00:00Z", "origin-ip": "2001:db8::1", "region": "us-central1", "vendor": "gcp" } ] }, "success": true } }, "cache-rules_origin_h2_max_streams_50": { "value": { "errors": [], "messages": [], "result": { "editable": true, "id": "origin_h2_max_streams", "value": 50 }, "success": true } }, "cache-rules_origin_max_http_version_2": { "value": { "errors": [], "messages": [], "result": { "editable": true, "id": "origin_max_http_version", "value": "2" }, "success": true } }, "cache-rules_supported_cloud_regions": { "value": { "errors": [], "messages": [], "result": { "obtained_codes": true, "vendors": { "aws": [ { "name": "us-east-1", "upper_tier_colos": [ "IAD", "EWR" ] }, { "name": "us-west-2", "upper_tier_colos": [ "SEA" ] } ], "gcp": [ { "name": "us-central1", "upper_tier_colos": [ "ORD" ] } ] } }, "success": true } }, "cache_auto_origin_tls_kex_disabled_response": { "value": { "errors": [], "messages": [], "result": { "enabled": false, "id": "auto_origin_tls_kex", "modified_on": "2014-01-01T05:20:00.12345Z" }, "success": true } }, "cache_auto_origin_tls_kex_enabled_response": { "value": { "errors": [], "messages": [], "result": { "enabled": true, "id": "auto_origin_tls_kex", "modified_on": "2014-01-01T05:20:00.12345Z" }, "success": true } }, "cache_auto_origin_tls_kex_error_response": { "value": { "errors": [ { "code": 1009, "message": "Missing field 'enabled' in JSON body" } ], "messages": [], "result": { "enabled": false, "id": "auto_origin_tls_kex", "modified_on": "2014-01-01T05:20:00.12345Z" }, "success": false } }, "cache_dummy_automatic_upgrader_disabled_response": { "value": { "errors": [], "messages": [], "result": { "editable": true, "id": "ssl_automatic_mode", "modified_on": "2014-01-01T05:20:00.12345Z", "value": "custom" }, "success": true } }, "cache_dummy_automatic_upgrader_enabled_response": { "value": { "errors": [], "messages": [], "result": { "editable": true, "id": "ssl_automatic_mode", "modified_on": "2014-01-01T05:20:00.12345Z", "next_scheduled_scan": "2014-02-01T05:20:00.12345Z", "value": "auto" }, "success": true } }, "cache_dummy_error_response": { "value": { "errors": [ { "code": 1008, "message": "Invalid SSL/TLS encryption configuration value, only auto or custom accepted" } ], "messages": [], "result": { "editable": true, "id": "ssl_automatic_mode", "modified_on": "2014-01-01T05:20:00.12345Z", "value": "custom" }, "success": false } }, "realtimekit_DaywiseStatsSuccessResponse": { "summary": "Daywise stats response", "value": { "data": [ { "date": "2022-03-01T00:00:00Z", "recordings_minutes_consumed": 129.14, "sessions_count": 10, "sessions_minutes_consumed": 123.22 }, { "date": "2022-03-02T00:00:00Z", "recordings_minutes_consumed": 338.12, "sessions_count": 16, "sessions_minutes_consumed": 1278.87 } ], "success": true } }, "realtimekit_GetActiveSessionNotFoundResponse": { "summary": "Active Session not found", "value": { "error": { "code": 404, "message": "No active session found for meeting_id 6bf2b8be-04dd-4191-b602-1128921a306b" }, "success": false } }, "realtimekit_GetActiveSessionSuccessResponse": { "summary": "Success response for fetching active session", "value": { "data": { "associated_id": "6bf2b8be-04dd-4191-b602-1128921a306b", "created_at": "2022-01-12T14:21:34.398Z", "ended_at": "null", "id": "813432c7-3c5a-45e2-9acf-eef7061c7584", "live_participants": 1, "max_concurrent_participants": 2, "minutes_consumed": 2.3434, "started_at": "2022-01-12T14:21:34.388Z", "status": "LIVE", "type": "meeting", "updated_at": "2022-01-12T14:26:00.784Z" }, "success": true } }, "realtimekit_OverallStatsSuccessResponse": { "summary": "Overall Stats response", "value": { "data": { "recordings_minutes_consumed": 468.8932, "sessions_count": 26, "sessions_minutes_consumed": 1323.23 }, "success": true } }, "realtimekit_ParticipantListSuccess": { "summary": "success response for session's participants list", "value": { "data": { "paging": { "end_offset": 2, "start_offset": 1, "total_count": 123 }, "participants": [ { "created_at": "2023-02-01T10:51:08.039Z", "custom_participant_id": "83qi0i", "display_name": "Mark", "duration": 5.8097, "id": "005f4e0c-4d08-4d4e-a391-a76be75cd296", "joined_at": "2023-02-01T10:51:08.03Z", "left_at": "2023-02-01T10:56:56.612Z", "preset_name": "webinar_participant", "updated_at": "2023-02-01T10:56:56.618Z", "user_id": "0a08343d-a9dc-45f0-9feb-6a64afcc4f81" }, { "created_at": "2023-02-01T10:50:36.853Z", "custom_participant_id": "3uggr", "display_name": "Henry", "duration": 6.9263, "id": "51fdf95f-d893-471a-922b-7db7adb14453", "joined_at": "2023-02-01T10:50:36.846Z\"", "left_at": "2023-02-01T10:57:32.424Z", "preset_name": "webinar_participant", "updated_at": "2023-02-01T10:57:32.431Z", "user_id": "85e7f0fd-7c16-45e9-9d68-f17ef007c4eb" } ] }, "success": true } }, "realtimekit_ParticipantListWithPeerEventSucces": { "summary": "success response for sessions participants list with peer events", "value": { "data": { "paging": { "end_offset": 2, "start_offset": 1, "total_count": 123 }, "participants": [ { "created_at": "2023-02-01T10:51:08.039Z", "custom_participant_id": "83qi0i", "display_name": "Mark", "duration": 5.8097, "id": "005f4e0c-4d08-4d4e-a391-a76be75cd296", "joined_at": "2023-02-01T10:51:08.03Z", "left_at": "2023-02-01T10:56:56.612Z", "peer_events": [ { "created_at": "2023-02-01T10:51:50.786Z", "event_name": "PEER_JOINING", "id": "94af3bac-f30b-40b9-ab45-4b9e6eff191a", "peer_id": "79d87ca5-7e47-452a-b3c1-b6842ad84bf5", "updated_at": "2023-02-01T10:51:50.792Z" }, { "created_at": "2023-02-01T10:56:50.786Z", "event_name": "PEER_LEAVING", "id": "94af3bac-f30b-40b9-ab45-4b9e6eff191b", "peer_id": "79d87ca5-7e47-452a-b3c1-b6842ad84bf5", "updated_at": "2023-02-01T10:56:50.792Z" } ], "preset_name": "webinar_participant", "updated_at": "2023-02-01T10:56:56.618Z", "user_id": "0a08343d-a9dc-45f0-9feb-6a64afcc4f81" }, { "created_at": "2023-02-01T10:50:36.853Z", "custom_participant_id": "3uggr", "display_name": "Henry", "duration": 6.9263, "id": "51fdf95f-d893-471a-922b-7db7adb14453", "joined_at": "2023-02-01T10:50:36.846Z\"", "left_at": "2023-02-01T10:57:32.424Z", "peer_events": [ { "created_at": "2023-02-01T10:51:50.786Z", "event_name": "PEER_JOINING", "id": "94af3bac-f30b-40b9-ab45-4b9e6eff191a", "peer_id": "51fdf95f-d893-471a-922b-7db7adb14453", "updated_at": "2023-02-01T10:51:50.792Z" }, { "created_at": "2023-02-01T10:56:50.786Z", "event_name": "PEER_LEAVING", "id": "94af3bac-f30b-40b9-ab45-4b9e6eff191b", "peer_id": "51fdf95f-d893-471a-922b-7db7adb14453", "updated_at": "2023-02-01T10:56:50.792Z" } ], "preset_name": "webinar_participant", "updated_at": "2023-02-01T10:57:32.431Z", "user_id": "85e7f0fd-7c16-45e9-9d68-f17ef007c4eb" } ] }, "success": true } }, "realtimekit_ParticipantNotFoundResponse": { "summary": "Participant Not Found", "value": { "error": { "code": 404, "message": "No user found with id 813432c7-3c5a-45e2-9acf-eef7061c7584" }, "success": false } }, "smartshield_cache_reserve_clear_completed": { "value": { "errors": [], "messages": [], "result": { "end_ts": "2023-10-02T12:00:00.12345Z", "id": "cache_reserve_clear", "start_ts": "2023-10-02T10:00:00.12345Z", "state": "Completed" }, "success": true } }, "smartshield_cache_reserve_clear_in_progress": { "value": { "errors": [], "messages": [], "result": { "id": "cache_reserve_clear", "start_ts": "2023-10-02T10:00:00.12345Z", "state": "In-progress" }, "success": true } }, "smartshield_cache_reserve_clear_not_found": { "value": { "errors": [ { "code": 1142, "message": "Unable to retrieve cache_reserve_clear setting value. The zone setting does not exist because you never performed a Cache Reserve Clear operation." } ], "messages": [], "result": null, "success": false } }, "smartshield_cache_reserve_clear_rejected_cr_on": { "value": { "errors": [ { "code": 1152, "message": "Turn off Cache Reserve sync to proceed with deletion." } ], "messages": [], "result": null, "success": false } }, "smartshield_smart_shield_4xx_get_response": { "value": { "errors": [ { "code": 1034, "message": "Upgrade Smart Shield to unlock smart_tiered_cache." }, { "code": 1034, "message": "Upgrade Smart Shield to unlock argo_smart_routing." }, { "code": 1034, "message": "Upgrade Smart Shield to unlock regional_tiered_cache." }, { "code": 1034, "message": "Upgrade Smart Shield to unlock cache_reserve." }, { "code": 1034, "message": "Upgrade Smart Shield to unlock healthchecks_count." } ], "messages": [], "result": null, "success": false } }, "smartshield_smart_shield_4xx_patch_response": { "value": { "errors": [ { "code": 1035, "message": "Invalid value for smart_tiered_cache. Value must be 'on' or 'off'." } ], "messages": [], "result": null, "success": false } }, "smartshield_smart_shield_500_response": { "value": { "errors": [ { "code": 1137, "message": "Unable to process request. Internal error." } ], "messages": [], "result": null, "success": false } }, "smartshield_smart_shield_502_get_response": { "value": { "errors": [ { "code": 1016, "message": "Unable to retrieve smart_tiered_cache." }, { "code": 1016, "message": "Unable to retrieve cache_reserve." }, { "code": 1016, "message": "Unable to retrieve smart_routing." }, { "code": 1016, "message": "Unable to retrieve regional_tiered_cache." }, { "code": 1016, "message": "Unable to retrieve healthchecks_count." } ], "messages": [], "result": null, "success": false } }, "smartshield_smart_shield_502_patch_response": { "value": { "errors": [ { "code": 1016, "message": "Unable to update smart_tiered_cache." } ], "messages": [], "result": null, "success": false } } }, "requestBodies": { "api-shield_bulk-create-rules": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_create-single-rule-request" } } } }, "required": true }, "api-shield_bulk-edit-rules": { "content": { "application/json": { "schema": { "type": "array", "items": { "allOf": [ { "properties": { "id": { "description": "Rule ID this patch applies to", "type": "string", "format": "uuid", "example": "0d9bf70c-92e1-4bb3-9411-34a3bcc59003", "maxLength": 36, "x-auditable": true } }, "required": [ "id" ], "type": "object" }, { "$ref": "#/components/schemas/api-shield_edit-single-rule-request" } ] } } } }, "required": true }, "api-shield_config-update": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_configuration" } } }, "required": true }, "api-shield_create-config": { "content": { "application/json": { "schema": { "type": "object", "properties": { "credentials": { "$ref": "#/components/schemas/api-shield_credentials-request" }, "description": { "$ref": "#/components/schemas/api-shield_description" }, "title": { "$ref": "#/components/schemas/api-shield_title" }, "token_sources": { "$ref": "#/components/schemas/api-shield_token_sources" }, "token_type": { "$ref": "#/components/schemas/api-shield_token_type" } }, "required": [ "title", "description", "token_sources", "token_type", "credentials" ] } } }, "required": true }, "api-shield_create-rule": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_create-single-rule-request" } } }, "required": true }, "api-shield_edit-config": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/api-shield_description" }, "title": { "$ref": "#/components/schemas/api-shield_title" }, "token_sources": { "$ref": "#/components/schemas/api-shield_token_sources" } } } } }, "required": true }, "api-shield_edit-config-credentials": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_credentials-patch-request" } } }, "required": true }, "api-shield_edit-rule": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_edit-single-rule-request" } } }, "required": true }, "api-shield_global_settings_edit": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_global_setting_change_base" } } }, "required": true }, "api-shield_global_settings_update": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_global_setting_change_base" }, { "required": [ "validation_default_mitigation_action" ], "type": "object" } ] } } }, "required": true }, "api-shield_per_operation_setting_update": { "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_per_operation_setting_change_base" }, { "required": [ "mitigation_action" ], "type": "object" } ] } } }, "required": true }, "api-shield_per_operation_settings_bulk_edit": { "content": { "application/json": { "schema": { "type": "object", "example": { "3818d821-5901-4147-a474-f5f5aec1d54e": { "mitigation_action": "log" }, "b17c8043-99a0-4202-b7d9-8f7cdbee02cd": { "mitigation_action": "block" } }, "additionalProperties": { "description": "Operation ID to mitigation action mappings", "properties": { "mitigation_action": { "description": "Mitigation actions are as follows:\n* `log` - log request when request does not conform to schema * `block` - deny access to the site when request does not conform to schema * `none` - skip running schema validation * null - clears any existing per-operation setting\n", "type": "string", "example": "block", "enum": [ "none", "log", "block", null ], "nullable": true } }, "type": "object" } } } }, "required": true }, "api-shield_preview-rules": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_selector" } } }, "required": true }, "api-shield_schema_create": { "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "description": "The kind of the schema", "type": "string", "example": "openapi_v3", "enum": [ "openapi_v3" ] }, "name": { "description": "A human-readable name for the schema", "type": "string", "example": "petstore schema" }, "source": { "description": "The raw schema, e.g., the OpenAPI schema, either as JSON or YAML", "type": "string", "example": "" }, "validation_enabled": { "description": "An indicator if this schema is enabled", "type": "boolean" } }, "required": [ "name", "kind", "source", "validation_enabled" ] } } }, "required": true }, "api-shield_schema_edit": { "content": { "application/json": { "schema": { "type": "object", "properties": { "validation_enabled": { "description": "Flag whether schema is enabled for validation.", "type": "boolean" } } } } }, "required": true }, "api-shield_update-config-credentials": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_credentials-request" } } }, "required": true }, "pay-per-crawl_DaricConfig": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pay-per-crawl_DaricConfig" } } }, "description": "Data for setting flag on zones", "required": true, "x-auditable": true }, "pay-per-crawl_ZonesCanBeEnabledPayload": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pay-per-crawl_ZonesCanBeEnabledPayload" } } }, "description": "Data for setting flag on zones", "required": true, "x-auditable": true }, "pay-per-crawl_ZonesCanBeEnabledQueryPayload": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pay-per-crawl_ZonesCanBeEnabledQueryPayload" } } }, "description": "Zone IDs to check for pay-per-crawl eligibility", "required": true, "x-auditable": true }, "realtimekit_AddParticipantBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_participant_id": { "description": "A unique participant ID. You must specify a unique ID for the participant, for example, UUID, email address, and so on. ", "type": "string" }, "name": { "description": "(Optional) Name of the participant. ", "type": "string", "example": "Mary Sue", "nullable": true }, "picture": { "description": "(Optional) A URL to a picture to be used for the participant. ", "type": "string", "format": "uri", "example": "https://i.imgur.com/test.jpg", "nullable": true }, "preset_name": { "description": "Name of the preset to apply to this participant.", "type": "string", "default": "group_call_host" } }, "required": [ "preset_name", "custom_participant_id" ] } } }, "required": true }, "realtimekit_CreateApp": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] } } }, "required": true }, "realtimekit_CreateMeetingBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_config": { "$ref": "#/components/schemas/realtimekit_AIConfig" }, "live_stream_on_start": { "description": "Specifies if the meeting should start getting livestreamed on start.", "type": "boolean", "default": false, "nullable": true }, "persist_chat": { "description": "If a meeting is set to persist_chat, meeting chat would remain for a week within the meeting space.", "type": "boolean", "default": false }, "record_on_start": { "description": "Specifies if the meeting should start getting recorded as soon as someone joins the meeting.", "type": "boolean", "default": false, "nullable": true }, "recording_config": { "$ref": "#/components/schemas/realtimekit_RecordingConfig" }, "session_keep_alive_time_in_secs": { "description": "Time in seconds, for which a session remains active, after the last participant has left the meeting.", "type": "number", "default": 60, "maximum": 600, "minimum": 60 }, "summarize_on_end": { "description": "Automatically generate summary of meetings using transcripts. Requires Transcriptions to be enabled, and can be retrieved via Webhooks or summary API.", "type": "boolean", "default": false }, "title": { "description": "Title of the meeting", "type": "string", "nullable": true }, "transcribe_on_end": { "description": "Automatically generate transcripts when the meeting ends.", "type": "boolean", "default": false } } } } }, "description": "Create meeting body", "required": true }, "realtimekit_CreatePollBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "anonymous": { "description": "if voters on a poll are anonymous", "type": "boolean" }, "hide_votes": { "description": "if votes on an option are visible before a person votes", "type": "boolean" }, "options": { "description": "Different options for the question", "type": "array", "items": { "type": "string" } }, "question": { "description": "Question of the poll", "type": "string" } }, "required": [ "question", "options" ] } } }, "description": "Request body for creating a new poll", "required": true }, "realtimekit_CreatePresetBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/realtimekit_Preset" } } }, "required": true }, "realtimekit_EditParticipantBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "(Optional) Name of the participant.", "type": "string", "example": "Jane Doe", "nullable": true }, "picture": { "description": "(Optional) A URL to a picture to be used for the participant.", "type": "string", "format": "uri", "nullable": true }, "preset_name": { "description": "(Optional) Name of the preset to apply to this participant.", "type": "string", "nullable": true } } } } }, "required": true }, "realtimekit_KickParticipantsBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_participant_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "participant_ids": { "type": "array", "items": { "format": "uuid", "type": "string" }, "minItems": 1 } }, "anyOf": [ { "required": [ "participant_ids" ] }, { "required": [ "custom_participant_ids" ] } ] } } }, "description": "Request body for kicking participants from an active session. At least one of `participant_ids` or `custom_participant_ids` must contain a value.", "required": true }, "realtimekit_MuteAllParticipantsBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "allow_unmute": { "description": "if false, participants won't be able to unmute themselves after they are muted", "type": "boolean", "default": false } } } } }, "description": "Request body for muting all participants in an active session.", "required": true }, "realtimekit_MuteParticipantsBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_participant_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "participant_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "anyOf": [ { "required": [ "participant_ids" ] }, { "required": [ "custom_participant_ids" ] } ] } } }, "description": "Request body for muting participants in an active session. At least one of `participant_ids` or `custom_participant_ids` must contain a value.", "required": true }, "realtimekit_ReplaceParticipantBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "custom_participant_id": { "description": "Unique participant ID accepted by the replace participant API.", "type": "string" }, "name": { "description": "(Optional) Name of the participant.", "type": "string", "nullable": true }, "picture": { "description": "(Optional) A URL to a picture to be used for the participant.", "type": "string", "format": "uri", "nullable": true }, "preset_name": { "description": "Name of the preset to apply to this participant.", "type": "string" } }, "required": [ "preset_name", "custom_participant_id" ] } } }, "required": true }, "realtimekit_StartRecording": { "content": { "application/json": { "examples": { "Example 1": { "value": { "allow_multiple_recordings": false, "audio_config": { "channel": "stereo", "codec": "AAC", "export_file": true }, "file_name_prefix": "string", "interactive_config": { "type": "ID3" }, "max_seconds": 60, "meeting_id": "97440c6a-140b-40a9-9499-b23fd7a3868a", "realtimekit_bucket_config": { "enabled": true }, "video_config": { "codec": "H264", "export_file": true, "height": 720, "watermark": { "position": "left top", "size": { "height": 1, "width": 1 }, "url": "http://example.com" }, "width": 1280 } } } }, "schema": { "type": "object", "properties": { "allow_multiple_recordings": { "description": "By default, a meeting allows only one recording to run at a time. Enabling the `allow_multiple_recordings` parameter to true allows you to initiate multiple recordings concurrently in the same meeting. This allows you to record separate videos of the same meeting with different configurations, such as portrait mode or landscape mode.", "type": "boolean", "default": false }, "audio_config": { "$ref": "#/components/schemas/realtimekit_AudioConfig" }, "file_name_prefix": { "description": "Update the recording file name.", "type": "string" }, "interactive_config": { "$ref": "#/components/schemas/realtimekit_InteractiveConfig" }, "max_seconds": { "description": "Specifies the maximum duration for recording in seconds, ranging from a minimum of 60 seconds to a maximum of 24 hours.", "type": "integer", "maximum": 86400, "minimum": 60 }, "meeting_id": { "description": "ID of the meeting to record.", "type": "string", "format": "uuid" }, "realtimekit_bucket_config": { "$ref": "#/components/schemas/realtimekit_realtimekitBucketConfig" }, "rtmp_out_config": { "$ref": "#/components/schemas/realtimekit_LivestreamingConfig" }, "storage_config": { "$ref": "#/components/schemas/realtimekit_StorageConfig" }, "url": { "description": "Pass a custom url to record arbitary screen", "type": "string", "format": "uri" }, "video_config": { "$ref": "#/components/schemas/realtimekit_VideoConfig" } }, "required": [ "meeting_id" ] } } }, "required": true }, "realtimekit_StartTrackRecordingBody": { "content": { "application/json": { "examples": { "Basic": { "value": { "meeting_id": "97440c6a-140b-40a9-9499-b23fd7a3868a" } }, "With file name prefix": { "value": { "layers": { "default": { "file_name_prefix": "speaker", "media_kind": "audio" } }, "meeting_id": "97440c6a-140b-40a9-9499-b23fd7a3868a" } } }, "schema": { "type": "object", "properties": { "layers": { "description": "Optional audio layer configuration. If omitted, RealtimeKit records all participant audio using the default file name prefix.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/realtimekit_TrackConfigLayer" } }, "meeting_id": { "description": "ID of the meeting to record.", "type": "string", "format": "uuid" }, "user_ids": { "description": "Optional list of participant user IDs to record. Selective track recording (`user_ids`) is in early beta contact support to use this feature.", "type": "array", "items": { "maxLength": 256, "minLength": 1, "type": "string" }, "maxItems": 100, "minItems": 1 } }, "required": [ "meeting_id" ] } } }, "description": "Starts audio track recording for an active meeting. Use `layers` only when you need to set a file name prefix. Selective track recording (`user_ids`) is in early beta contact support to use this feature.", "required": true }, "realtimekit_UpdateMeetingBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ai_config": { "$ref": "#/components/schemas/realtimekit_AIConfig" }, "live_stream_on_start": { "description": "Specifies if the meeting should start getting livestreamed on start.", "type": "boolean" }, "persist_chat": { "description": "If a meeting is updated to persist_chat, meeting chat would remain for a week within the meeting space.", "type": "boolean" }, "record_on_start": { "description": "Specifies if the meeting should start getting recorded as soon as someone joins the meeting.", "type": "boolean" }, "recording_config": { "$ref": "#/components/schemas/realtimekit_RecordingConfig" }, "session_keep_alive_time_in_secs": { "description": "Time in seconds, for which a session remains active, after the last participant has left the meeting.", "type": "number", "maximum": 600, "minimum": 60 }, "status": { "description": "Whether the meeting is `ACTIVE` or `INACTIVE`. Users will not be able to join an `INACTIVE` meeting.", "type": "string", "example": "INACTIVE", "enum": [ "ACTIVE", "INACTIVE" ] }, "summarize_on_end": { "description": "Automatically generate summary of meetings using transcripts. Requires Transcriptions to be enabled, and can be retrieved via Webhooks or summary API.", "type": "boolean" }, "title": { "description": "Title of the meeting", "type": "string" }, "transcribe_on_end": { "description": "Automatically generate transcripts when the meeting ends.", "type": "boolean" } } } } }, "description": "Update meeting body", "required": true }, "realtimekit_UpdatePresetBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/realtimekit_UpdatePreset" } } }, "required": true }, "rulesets_CreateRuleset": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Ruleset" }, { "properties": { "kind": { "$ref": "#/components/schemas/rulesets_RulesetKind" }, "name": { "type": "string" }, "phase": { "$ref": "#/components/schemas/rulesets_RulesetPhase" }, "rules": { "$ref": "#/components/schemas/rulesets_RequestRules" } }, "required": [ "name", "kind", "phase" ], "type": "object" } ] } } }, "required": true }, "rulesets_ManagedTransforms": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rulesets_ManagedTransformsPatch" } } }, "required": true }, "rulesets_Rule": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/rulesets_RequestRule" }, { "properties": { "position": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/rulesets_RulePosition" }, { "properties": { "before": { "description": "The ID of another rule to place the rule before. An empty value causes the rule to be placed at the top.", "type": "string", "example": "da5e8e506c8e7877fe06cdf4c41add54", "pattern": "^[0-9a-f]{32}$", "title": "Before" } }, "title": "Before Position", "type": "object" } ] }, { "allOf": [ { "$ref": "#/components/schemas/rulesets_RulePosition" }, { "properties": { "after": { "description": "The ID of another rule to place the rule after. An empty value causes the rule to be placed at the bottom.", "type": "string", "example": "5bccdbb2a5142cd25cad8591255bd209", "pattern": "^[0-9a-f]{32}$", "title": "After" } }, "title": "After Position", "type": "object" } ] }, { "allOf": [ { "$ref": "#/components/schemas/rulesets_RulePosition" }, { "properties": { "index": { "description": "An index at which to place the rule, where index 1 is the first rule.", "type": "integer", "example": 1, "minimum": 1, "title": "Index" } }, "title": "Index Position", "type": "object" } ] } ] } }, "type": "object" } ] } } }, "required": true }, "rulesets_UpdateEntrypointRuleset": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Ruleset" }, { "properties": { "rules": { "$ref": "#/components/schemas/rulesets_RequestRules" } }, "type": "object" } ] } } }, "required": true }, "rulesets_UpdateRuleset": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Ruleset" }, { "properties": { "kind": { "$ref": "#/components/schemas/rulesets_RulesetKind" }, "phase": { "$ref": "#/components/schemas/rulesets_RulesetPhase" }, "rules": { "$ref": "#/components/schemas/rulesets_RequestRules" } }, "type": "object" } ] } } }, "required": true }, "rulesets_UrlNormalization": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rulesets_UrlNormalization" } } }, "required": true }, "snippets_Snippet": { "content": { "multipart/form-data": { "schema": { "description": "Define a snippet object.", "type": "object", "properties": { "metadata": { "description": "Provide metadata about the snippet.", "type": "object", "properties": { "main_module": { "$ref": "#/components/schemas/snippets_SnippetMainModule" } }, "required": [ "main_module" ], "title": "Metadata" } }, "additionalProperties": { "$ref": "#/components/schemas/snippets_SnippetFiles" }, "required": [ "metadata", "files" ], "title": "Snippet" } } }, "required": true }, "snippets_SnippetRules": { "content": { "application/json": { "schema": { "description": "Define a snippet rules object.", "type": "object", "properties": { "rules": { "$ref": "#/components/schemas/snippets_SnippetRules" } }, "required": [ "rules" ], "title": "Snippet Rules" } } }, "required": true }, "workers_namespace_upload": { "content": { "application/javascript": { "schema": { "description": "Raw javascript content comprising a Worker. Must be in service worker syntax.", "type": "string", "example": "addEventListener('fetch', (event) => event.respondWith(new Response('OK')))" } }, "multipart/form-data": { "encoding": { "files": { "contentType": "application/javascript+module, text/javascript+module, application/javascript, text/javascript, text/x-python, text/x-python-requirement, application/wasm, text/plain, application/octet-stream, application/source-map" }, "metadata": { "contentType": "application/json" } }, "schema": { "$ref": "#/components/schemas/workers_multipart-script" } }, "text/javascript": { "schema": { "description": "Raw javascript content comprising a Worker. Must be in service worker syntax.", "type": "string", "example": "addEventListener('fetch', (event) => event.respondWith(new Response('OK')))" } } }, "required": true }, "workers_script_upload": { "content": { "application/javascript": { "schema": { "description": "Raw javascript content comprising a Worker. Must be in service worker syntax.", "type": "string", "example": "addEventListener('fetch', (event) => event.respondWith(new Response('OK')))" } }, "multipart/form-data": { "encoding": { "files": { "contentType": "application/javascript+module, text/javascript+module, application/javascript, text/javascript, text/x-python, text/x-python-requirement, application/wasm, text/plain, application/octet-stream, application/source-map" }, "metadata": { "contentType": "application/json" } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_multipart-script" }, { "properties": { "metadata": { "type": "object", "properties": { "annotations": { "description": "Annotations for the version created by this upload.", "type": "object", "properties": { "workers/message": { "description": "Human-readable message about the version. Truncated to 1000 bytes if longer.", "type": "string", "example": "Fixed bug.", "maxLength": 1000 }, "workers/tag": { "description": "User-provided identifier for the version. Maximum 100 bytes.", "type": "string", "example": "v1.0.1", "maxLength": 100 } } } } } }, "type": "object" } ] } }, "text/javascript": { "schema": { "description": "Raw javascript content comprising a Worker. Must be in service worker syntax.", "type": "string", "example": "addEventListener('fetch', (event) => event.respondWith(new Response('OK')))" } } }, "required": true }, "workers_version-post": { "content": { "multipart/form-data": { "encoding": { "files": { "contentType": "application/javascript+module, text/javascript+module, application/javascript, text/javascript, `text/x-python`, text/x-python-requirement, application/wasm, text/plain, application/octet-stream, application/source-map" }, "metadata": { "contentType": "application/json" } }, "schema": { "type": "object", "properties": { "files": { "description": "An array of modules (often JavaScript files) comprising a Worker script. At least one module must be present and referenced in the metadata as `main_module` or `body_part` by filename.
Possible Content-Type(s) are: `application/javascript+module`, `text/javascript+module`, `application/javascript`, `text/javascript`, `text/x-python`, `text/x-python-requirement`, `application/wasm`, `text/plain`, `application/octet-stream`, `application/source-map`.", "type": "array", "items": { "format": "binary", "type": "string" }, "x-stainless-collection-type": "set" }, "metadata": { "description": "JSON-encoded metadata about the uploaded parts and Worker configuration.", "type": "object", "properties": { "annotations": { "type": "object", "properties": { "workers/alias": { "description": "Associated alias for a version.", "type": "string", "example": "staging", "maxLength": 63 }, "workers/commit_sha": { "description": "Full commit SHA associated with the version, detected from the CI environment. Maximum 64 bytes.", "type": "string", "example": "8b6aeb38455e2f92e170deb46313b90166ccc1e5", "maxLength": 64 }, "workers/message": { "description": "Human-readable message about the version. Truncated to 1000 bytes if longer.", "type": "string", "example": "Fixed worker code.", "maxLength": 1000 }, "workers/pull_request_number": { "description": "Number of the pull or merge request associated with the version, detected from the CI environment. Maximum 20 bytes.", "type": "string", "example": "14966", "maxLength": 20 }, "workers/pull_request_title": { "description": "Title of the pull or merge request associated with the version, detected from the CI environment. Maximum 512 bytes.", "type": "string", "example": "Add a cool new feature", "maxLength": 512 }, "workers/pull_request_url": { "description": "URL of the pull or merge request associated with the version, detected from the CI environment. Maximum 512 bytes.", "type": "string", "example": "https://github.com/cloudflare/workers-sdk/pull/14966", "maxLength": 512 }, "workers/repository_url": { "description": "URL of the source repository the version was built from, detected from the CI environment. Maximum 512 bytes.", "type": "string", "example": "https://github.com/cloudflare/workers-sdk", "maxLength": 512 }, "workers/tag": { "description": "User-provided identifier for the version. Maximum 100 bytes.", "type": "string", "example": "any-identifier-from-external-system", "maxLength": 100 } } }, "bindings": { "$ref": "#/components/schemas/workers_bindings" }, "cache_options": { "$ref": "#/components/schemas/workers_cache_options" }, "compatibility_date": { "$ref": "#/components/schemas/workers_compatibility_date" }, "compatibility_flags": { "$ref": "#/components/schemas/workers_compatibility_flags" }, "exports": { "description": "Declarative exports for this version. Worker\nentrypoint entries (`type: worker`) carry cache\nconfiguration for that entrypoint.\n", "allOf": [ { "$ref": "#/components/schemas/workers_exports_config_map" } ], "writeOnly": true }, "keep_bindings": { "description": "List of binding types to keep from previous_upload.", "type": "array", "items": { "type": "string" }, "x-stainless-collection-type": "set" }, "main_module": { "description": "Name of the uploaded file that contains the main module (e.g. the file exporting a `fetch` handler). Indicates a `module syntax` Worker, which is required for Version Upload.", "type": "string", "example": "worker.js" }, "package_dependencies": { "description": "The list of npm packages that were installed and used when this Worker\nversion was built.\n", "type": "array", "items": { "properties": { "installedVersion": { "description": "The exact version that was resolved and installed by the package manager.", "type": "string", "example": "4.17.22" }, "name": { "description": "The npm package name.", "type": "string", "example": "lodash" }, "packageJsonVersion": { "description": "The version constraint as written in package.json.", "type": "string", "example": "^4.17.21" } }, "required": [ "name", "packageJsonVersion", "installedVersion" ], "type": "object" }, "x-auditable": true }, "usage_model": { "$ref": "#/components/schemas/workers_usage_model" } }, "required": [ "main_module" ] } }, "required": [ "metadata" ] } } }, "required": true } }, "responses": { "analytics-engine_BadRequest": { "description": "Bad request. The query parameter or request body is missing or malformed.\n", "content": { "text/plain": { "examples": { "content_type_error": { "summary": "Content type error (POST)", "value": "Content type error" }, "missing_query": { "summary": "Missing query parameter", "value": "Query string error: missing field `query`" } }, "schema": { "type": "string" } } } }, "analytics-engine_Forbidden": { "description": "Forbidden. Authentication failed, the account does not have access to Analytics Engine, or the provided token does not have the required permissions. This service returns 403 for all authentication and authorization failures (missing token, invalid token, audience mismatch, account mismatch, or insufficient entitlements).\n", "content": { "text/plain": { "examples": { "auth_error": { "summary": "Authentication or authorization failure", "value": "Authorization error" } }, "schema": { "type": "string" } } } }, "analytics-engine_GatewayTimeout": { "description": "Gateway Timeout. The query exceeded the 60-second execution timeout. Simplify the query, narrow the time range, or add more restrictive filters to reduce execution time.\n", "content": { "text/plain": { "examples": { "timeout": { "summary": "Query execution timeout", "value": "Gateway Timeout" } }, "schema": { "type": "string" } } } }, "analytics-engine_InternalServerError": { "description": "Internal Server Error. An unexpected error occurred during query execution. This may indicate a transient backend issue. Retrying the request after a brief delay is recommended.\n", "content": { "text/plain": { "examples": { "internal_error": { "summary": "Internal server error", "value": "Sorry, we were unable to evaluate your query. Please try again later." } }, "schema": { "type": "string" } } } }, "analytics-engine_QuerySuccess": { "description": "Query executed successfully. Results are returned as newline-delimited JSON (NDJSON) by default. Each line is a JSON object representing one row of results. If the FORMAT JSON clause is used in the query, the response is a single JSON object with data, meta, and rows fields.\n", "headers": { "X-Query-Id": { "description": "Unique identifier for this query execution.", "schema": { "type": "string", "example": "01HXYZ1234ABCDEF5678" } } }, "content": { "application/json": { "examples": { "json_result": { "summary": "JSON format query results (FORMAT JSON)", "value": { "data": [ { "blob1": "US", "count()": 1523 }, { "blob1": "DE", "count()": 847 } ], "meta": [ { "name": "blob1", "type": "String" }, { "name": "count()", "type": "UInt64" } ], "rows": 2 } } }, "schema": { "$ref": "#/components/schemas/analytics-engine_JsonFormatResponse" } }, "application/x-ndjson": { "examples": { "ndjson_result": { "summary": "NDJSON query results", "value": "{\"blob1\":\"US\",\"count()\":1523}\n{\"blob1\":\"DE\",\"count()\":847}\n{\"blob1\":\"GB\",\"count()\":612}\n" } }, "schema": { "description": "Newline-delimited JSON. Each line is a JSON object representing one row of query results.\n", "type": "string" } } } }, "analytics-engine_ServiceUnavailable": { "description": "Service Unavailable. The query queue wait timeout expired before a processing slot became available. This occurs under heavy load when per-account or global concurrency limits are saturated. Retry the request after a brief delay.\n", "content": { "text/plain": { "examples": { "queue_timeout": { "summary": "Query queue timeout", "value": "Query timed out waiting in queue. The system is under heavy load. Please try again later." } }, "schema": { "type": "string" } } } }, "analytics-engine_TooManyRequests": { "description": "Too Many Requests. The account has exceeded the concurrent query limit, the global query pool is full, or a resource limit was hit (query too slow, too much memory, result too large).\n", "content": { "text/plain": { "examples": { "memory_limit": { "summary": "Memory limit exceeded", "value": "Resource limit: Your query requires too much memory. Try simplifying the query or narrowing the time range." }, "query_timeout": { "summary": "Query execution too slow", "value": "Resource limit: Your query timed out. Try simplifying the query or narrowing the time range." }, "queue_full": { "summary": "Per-account queue full", "value": "Resource limit: Too many queries queued for this account. Please try again later." }, "result_too_large": { "summary": "Result set too large", "value": "Resource limit: Your query result is too large. Try adding a LIMIT clause or narrowing your query." } }, "schema": { "type": "string" } } } }, "analytics-engine_UnprocessableQuery": { "description": "Unprocessable Entity. The SQL query failed validation. Common causes include syntax errors, references to unknown columns, unsupported SQL features (JOINs, non-SELECT statements), type mismatches in expressions, and GROUP BY violations.\n", "content": { "text/plain": { "examples": { "syntax_error": { "summary": "SQL syntax error", "value": "Input was invalid: syntax error at position 15" }, "type_mismatch": { "summary": "Type mismatch in expression", "value": "Input was invalid: cannot combine the String and UInt64 types with the + operator" }, "unknown_column": { "summary": "Unknown column reference", "value": "Input was invalid: cannot select unknown column: nonexistent" }, "unsupported_feature": { "summary": "Unsupported SQL feature", "value": "Input was invalid: JOINs are not supported" } }, "schema": { "type": "string" } } } }, "api-shield_bulk-create-rules-success": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_Rule" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_bulk-edit-rules-success": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_Rule" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_config-get-success": { "description": "Retrieve information about specific configuration properties response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_configuration-single-response" } } } }, "api-shield_config-update-success": { "description": "Set configuration properties response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_configuration-single-response" } } } }, "api-shield_create-config-success": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_TokenConfiguration" } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_create-rule-success": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_Rule" } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_delete-config-success": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/api-shield_uuid-2" } } } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_delete-rule-success": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-single-obj" } } } }, "api-shield_edit-config-success": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "description": { "$ref": "#/components/schemas/api-shield_description" }, "id": { "$ref": "#/components/schemas/api-shield_uuid-2" }, "title": { "$ref": "#/components/schemas/api-shield_title" }, "token_sources": { "$ref": "#/components/schemas/api-shield_token_sources" } } } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_edit-rule-success": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_Rule" } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_generic-failure": { "description": "Retrieve information about specific configuration properties response failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } }, "api-shield_generic_failure": { "description": "Failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_api-response-common-failure" } } } }, "api-shield_get-config-success": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_TokenConfiguration" } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_get-rule-success": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_Rule" } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_global_settings_edit_success": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_global_settings" } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_global_settings_get_success": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_global_settings" } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_global_settings_update_success": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-single" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_global_settings" } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_list-configs-success": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_TokenConfiguration" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_list-rules-success": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_Rule" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_per_operation_setting_get_success": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_per_operation_setting" } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_per_operation_setting_update_success": { "description": "Successfully updated", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_per_operation_setting" } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_per_operation_settings_bulk_edit_success": { "description": "Update multiple operation-level schema validation settings response", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "description": "Operation ID to updated mitigation action mapping", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/api-shield_per_operation_setting_change_base" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_per_operation_settings_delete_success": { "description": "Successfully deleted", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "type": "object", "properties": { "operation_id": { "$ref": "#/components/schemas/api-shield_uuid-2" } } } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_per_operation_settings_list_success": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_per_operation_setting" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_preview-rules-success": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "object", "properties": { "available_hosts": { "description": "All hostnames on zone used by operations", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_host" }, "uniqueItems": true }, "excluded": { "description": "Number of operations with `excluded` `state`", "type": "integer", "example": 40, "x-auditable": true }, "ignored": { "description": "Number of operations with `ignored` `state`", "type": "integer", "example": 10, "x-auditable": true }, "included": { "description": "Number of operations with `included` `state`", "type": "integer", "example": 50, "x-auditable": true }, "operations": { "type": "array", "items": { "properties": { "endpoint": { "$ref": "#/components/schemas/api-shield_endpoint" }, "host": { "$ref": "#/components/schemas/api-shield_host" }, "last_updated": { "$ref": "#/components/schemas/api-shield_timestamp-2" }, "method": { "$ref": "#/components/schemas/api-shield_method" }, "operation_id": { "$ref": "#/components/schemas/api-shield_uuid-2" }, "state": { "$ref": "#/components/schemas/api-shield_selector-operation-state" } }, "type": "object" } }, "selected_hosts": { "description": "Hostnames of `included` operations", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_host" }, "uniqueItems": true }, "total": { "description": "Number of operations on zone", "type": "integer", "example": 100, "x-auditable": true } } } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_schema_create_failure": { "description": "Failed uploaded the schema", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common-failure" }, { "properties": { "errors": { "description": "Describes errors in the schema that prohibited accepting the schema.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_schema_issue_notification" } }, "messages": { "description": "Describes issues in the schema and how they were resolved to accept the schema.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_schema_issue_notification" } } }, "required": [ "errors" ], "type": "object" } ] } } } }, "api-shield_schema_create_success": { "description": "Successfully uploaded the schema", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_public_schema_success_result" }, { "properties": { "errors": { "description": "Describes errors in the schema that prohibited accepting the schema.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_schema_issue_notification" } }, "messages": { "description": "Describes issues in the schema and how they were resolved to accept the schema.", "type": "array", "items": { "$ref": "#/components/schemas/api-shield_schema_issue_notification" } } }, "required": [ "messages" ], "type": "object" } ] } } } }, "api-shield_schema_delete_success": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-single" }, { "properties": { "result": { "description": "Schema deletion returns no result body.", "type": "object", "nullable": true } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_schema_edit_success": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_public_schema_success_result" } } } }, "api-shield_schema_get_success": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/api-shield_public_schema_success_result" } } } }, "api-shield_schema_hosts_get_success": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_schema_hosts" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_schemas_extract_operations_get_success": { "description": "All operations in the schema", "content": { "application/json": { "schema": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/api-shield_operation" }, { "$ref": "#/components/schemas/api-shield_basic_operation" } ] } } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_schemas_list_success": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-collection" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/api-shield_public_schema" } } }, "required": [ "result" ], "type": "object" } ] } } } }, "api-shield_update-config-credentials-success": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/api-shield_api-response-common" }, { "properties": { "result": { "$ref": "#/components/schemas/api-shield_credentials" } }, "required": [ "result" ], "type": "object" } ] } } } }, "art_BadRequest": { "description": "Invalid request body. Common causes: missing required fields, invalid timestamp format (must be RFC3339), or unknown dataset/column/stat names.\n", "content": { "application/json": { "examples": { "invalid_timestamp": { "summary": "Invalid timestamp format", "value": { "errors": [ { "code": 11005, "message": "art.api.parameter.invalid" } ], "messages": [ { "code": 1002, "message": "Parameter 'from' has invalid value '2024-11-05 00:00:00'. Should be of type: 'RFC3339'" } ], "result": null, "success": false } }, "missing_body": { "summary": "Missing or empty request body", "value": { "errors": [ { "code": 11005, "message": "art.api.parameter.invalid" } ], "messages": [ { "code": 1000, "message": "API in beta: expect breaking changes." } ], "result": null, "success": false } } }, "schema": { "$ref": "#/components/schemas/art_ErrorResponse" } } } }, "art_Forbidden": { "description": "Insufficient permissions. The authenticated user does not have access to the requested dataset or account.\n", "content": { "application/json": { "examples": { "no_dataset_access": { "summary": "No permission for dataset", "value": { "errors": [ { "code": 11003, "message": "art.api.resource.insufficient_permissions" } ], "messages": [], "result": null, "success": false } }, "wrong_account": { "summary": "Account tag mismatch", "value": { "errors": [ { "code": 11003, "message": "art.api.resource.insufficient_permissions" } ], "messages": [], "result": null, "success": false } } }, "schema": { "$ref": "#/components/schemas/art_ErrorResponse" } } } }, "art_Unauthorized": { "description": "Authentication required. Provide a valid API token or key.", "content": { "application/json": { "examples": { "no_auth": { "summary": "Missing authentication", "value": { "errors": [ { "code": 11003, "message": "art.api.resource.insufficient_permissions" } ], "messages": [], "result": null, "success": false } } }, "schema": { "$ref": "#/components/schemas/art_ErrorResponse" } } } }, "brand-protection-api_DEFAULT_ERROR": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "brand-protection-api_UNPROCESSABLE_CONTENT": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brand-protection-api_Error" } } } }, "brex_BadRequest": { "description": "Invalid request body or account ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_ErrorResponse" } } } }, "brex_Conflict": { "description": "Configuration already exists for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_ErrorResponse" } } } }, "brex_Forbidden": { "description": "The authenticated user is not authorized to access this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_ErrorResponse" } } } }, "brex_InternalServerError": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_ErrorResponse" } } } }, "brex_NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_ErrorResponse" } } } }, "brex_Unauthorized": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/brex_ErrorResponse" } } } }, "builds_BadRequest": { "description": "Invalid request", "content": { "application/json": { "example": { "errors": [ { "code": 12002, "message": "Invalid request body" } ], "messages": [], "result": null, "success": false }, "schema": { "$ref": "#/components/schemas/builds_ErrorResponse" } } } }, "builds_Conflict": { "description": "Conflict - duplicate resource", "content": { "application/json": { "example": { "errors": [ { "code": 12049, "message": "Resource already exists" } ], "messages": [], "result": null, "success": false }, "schema": { "$ref": "#/components/schemas/builds_ErrorResponse" } } } }, "builds_NotFound": { "description": "Resource not found", "content": { "application/json": { "example": { "errors": [ { "code": 12000, "message": "Not found" } ], "messages": [], "result": null, "success": false }, "schema": { "$ref": "#/components/schemas/builds_ErrorResponse" } } } }, "builds_SuccessEmpty": { "description": "Operation successful", "content": { "application/json": { "example": { "errors": [], "messages": [], "result": null, "success": true }, "schema": { "$ref": "#/components/schemas/builds_APIResponse" } } } }, "builds_TooManyRequests": { "description": "Rate limit exceeded", "content": { "application/json": { "example": { "errors": [ { "code": 12051, "message": "Rate limit exceeded" } ], "messages": [], "result": null, "success": false }, "schema": { "$ref": "#/components/schemas/builds_ErrorResponse" } } } }, "builds_Unauthorized": { "description": "Authentication required", "content": { "application/json": { "example": { "errors": [ { "code": 12005, "message": "Missing token from authorization header" } ], "messages": [], "result": null, "success": false }, "schema": { "$ref": "#/components/schemas/builds_ErrorResponse" } } } }, "cloudforce-one-events_ApiV4ClientError": { "description": "Client error response." }, "email-auth_ClientError": { "description": "Client Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email-auth_api-response-common-failure" } } } }, "email-security_ClientError": { "description": "Client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email-security_api-response-common-failure" } } } }, "kamino_client_error": { "description": "Client error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/kamino_error_response" } } } }, "lex_BadRequest": { "description": "Invalid request or unsupported query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_ErrorResponse" } } } }, "lex_BadRequest-2": { "description": "Invalid request, unsupported dataset, or invalid field configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_ErrorResponse-2" } } } }, "lex_Conflict": { "description": "A dataset of this type already exists for this account or zone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_ErrorResponse-2" } } } }, "lex_Forbidden": { "description": "Missing permission to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_ErrorResponse" } } } }, "lex_Forbidden-2": { "description": "The caller lacks permission or entitlement to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_ErrorResponse-2" } } } }, "lex_NotFound": { "description": "Requested resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_ErrorResponse" } } } }, "lex_NotFound-2": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_ErrorResponse-2" } } } }, "lex_ResourcesExhausted": { "description": "Query exceeded internal memory or resource limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lex_ErrorResponse" } } } }, "logpull_BadRequestResponse": { "description": "Error message detailing issue with request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string", "example": "start must be before end" } }, "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "example": false } } } } } }, "logpull_ListKeysOKResponse": { "description": "List of keys matching query.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "properties": { "keys": { "description": "Array of object keys containing logs that match the query.", "type": "array", "items": { "type": "string" }, "example": [ "http_requests/20220501/20220501T000000Z_20220501T000130Z_921f59f6.log.gz", "http_requests/20220501/20220501T000000Z_20220501T000130Z_921f59f6.log.gz" ] } } }, "success": { "type": "boolean" } } } } } }, "logpull_RetrieveLogsOKResponse": { "description": "Newline-delimited JSON logs.", "content": { "application/json": { "example": "{\"ClientIP\":\"1.1.1.1\",\"ClientRequestHost\":\"example.com\",\"ClientRequestMethod\":\"GET\",\"ClientRequestURI\":\"/\",\"EdgeEndTimestamp\":\"2022-05-11T09:59:42Z\",\"EdgeResponseBytes\":363,\"EdgeResponseStatus\":200,\"EdgeStartTimestamp\":\"2022-05-11T09:59:42Z\",\"RayID\":\"709a103c4cefe918\"}\n{\"ClientIP\":\"1.1.1.1\",\"ClientRequestHost\":\"example.com\",\"ClientRequestMethod\":\"GET\",\"ClientRequestURI\":\"/\",\"EdgeEndTimestamp\":\"2022-05-11T10:00:05Z\",\"EdgeResponseBytes\":368,\"EdgeResponseStatus\":200,\"EdgeStartTimestamp\":\"2022-05-11T10:00:05Z\",\"RayID\":\"709a10ccce7240c9\"}\n" } } }, "logpull_UnauthorizedResponse": { "description": "Authentication credentials are missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "number" }, "message": { "type": "string", "example": "Unable to access bucket with the provided credentials." } }, "type": "object" } }, "messages": { "type": "array", "items": { "type": "string" } }, "result": { "type": "object", "nullable": true }, "success": { "type": "boolean", "example": false } } } } } }, "realtimekit_AddParticipant": { "description": "Success response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/realtimekit_GenericSuccessResponse" }, { "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/realtimekit_Participant" }, { "properties": { "token": { "description": "The participant's auth token that can be used for joining a meeting from the client side.", "type": "string", "x-sensitive": true } }, "required": [ "token" ], "type": "object" } ] } }, "type": "object" } ] } } } }, "realtimekit_CreatePoll": { "description": "response for creating a poll", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "action": { "type": "string" }, "poll": { "$ref": "#/components/schemas/realtimekit_Poll" } } }, "success": { "type": "boolean" } } } } } }, "realtimekit_DeleteParticipant": { "description": "Success response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/realtimekit_GenericSuccessResponse" }, { "properties": { "data": { "type": "object", "properties": { "created_at": { "description": "Timestamp this object was created at. The time is returned in ISO format.", "type": "string", "format": "date-time" }, "custom_participant_id": { "description": "A unique participant ID generated by the client.", "type": "string" }, "preset_id": { "description": "ID of the preset applied to this participant.", "type": "string", "format": "uuid" }, "updated_at": { "description": "Timestamp this object was updated at. The time is returned in ISO format.", "type": "string", "format": "date-time" } }, "required": [ "custom_participant_id", "preset_id", "created_at", "updated_at" ] } }, "type": "object" } ] } } } }, "realtimekit_GenericError": { "description": "Failure response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/realtimekit_GenericErrorResponse" } } } }, "realtimekit_GetActiveRecording": { "description": "Success response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/realtimekit_GenericSuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/realtimekit_Recording" } }, "required": [ "data" ], "type": "object" } ] } } } }, "realtimekit_GetActiveSession": { "description": "Active Session Success response", "content": { "application/json": { "examples": { "activeSessionSuccess": { "$ref": "#/components/examples/realtimekit_GetActiveSessionSuccessResponse" } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/realtimekit_ActiveSession" }, "success": { "type": "boolean" } } } } } }, "realtimekit_GetActiveSessionNotFound": { "description": "Active Session is not found for the given meetingId", "content": { "application/json": { "examples": { "activeSessionNotFound": { "$ref": "#/components/examples/realtimekit_GetActiveSessionNotFoundResponse" } }, "schema": { "$ref": "#/components/schemas/realtimekit_GenericErrorResponse" } } } }, "realtimekit_GetAllMeetings": { "description": "Success response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/realtimekit_PagingResponse" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_Meeting" } } }, "type": "object" } ] } } } }, "realtimekit_GetAllParticipants": { "description": "Success response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/realtimekit_PagingResponse" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_Participant" } } }, "type": "object" } ] } } } }, "realtimekit_GetAllPresets": { "description": "Example response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/realtimekit_PagingResponse" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_PresetListItem" } } }, "type": "object" } ] } } } }, "realtimekit_GetDaywiseStats": { "description": "Returns daywise analytics of an App", "content": { "application/json": { "examples": { "DaywiseStatsSuccess": { "$ref": "#/components/examples/realtimekit_DaywiseStatsSuccessResponse" } }, "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_DaywiseStats" } }, "succes": { "type": "boolean" } } } } } }, "realtimekit_GetMeeting": { "description": "Success Response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/realtimekit_GenericSuccessResponse" }, { "allOf": [ { "properties": { "data": { "$ref": "#/components/schemas/realtimekit_Meeting" } }, "type": "object" }, { "properties": { "data": { "type": "object", "properties": { "recording_config": { "$ref": "#/components/schemas/realtimekit_RecordingConfig" } } } }, "type": "object" }, { "properties": { "data": { "type": "object", "properties": { "ai_config": { "$ref": "#/components/schemas/realtimekit_AIConfig" } } } }, "type": "object" } ], "type": "object" } ] } } } }, "realtimekit_GetOverallStats": { "description": "Returns complete analytics of an App", "content": { "application/json": { "examples": { "OverallStatsSuccess": { "$ref": "#/components/examples/realtimekit_OverallStatsSuccessResponse" } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/realtimekit_OverallStats" }, "success": { "type": "boolean" } } } } } }, "realtimekit_GetParticipant": { "description": "Success response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/realtimekit_GenericSuccessResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/realtimekit_Participant" } }, "required": [ "data" ], "type": "object" } ] } } } }, "realtimekit_GetParticipantDataFromPeerId": { "description": "Returns details of a participant using peer ID, including the peer report.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "participant": { "$ref": "#/components/schemas/realtimekit_PeerParticipantDetails" } } }, "success": { "type": "boolean" } } } } } }, "realtimekit_GetParticipantDetails": { "description": "Returns details of a participant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "participant": { "$ref": "#/components/schemas/realtimekit_ParticipantsList" } } }, "success": { "type": "boolean" } } } } } }, "realtimekit_GetPresetBody": { "description": "Success response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/realtimekit_GenericSuccessResponse" }, { "properties": { "data": { "allOf": [ { "properties": { "created_at": { "description": "Timestamp this preset was created at", "type": "string", "format": "date-time" }, "id": { "description": "ID of the preset", "type": "string", "format": "uuid" }, "updated_at": { "description": "Timestamp this preset was last updated", "type": "string", "format": "date-time" } }, "required": [ "id", "created_at", "updated_at" ], "type": "object" }, { "$ref": "#/components/schemas/realtimekit_Preset" } ] } }, "required": [ "data" ], "type": "object" } ] } } } }, "realtimekit_GetRecording": { "description": "Success response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/realtimekit_GenericSuccessResponse" }, { "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/realtimekit_Recording" }, { "properties": { "start_reason": { "$ref": "#/components/schemas/realtimekit_startReason" }, "stop_reason": { "$ref": "#/components/schemas/realtimekit_stopReason" }, "storage_config": { "$ref": "#/components/schemas/realtimekit_StorageConfig" } }, "type": "object" } ] } }, "type": "object" } ] } } } }, "realtimekit_GetRecordings": { "description": "Success response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/realtimekit_PagingResponse" }, { "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/realtimekit_Recording" }, { "properties": { "storage_config": { "$ref": "#/components/schemas/realtimekit_StorageConfig" } }, "type": "object" }, { "properties": { "meeting": { "$ref": "#/components/schemas/realtimekit_Meeting" } }, "type": "object" } ] } } }, "type": "object" } ] } } } }, "realtimekit_GetSessionChat": { "description": "Returns all chat messages of a session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/realtimekit_ChatMessage" }, "success": { "type": "boolean" } } } } } }, "realtimekit_GetSessionDetails": { "description": "Get details about a particular session", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/realtimekit_ActiveSession" }, "success": { "type": "boolean" } } } } } }, "realtimekit_GetSessionParticipants": { "description": "Get participants list of a particular session", "content": { "application/json": { "examples": { "ParticipantListSuccess": { "$ref": "#/components/examples/realtimekit_ParticipantListSuccess" }, "ParticipantListWithPeerStatsSuccess": { "$ref": "#/components/examples/realtimekit_ParticipantListWithPeerEventSucces" } }, "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "participants": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_ParticipantsList" } } } }, "success": { "type": "boolean" } } } } } }, "realtimekit_GetSessionTranscript": { "description": "Returns the complete transcript of a session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/realtimekit_Transcript" }, "success": { "type": "boolean" } } } } } }, "realtimekit_GetSessionTranscriptSummary": { "description": "Returns a complete summary of transcripts of a session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/realtimekit_TranscriptSummary" }, "success": { "type": "boolean" } } } } } }, "realtimekit_GetSessions": { "description": "Get all sessions success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_ActiveSession" } } } }, "paging": { "type": "object", "properties": { "end_offset": { "type": "number" }, "start_offset": { "type": "number" }, "total_count": { "type": "number", "minimum": 0 } } }, "success": { "type": "boolean" } } } } } }, "realtimekit_KickAllParticipants": { "description": "Kick all participants from a meeting", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "action": { "type": "string" }, "kicked_participants_count": { "type": "number" } } }, "success": { "type": "boolean" } } } } } }, "realtimekit_KickParticipants": { "description": "Kick participants success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "action": { "type": "string" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_SessionParticipant" } } } }, "success": { "type": "boolean" } } } } } }, "realtimekit_MuteAllParticipants": { "description": "Mute all participants of a meeting", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "action": { "type": "string" }, "muted_participants_count": { "type": "number" } } }, "success": { "type": "boolean" } } } } } }, "realtimekit_MuteParticipants": { "description": "Mute one or more participants of a meeting", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "action": { "type": "string" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/realtimekit_SessionParticipant" } } } }, "success": { "type": "boolean" } } } } } }, "realtimekit_ParticipantNotFound": { "description": "No participant found for the given `participant_id` or `custom_participant_id`", "content": { "application/json": { "examples": { "participantNotFound": { "$ref": "#/components/examples/realtimekit_ParticipantNotFoundResponse" } }, "schema": { "$ref": "#/components/schemas/realtimekit_GenericErrorResponse" } } } }, "realtimekit_RegenToken": { "description": "Example response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/realtimekit_GenericSuccessResponse" }, { "properties": { "data": { "type": "object", "properties": { "token": { "description": "Regenerated participant's authentication token.", "type": "string", "x-sensitive": true } }, "required": [ "token" ] } }, "required": [ "data" ], "type": "object" } ] } } } }, "rulesets_Empty": { "description": "An empty response." }, "rulesets_Failure": { "description": "A failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Response" }, { "properties": { "result": { "type": "object", "enum": [ null ], "nullable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "type": "object" } ] } } } }, "rulesets_ManagedTransforms": { "description": "A Managed Transforms response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Response" }, { "properties": { "errors": { "type": "array", "items": {}, "enum": [ [] ] }, "result": { "$ref": "#/components/schemas/rulesets_ManagedTransforms" }, "success": { "type": "boolean", "enum": [ true ] } }, "type": "object" } ] } } } }, "rulesets_Ruleset": { "description": "A ruleset response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Response" }, { "properties": { "errors": { "type": "array", "items": {}, "enum": [ [] ] }, "result": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Ruleset" }, { "properties": { "kind": { "$ref": "#/components/schemas/rulesets_RulesetKind" }, "name": { "type": "string" }, "phase": { "$ref": "#/components/schemas/rulesets_RulesetPhase" }, "rules": { "$ref": "#/components/schemas/rulesets_ResponseRules" } }, "required": [ "name", "kind", "phase", "rules" ], "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "type": "object" } ] } } } }, "rulesets_RulesetOrDryRun": { "description": "A ruleset response, or a successful dry-run validation response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Response" }, { "properties": { "errors": { "type": "array", "items": {}, "enum": [ [] ] }, "result": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/rulesets_Ruleset" }, { "properties": { "kind": { "$ref": "#/components/schemas/rulesets_RulesetKind" }, "name": { "type": "string" }, "phase": { "$ref": "#/components/schemas/rulesets_RulesetPhase" }, "rules": { "$ref": "#/components/schemas/rulesets_ResponseRules" } }, "required": [ "name", "kind", "phase", "rules" ], "type": "object" } ] }, { "description": "Returned when dry_run is true.", "enum": [ null ], "nullable": true, "type": "object" } ] }, "success": { "type": "boolean", "enum": [ true ] } }, "type": "object" } ] } } } }, "rulesets_Rulesets": { "description": "A rulesets response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Response" }, { "properties": { "errors": { "type": "array", "items": {}, "enum": [ [] ] }, "result": { "description": "A list of rulesets. The returned information will not include the rules in each ruleset.", "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Ruleset" }, { "properties": { "kind": { "$ref": "#/components/schemas/rulesets_RulesetKind" }, "name": { "type": "string" }, "phase": { "$ref": "#/components/schemas/rulesets_RulesetPhase" } }, "required": [ "name", "kind", "phase" ], "type": "object" } ] }, "title": "Rulesets" }, "result_info": { "$ref": "#/components/schemas/rulesets_ResultInfo" }, "success": { "type": "boolean", "enum": [ true ] } }, "type": "object" } ] } } } }, "rulesets_UrlNormalization": { "description": "A URL Normalization response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/rulesets_Response" }, { "properties": { "errors": { "type": "array", "items": {}, "enum": [ [] ] }, "result": { "$ref": "#/components/schemas/rulesets_UrlNormalization" }, "success": { "type": "boolean", "enum": [ true ] } }, "type": "object" } ] } } } }, "snippets_Failure": { "description": "Return a failure response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/snippets_Response" }, { "properties": { "result": { "type": "object", "enum": [ null ], "nullable": true, "x-auditable": true }, "success": { "type": "boolean", "enum": [ false ] } }, "type": "object" } ] } } } }, "snippets_Null": { "description": "Return a null response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/snippets_Response" }, { "properties": { "errors": { "type": "array", "items": { "type": "object" }, "enum": [ [] ] }, "result": { "type": "object", "enum": [ null ], "nullable": true, "x-auditable": true }, "success": { "type": "boolean", "enum": [ true ] } }, "type": "object" } ] } } } }, "snippets_Snippet": { "description": "Return a snippet response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/snippets_Response" }, { "properties": { "errors": { "type": "array", "items": { "type": "object" }, "enum": [ [] ] }, "result": { "$ref": "#/components/schemas/snippets_Snippet" }, "success": { "type": "boolean", "enum": [ true ] } }, "type": "object" } ] } } } }, "snippets_SnippetContent": { "description": "Return snippet content.", "headers": { "cf-entrypoint": { "schema": { "$ref": "#/components/schemas/snippets_SnippetMainModule" } } }, "content": { "multipart/form-data": { "schema": { "description": "Contain the snippet content response data.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/snippets_SnippetFiles" }, "title": "Snippet Content Response" } } } }, "snippets_SnippetRules": { "description": "A snippet rules response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/snippets_Response" }, { "properties": { "errors": { "type": "array", "items": { "type": "object" }, "enum": [ [] ] }, "result": { "$ref": "#/components/schemas/snippets_SnippetRules" }, "success": { "type": "boolean", "enum": [ true ] } }, "type": "object" } ] } } } }, "snippets_Snippets": { "description": "A snippets response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/snippets_Response" }, { "properties": { "errors": { "type": "array", "items": { "type": "object" }, "enum": [ [] ] }, "result": { "description": "Contain snippets.", "type": "array", "items": { "$ref": "#/components/schemas/snippets_Snippet" }, "title": "Snippets" }, "result_info": { "$ref": "#/components/schemas/snippets_ResultInfo" }, "success": { "type": "boolean", "enum": [ true ] } }, "type": "object" } ] } } } }, "usage-analytics_bad_request": { "description": "Bad request - invalid parameters or query.", "content": { "application/json": { "examples": { "bad_request": { "summary": "Invalid request parameters", "value": { "errors": [ { "code": 10010, "message": "Bad Request" } ], "messages": [], "result": [], "success": false } } }, "schema": { "$ref": "#/components/schemas/usage-analytics_error_response" } } } }, "usage-analytics_forbidden": { "description": "Insufficient permissions to access this resource.", "content": { "application/json": { "examples": { "forbidden": { "summary": "Insufficient permissions", "value": { "errors": [ { "code": 10001, "message": "Forbidden" } ], "messages": [], "result": [], "success": false } } }, "schema": { "$ref": "#/components/schemas/usage-analytics_error_response" } } } }, "usage-analytics_unauthorized": { "description": "Authentication required.", "content": { "application/json": { "examples": { "unauthorized": { "summary": "Missing or invalid authentication", "value": { "errors": [ { "code": 10000, "message": "Authentication required" } ], "messages": [], "result": [], "success": false } } }, "schema": { "$ref": "#/components/schemas/usage-analytics_error_response" } } } }, "vuln_scanner_4XX": { "description": "Client error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/vuln_scanner_api-response-common-failure" } } } }, "workers_200": { "description": "Upload Worker Module response.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_script-response-upload-single" }, { "example": { "errors": [], "messages": [], "result": { "created_on": "2022-05-05T05:15:11.602148Z", "etag": "777f24a43bef5f69174aa69ceaf1dea67968d510a31d1vw3e49d34a0187c06d1", "handlers": [ "fetch" ], "id": "this-is_my_script-01", "logpush": false, "modified_on": "2022-05-20T19:02:56.446492Z", "placement": { "mode": "smart" }, "startup_time_ms": 10, "tail_consumers": [ { "environment": "production", "service": "my-log-consumer" } ], "usage_model": "standard" }, "success": true }, "type": "object" } ] } } } }, "workers_4XX": { "description": "Upload Worker Module response failure. When the upload uses the\ndeclarative `exports` field and one or more entries fail\nreconciliation, the response is the exports reconciliation\nerror envelope (error code 100402) with per-class detail in\n`errors[].meta.details`.\n", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "$ref": "#/components/schemas/workers_exports_reconciliation_error_response" } ] } } } }, "workers_ErrorAuth": { "description": "Authentication required or insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/workers_ErrorAuth" } } }, "required": [ "errors" ], "type": "object" } ] } } } }, "workers_ErrorInternalServer": { "description": "Internal Server Error - An unexpected server error occurred.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/workers_ErrorInternalServer" } } }, "required": [ "errors" ], "type": "object" } ] } } } }, "workers_ErrorWorkerNotFound": { "description": "Not Found - Worker does not exist.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/workers_api-response-common-failure" }, { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/workers_ErrorWorkerNotFound" } } }, "required": [ "errors" ], "type": "object" } ] } } } } }, "securitySchemes": { "api_email": { "in": "header", "name": "X-Auth-Email", "type": "apiKey" }, "api_key": { "in": "header", "name": "X-Auth-Key", "type": "apiKey" }, "api_token": { "scheme": "bearer", "type": "http" }, "user_service_key": { "in": "header", "name": "X-Auth-User-Service-Key", "type": "apiKey" } } }, "externalDocs": { "description": "Cloudflare Radar Documentation", "url": "https://developers.cloudflare.com/radar/" }, "security": [ { "api_email": [], "api_key": [] }, { "api_token": [] }, { "user_service_key": [] } ], "x-forge-commands": { "abuse-reports": { "description": "Submit and track abuse reports for phishing, malware, and other policy violations on Cloudflare-proxied sites", "groups": { "emails": { "description": "Emails operations" }, "mitigations": { "description": "Mitigation actions taken in response to abuse reports" } } }, "accounts": { "description": "Account settings, members, roles, subscriptions, and API tokens for your Cloudflare account", "groups": { "applications": { "description": "Applications operations" }, "categories": { "description": "Categories operations" }, "organizations": { "description": "Move accounts between organizations" }, "profile": { "description": "View and manage the profile for a Cloudflare account" }, "roles": { "description": "View the roles available for assigning to account members, each defining a set of permissions" }, "subscriptions": { "description": "View and manage plan subscriptions attached to this account" }, "tokens": { "description": "Create and manage scoped API tokens for programmatic access to the Cloudflare API" } } }, "ai-gateway": { "description": "Proxy, cache, rate-limit, and observe requests to AI providers — OpenAI, Anthropic, Workers AI, and more", "groups": { "datasets": { "description": "Curated collections of gateway logs used as inputs for evaluations and fine-tuning" }, "dynamic-routing": { "description": "Route requests across multiple AI providers with fallback, load-balancing, and versioned deployments" }, "evaluation-types": { "description": "Available evaluator types for scoring AI gateway responses (accuracy, toxicity, etc.)" }, "evaluations": { "description": "Run quality evaluations against gateway logs or datasets to score model outputs" }, "logging-state": { "description": "Inspect and migrate the logging platform used by an AI Gateway account" }, "logs": { "description": "Inspect individual request/response pairs that passed through the gateway" }, "provider-configs": { "description": "Store API keys and endpoint settings for each upstream AI provider" }, "urls": { "description": "Retrieve the gateway's proxy URL used by clients to send inference requests" } } }, "ai-search": { "description": "Managed search-as-a-service: crawl, index, and query content with AI-powered relevance and chat completions", "groups": { "items": { "description": "Content indexed by AI Search instances" }, "jobs": { "description": "Indexing job lifecycle for AI Search instances" }, "namespace": { "description": "Logical groupings for organizing AI Search instances" }, "tokens": { "description": "Credentials used by AI Search instances" } } }, "ai-security": { "description": "Detect prompt injection, PII, and unsafe topics in traffic to your AI applications", "groups": { "custom-topics": { "description": "Organization-specific topic categories used by AI Security for Apps content detection" } } }, "analytics": { "description": "Zone-level traffic analytics — dashboard summaries, per-colo breakdowns, and Argo latency metrics", "groups": { "colo": { "description": "Per-data-center (colo) traffic analytics breakdown for the zone" }, "dashboard": { "description": "Aggregated zone dashboard analytics — requests, bandwidth, threats, and page views" }, "latency": { "description": "Argo Smart Routing latency analytics showing time-to-first-byte improvements" } } }, "argo": { "description": "Network optimization features that speed up and improve reliability of traffic to your origins", "groups": { "smart-routing": { "description": "Route traffic through the fastest network paths to your origin using real-time latency data" } } }, "billing": { "description": "Account billing profiles and usage data for Cloudflare subscriptions and add-on services", "groups": { "profiles": { "description": "Billing profile with payment method, address, and invoice preferences" }, "usage": { "description": "Metered usage data for billed services — requests, bandwidth, and feature consumption" } } }, "builds": { "description": "Build and deploy Workers from connected repositories, then inspect build status and logs.", "groups": { "deploy-hooks": { "description": "Manage branch-specific HTTP hooks that start builds." }, "limits": { "description": "View build-minute availability and refresh information." }, "logs": { "description": "Retrieve build logs." }, "repos": { "description": "Manage source repository connections for Workers Builds." }, "tokens": { "description": "Manage credentials used by Workers Builds to deploy Workers." }, "triggers": { "description": "Configure how repository changes build and deploy Workers." }, "versions": { "description": "Find builds associated with Worker versions." }, "workers": { "description": "Manage repository-backed build configuration for Workers." } } }, "calls": { "description": "Real-time audio/video communication infrastructure — SFU apps for WebRTC and TURN relay keys", "groups": { "sfu": { "description": "Selective Forwarding Unit apps that route WebRTC media between participants" }, "turn": { "description": "TURN relay keys that help clients traverse NATs and firewalls for peer-to-peer connectivity" } } }, "client-side-security": { "description": "Client-Side Security — monitor JavaScript, connections, and cookies on your pages for supply-chain attacks", "groups": { "connections": { "description": "Third-party connections made by scripts on your pages — track data exfiltration risks" }, "cookies": { "description": "Cookies set by your pages with classification and same-site attribute tracking" }, "policies": { "description": "Content Security Policies that control which scripts and connections are allowed on your pages" }, "scripts": { "description": "JavaScript files detected on your pages with change tracking and malicious code detection" }, "settings": { "description": "Fine tune Client-Side Security behaviors" } } }, "cloud-connector": { "description": "Route traffic from Cloudflare directly to cloud provider services (AWS, Azure, GCP) without origin servers", "groups": { "rules": { "description": "Routing rules that map request patterns to cloud provider endpoints" } } }, "cloudforce-one": { "description": "Detection rule management APIs", "groups": { "binary-storage": { "description": "Upload and retrieve malware samples and suspicious binaries for analysis" }, "requests": { "description": "Additional request operations — priority listing and asset creation" }, "rules": { "description": "Rule management operations", "groups": { "approvals": { "description": "Approval workflow operations" }, "email": { "description": "Email rule operations" }, "exemptions": { "description": "Exemption rule operations" }, "managed": { "description": "Managed rule operations" }, "stats": { "description": "Rule statistics operations" }, "tree": { "description": "Rule navigation tree operations" } } }, "scans": { "description": "Scan URLs, IPs, and domains for threat intelligence indicators" } } }, "containers": { "description": "Deploy and manage Containers applications on Cloudflare's global network", "groups": { "applications": { "description": "Manage Containers applications" }, "applications.instances": { "description": "Inspect Containers instances belonging to applications" }, "applications.rollouts": { "description": "Manage rollouts for scheduler-backed applications" }, "applications.versions": { "description": "Inspect versions of scheduler-backed applications" }, "registries": { "description": "Manage Containers image registries" }, "registries.credentials": { "description": "Generate image registry credentials" } } }, "content-scan": { "description": "Malicious uploads detection, scan uploaded content in HTTP requests for malware and malicious payloads", "groups": { "expressions": { "description": "Custom expressions that tell the scanner how to reach content objects it cannot parse on its own" } } }, "custom-pages": { "description": "Custom error and challenge pages (1000s, WAF blocks, captchas) for zones and accounts", "groups": { "account-custom-pages": { "description": "Account-scoped custom page operations" }, "account-custom-pages.preview-tokens": { "description": "Account preview tokens operations" }, "assets": { "description": "Assets operations" }, "zone-custom-pages": { "description": "Zone-scoped custom page operations" }, "zone-custom-pages.preview-tokens": { "description": "Zone preview tokens operations" } } }, "d1": { "description": "D1 is Cloudflare's managed, serverless database with SQLite's SQL semantics, built-in disaster recovery, and Worker and HTTP API access.", "groups": { "time-travel": { "description": "use specific point-in-time backups of your D1 database", "x-forge-epilogue": "For more information about Time Travel, see https://developers.cloudflare.com/d1/reference/time-travel" } } }, "diagnostics": { "description": "Network diagnostic tools — traceroutes from Cloudflare's edge and endpoint health checks", "groups": { "endpoint-healthchecks": { "description": "Monitor external endpoint availability with periodic HTTP/HTTPS health checks" }, "traceroutes": { "description": "Run traceroutes from Cloudflare data centers to diagnose network path issues" } } }, "email-routing": { "description": "Route incoming emails to destination addresses using custom rules, catch-all handlers, and DNS configuration", "groups": { "addresses": { "description": "Verified destination email addresses that can receive forwarded mail" }, "dns": { "description": "DNS records required for email routing (MX, SPF, DKIM) — enable, lock, or disable" }, "rules": { "description": "Routing rules that match incoming email addresses and forward to destination mailboxes" }, "suppression": { "description": "Email suppression list management for routing and sending" } } }, "email-security": { "description": "Cloud email security — investigate threats, manage allow/block policies, and detect phishing", "groups": { "investigate": { "description": "Search and investigate email messages — view detections, traces, raw content, and take remediation actions" }, "phishguard": { "description": "PhishGuard user-reported phishing submissions and analysis reports" }, "settings": { "description": "Email security policies — allow lists, blocked senders, trusted domains, and impersonation registry" }, "submissions": { "description": "User and admin email submissions for classification review" } } }, "email-sending": { "description": "Send emails and manage sending subdomains", "groups": { "subdomains": { "description": "Sending subdomain operations" } } }, "filters": { "description": "Filter expressions used by legacy firewall rules to match requests — prefer Rulesets for new configurations" }, "firewall": { "description": "Legacy firewall rules, zone lockdowns, access rules, user-agent blocking, and WAF packages", "groups": { "access-rules": { "description": "IP-based access rules that allow, block, challenge, or whitelist traffic globally or per-zone" }, "lockdowns": { "description": "Zone lockdown rules that restrict access to URLs by IP address or range" }, "rules": { "description": "Legacy firewall rules with filter expressions — prefer Rulesets for new configurations" }, "ua-rules": { "description": "Block or challenge requests based on the User-Agent header string" }, "waf": { "description": "Legacy WAF managed rule packages, rule groups, individual rules, and override configurations" }, "zone-access-rules": { "description": "Zone-scoped IP access rules for blocking or allowing traffic" } } }, "google-tag-gateway": { "description": "Google Tag Gateway operations", "groups": { "config": { "description": "Google Tag Gateway config operations" } } }, "healthchecks": { "description": "Standalone health checks that monitor origin server availability from Cloudflare's edge", "groups": { "previews": { "description": "Test a health check configuration before deploying it to production" } } }, "hyperdrive": { "description": "Accelerate access to existing databases by caching queries and pooling connections at the edge" }, "iam": { "description": "Identity and access management — permission groups, resource groups, user groups, and SSO connectors", "groups": { "permission-groups": { "description": "View the permission groups that can be assigned to API tokens and policies" }, "resource-groups": { "description": "Define scopes that limit which account resources a policy or token can access" }, "sso": { "description": "Configure single sign-on connectors to authenticate account members through an external identity provider" }, "user-groups": { "description": "Organize account members into groups for easier permission assignment" } } }, "images": { "description": "Store, resize, and deliver optimized images globally — variants, signing keys, and direct uploads", "groups": { "flows": { "description": "Zone-level transformation flows that control how images are resized and optimized on delivery" }, "keys": { "description": "Manage signing keys for generating private image URLs" }, "variants": { "description": "Manage named resize variants for transforming images on delivery" } } }, "intel": { "description": "Threat intelligence lookups — IP reputation, domain info, ASN details, WHOIS, and indicator feeds", "groups": { "asn": { "description": "ASN intelligence — ownership, geolocation, and subnet details for autonomous systems" }, "attack-surface-report": { "description": "Attack surface intelligence — exposed assets, vulnerabilities, and infrastructure mapping" }, "dns": { "description": "Passive DNS data showing historical DNS resolution records for domains" }, "domain-history": { "description": "Historical domain registration and categorization changes over time" }, "domains": { "description": "Domain intelligence — risk scores, categories, and associated infrastructure" }, "indicator-feeds": { "description": "Threat indicator feeds — subscribe to and manage curated lists of malicious IPs, domains, and URLs" }, "ip-lists": { "description": "Curated IP lists used for threat detection and policy enforcement" }, "ips": { "description": "IP address intelligence — geolocation, risk assessment, and hosting provider details" }, "miscategorizations": { "description": "Report and track domain miscategorization corrections" }, "urls": { "description": "URL intelligence operations" } } }, "leaked-credential-checks": { "description": "Detect compromised credentials in login requests by checking against known breach databases", "groups": { "detections": { "description": "Custom detection locations that tell the WAF where to find usernames and passwords in requests" } } }, "load-balancers": { "description": "Distribute traffic across origin pools with health monitoring, geo-steering, and failover", "groups": { "monitor-groups": { "description": "Group monitors together for shared configuration and bulk management" }, "monitor-groups.references": { "description": "List references to monitor groups used by load balancer pools" }, "monitors": { "description": "Health check configurations that probe origin servers and determine pool availability" }, "monitors.previews": { "description": "Health check configurations that probe origin servers and determine pool availability" }, "monitors.references": { "description": "Health check configurations that probe origin servers and determine pool availability" }, "pools": { "description": "Origin server pools with weighted traffic distribution, health thresholds, and geographic preferences" }, "pools.health": { "description": "Origin server pools with weighted traffic distribution, health thresholds, and geographic preferences" }, "pools.references": { "description": "Origin server pools with weighted traffic distribution, health thresholds, and geographic preferences" }, "previews": { "description": "Preview the result of a health check monitor configuration before applying it" }, "regions": { "description": "Geographic regions used for regional pool steering and traffic policies" }, "searches": { "description": "Search across all load balancer resources (pools, monitors, load balancers) by name or reference" } } }, "logs": { "description": "Log control, retention, and raw log access — CMB config, ray ID lookups, and received fields", "groups": { "control": { "description": "Log control operations" }, "received": { "description": "Received log operations" } } }, "magic-network-monitoring": { "description": "Flow-based network traffic monitoring with configurable alerting rules and VPC flow ingestion", "groups": { "configs": { "description": "Account-level monitoring configuration — sampling rates, thresholds, and notification settings" }, "rules": { "description": "Monitoring rules that define traffic thresholds and trigger alerts or prefix advertisements" }, "vpc-flows": { "description": "Ingest VPC flow logs from cloud providers for network visibility and anomaly detection" } } }, "magic-transit": { "description": "DDoS-protected network transit — GRE/IPsec tunnels, static routes, Magic WAN sites, connectors, and packet captures", "groups": { "advanced-dns-protection": { "description": "Advanced Dns Protection operations" }, "advanced-tcp-protection": { "description": "Advanced Tcp Protection operations" }, "apps": { "description": "Application-aware traffic policies for Magic WAN that steer traffic by app type" }, "bgp-filter-profiles": { "description": "BGP filter profiles for controlling which routes are allowed or denied on Magic Transit tunnels" }, "bgp-settings": { "description": "BGP settings for controlling default ASN and route redistribution on Magic Transit tunnels" }, "cf-interconnects": { "description": "Cloudflare Network Interconnect (CNI) links for direct physical or virtual peering" }, "gre-tunnels": { "description": "GRE tunnel endpoints that connect your network to Cloudflare for Magic Transit" }, "ipsec-tunnels": { "description": "IPsec tunnel endpoints with pre-shared key management for encrypted transit" }, "pcaps": { "description": "Packet capture requests for debugging traffic flowing through Magic Transit tunnels" }, "routes": { "description": "Static routes that direct IP prefix traffic through specific GRE/IPsec tunnels" }, "sites": { "description": "Magic WAN branch sites — base CRUD, LAN/WAN interface configuration, ACLs, connectors, app configuration, and NetFlow config" } } }, "moq": { "description": "MoQ relays: provision a relay, then issue tokens for publishers and subscribers", "groups": { "relays": { "description": "Relays are isolated MoQ scopes that carry media between publishers and subscribers" } } }, "network-interconnects": { "description": "Physical and virtual private interconnects between your infrastructure and Cloudflare's network", "groups": { "cnis": { "description": "Cloud Network Interconnect (CNI) connections — private links from cloud providers to Cloudflare" }, "interconnects": { "description": "Physical cross-connect and partner interconnect sessions with LOA and status tracking" }, "settings": { "description": "Account-level interconnect settings and default configurations" }, "slots": { "description": "Available interconnect facility slots showing port capacity at Cloudflare data centers" } } }, "organizations": { "description": "Multi-user organizations that group accounts, members, and shared settings under a single entity", "groups": { "account-organizations": { "description": "List organizations associated with a specific account" }, "accounts": { "description": "Accounts operations" }, "members": { "description": "Members operations" }, "members-batch-create": { "description": "Members Batch Create operations" }, "organization-profile": { "description": "View and update the public profile information for an organization" }, "shares": { "description": "Shares operations" } } }, "pages": { "description": "Full-stack application hosting with Git-integrated builds, preview deployments, and custom domains", "groups": { "projects": { "description": "Pages projects, deployments, build logs, and custom domain bindings" } } }, "pipelines": { "description": "Ingest, transform, and route event streams into R2, analytics, or other destinations in real time", "groups": { "sinks": { "description": "Destinations where pipeline data is written — R2 buckets, HTTP endpoints, or other storage" }, "streams": { "description": "Inbound data streams that feed events into a pipeline for processing" } } }, "precursor": { "description": "Precursor settings for a zone" }, "queues": { "description": "Reliable message queuing between Workers — produce, consume, and batch-process messages at scale", "groups": { "consumers": { "description": "Workers that automatically receive and process messages from a queue" }, "messages": { "description": "Push messages to a queue and pull or acknowledge them from consumers" }, "purge": { "description": "Remove all pending messages from a queue" }, "subscriptions": { "description": "Manage queue subscriptions for event-driven message routing" } } }, "r2": { "description": "S3-compatible object storage with zero egress fees — buckets, lifecycle rules, event notifications, and data migration", "groups": { "buckets": { "description": "Create and configure R2 buckets including CORS, lifecycle, custom domains, event notifications, and object locks" }, "buckets.jobs": { "description": "Inspect background jobs for an R2 bucket" }, "buckets.local-uploads": { "description": "R2 bucket local upload configuration" }, "super-slurper": { "description": "Migrate data from external S3-compatible storage into R2 buckets with resumable transfer jobs" }, "temporary-credentials": { "description": "Generate short-lived S3-compatible credentials scoped to specific buckets and operations" } } }, "r2-data-catalog": { "description": "Iceberg-compatible data catalog for R2 — organize objects into tables and namespaces for SQL query engines", "groups": { "credentials": { "description": "Catalog access credentials for external query engines (Spark, Trino, etc.)" }, "maintenance-configs": { "description": "Table maintenance settings — compaction schedules and snapshot expiration policies" }, "namespaces": { "description": "Logical namespaces that group related tables within the data catalog" } } }, "radar": { "description": "Internet-wide traffic intelligence — BGP, DNS, HTTP trends, attack data, and network quality insights", "groups": { "agent-readiness": { "description": "Agent readiness summary statistics across the Cloudflare network" }, "ai": { "description": "AI inference trends and model usage statistics across the Cloudflare network" }, "annotations": { "description": "Radar annotations marking significant Internet events (outages, cable cuts, etc.)" }, "as112": { "description": "AS112 DNS sinkhole statistics — reverse DNS query volumes for private address space" }, "attacks": { "description": "DDoS and application-layer attack trends, vectors, and target analysis" }, "bgp": { "description": "BGP routing data — prefix announcements, AS-level stats, route leaks, and hijack events" }, "bots": { "description": "Internet-wide bot traffic trends, categories, and distribution statistics" }, "ct": { "description": "Certificate Transparency log monitoring and newly-issued certificate discovery" }, "datasets": { "description": "Downloadable Radar datasets for offline analysis and research" }, "dns": { "description": "Global DNS query trends — top domains, resolver stats, and DNSSEC adoption" }, "email": { "description": "Email security trends — DMARC/SPF/DKIM adoption, spam, and phishing statistics" }, "entities": { "description": "Look up ASNs, IPs, domains, and locations with metadata and traffic summaries" }, "geolocations": { "description": "Geographic location metadata used for regional traffic analysis" }, "http": { "description": "HTTP protocol trends — TLS versions, HTTP versions, browser share, and OS distribution" }, "leaked-credentials": { "description": "Leaked credential detection trends and exposure statistics" }, "netflows": { "description": "Network-layer traffic flow data and volumetric trend analysis" }, "origins": { "description": "Cloud and hosting origin providers (e.g. Amazon, by region) and their traffic metrics" }, "post-quantum": { "description": "Post-quantum encryption adoption and deployment trends across the Internet" }, "quality": { "description": "Internet connection quality metrics — speed, latency, and jitter by geography and ASN" }, "ranking": { "description": "Top domain rankings based on DNS query popularity across the Cloudflare network" }, "robots-txt": { "description": "Robots.txt adoption and crawler directive trends across the web" }, "search": { "description": "Search Radar data across IPs, ASNs, domains, and locations" }, "tcp-resets-timeouts": { "description": "TCP connection reset and timeout statistics indicating network health issues" }, "tlds": { "description": "Top-level domain (TLD) metadata and performance trends" }, "traffic-anomalies": { "description": "Detected traffic anomalies and unusual patterns in Internet traffic flows" }, "verified-bots": { "description": "Catalog of known good bots (Googlebot, Bingbot, etc.) and their traffic patterns" } } }, "rate-limits": { "description": "Legacy per-zone rate limiting rules — prefer Advanced Rate Limiting in Rulesets for new configurations" }, "realtimekit": { "description": "SDK-backed meetings, participants, recordings, livestreams, and webhooks", "groups": { "analytics": { "description": "Usage and livestream analytics for RealtimeKit applications" }, "analytics.livestreams": { "description": "Livestream analytics for RealtimeKit applications" }, "analytics.livestreams.daily": { "description": "Daily livestream analytics for RealtimeKit applications" }, "analytics.usage": { "description": "Usage analytics for RealtimeKit applications" }, "apps": { "description": "RealtimeKit applications that group meetings, sessions, and configuration" }, "livestreams": { "description": "Independent and meeting-based livestreams and their sessions" }, "livestreams.sessions": { "description": "Sessions for RealtimeKit livestreams" }, "meetings": { "description": "Meetings, participants, access tokens, and meeting livestreams" }, "meetings.active": { "description": "Live meeting state and participant controls" }, "meetings.active.polls": { "description": "Polls for active meeting sessions" }, "meetings.livestream": { "description": "Livestream operations associated with RealtimeKit meetings" }, "meetings.participants": { "description": "Participants in RealtimeKit meetings" }, "meetings.participants.tokens": { "description": "Access tokens for RealtimeKit meeting participants" }, "presets": { "description": "Reusable meeting configuration for media, permissions, and interface behavior" }, "recordings": { "description": "Meeting and participant-track recordings and recording controls" }, "recordings.active": { "description": "Active recordings for RealtimeKit meetings" }, "recordings.tracks": { "description": "Participant-track recordings for RealtimeKit meetings" }, "sessions": { "description": "Historical session data, participants, chat, transcripts, and summaries" }, "sessions.chat": { "description": "Chat messages from historical RealtimeKit sessions" }, "sessions.livestreams": { "description": "Livestreams associated with historical RealtimeKit sessions" }, "sessions.participants": { "description": "Participants in historical RealtimeKit sessions" }, "sessions.peers": { "description": "Peer details from historical RealtimeKit sessions" }, "sessions.summaries": { "description": "Summaries of historical RealtimeKit sessions" }, "sessions.transcripts": { "description": "Transcripts from historical RealtimeKit sessions" }, "webhooks": { "description": "Webhook endpoints and supported events for RealtimeKit notifications" }, "webhooks.events": { "description": "Supported events for RealtimeKit webhooks" } } }, "request-tracers": { "description": "Trace how a request would be processed through Cloudflare's rules and configuration pipeline", "groups": { "traces": { "description": "Simulate request processing to debug rule matches, transforms, and routing decisions" } } }, "resource-sharing": { "description": "Share Cloudflare resources (zones, accounts) across organizations with granular access controls", "groups": { "recipients": { "description": "Update share recipients" }, "resources": { "description": "Individual resources (zones, configs) that have been shared with recipients" } } }, "rules": { "description": "Account-level IP lists, hostname lists, and other reusable lists referenced by firewall rules and rulesets", "groups": { "lists": { "description": "Named lists of IPs, hostnames, ASNs, or redirects that can be referenced in rule expressions" } } }, "rum": { "description": "Real User Measurement (Web Analytics) — track page loads, Core Web Vitals, and visitor metrics", "groups": { "rules": { "description": "Rules that control which pages and paths are tracked by Web Analytics" }, "site-info": { "description": "Web Analytics sites — register domains and get the JavaScript beacon snippet" } } }, "scim": { "description": "SCIM 2.0 provisioning — manage users, groups, and identity provider sync for your account", "groups": { "groups": { "description": "Groups operations" }, "resource-types": { "description": "Resource Types operations" }, "schemas": { "description": "Schemas operations" }, "service-provider-config": { "description": "Service Provider Config operations" }, "users": { "description": "Users operations" } } }, "secrets-store": { "description": "Centralized secret management — store API keys, tokens, and credentials for use across Workers and other products", "groups": { "quota": { "description": "Account quota limits for secrets stores, secrets count, and storage capacity" }, "secrets": { "description": "Encrypted key-value secrets within a store. Pass --store-id to scope." }, "stores": { "description": "Secret stores that hold encrypted key-value secrets accessible by Workers and services" } } }, "security-center": { "description": "Security posture dashboard — view and manage security insights, misconfigurations, and vulnerabilities", "groups": { "insights": { "description": "Security findings and recommendations across your account — DNS, SSL, WAF misconfigurations, etc." }, "zone-insights": { "description": "Zone-scoped security insights — counts by class, severity, type, and dismissal" } } }, "security-txt": { "description": "Manage the /.well-known/security.txt file that tells security researchers how to report vulnerabilities" }, "spectrum": { "description": "Proxy and protect arbitrary TCP/UDP applications through Cloudflare's network with DDoS mitigation", "groups": { "apps": { "description": "Spectrum application configurations that map protocols and ports to origin servers" } } }, "speed": { "description": "Observatory speed tests — run Lighthouse audits, track performance trends, and schedule recurring tests", "groups": { "availabilities": { "description": "Check which speed test regions and configurations are available for your zone" }, "pages": { "description": "Tested pages with their performance history, trends, and individual test results" }, "schedule": { "description": "Scheduled recurring speed tests that automatically run at regular intervals" } } }, "ssl": { "description": "SSL/TLS certificate management — certificate packs, Universal SSL, verification, and TLS mode recommendations", "groups": { "automatic-upgrader": { "description": "SSL automatic mode enrollment — get or update automatic SSL/TLS upgrader settings" }, "recommendations": { "description": "Get the recommended SSL/TLS encryption mode based on your origin server's certificate configuration" } } }, "stream": { "description": "Video encoding, storage, and delivery — upload, live-stream, clip, caption, and embed video at scale", "groups": { "audio-tracks": { "description": "Add, edit, or remove additional audio tracks on a video" }, "captions": { "description": "Upload, generate, or retrieve captions and subtitles for videos in multiple languages" }, "clip": { "description": "Create a new video clip from an existing video by specifying start and end times" }, "copy": { "description": "Import a video from a URL into Stream for processing and delivery" }, "direct-upload": { "description": "Generate a tokenized URL that lets end-users upload video directly to Stream" }, "downloads": { "description": "Create downloadable MP4 renditions of a video for offline viewing" }, "embed": { "description": "Retrieve the HTML embed code snippet for a video" }, "keys": { "description": "Signing keys used to generate short-lived signed URLs for private video playback" }, "live-inputs": { "description": "Enable and disable live input streams" }, "token": { "description": "Generate short-lived signed URL tokens for secure private video playback" }, "typed-downloads": { "description": "Type-specific stream download creation and deletion" }, "videos": { "description": "Aggregate video storage usage statistics for the account" }, "watermarks": { "description": "Watermark profiles that overlay an image on every video in the account" }, "webhooks": { "description": "Webhook notifications for video lifecycle events (ready, error, etc.)" } } }, "tenants": { "description": "Multi-tenant account management — manage tenant accounts, entitlements, and memberships", "groups": { "account-types": { "description": "Account Types operations" }, "accounts": { "description": "Accounts operations" }, "entitlements": { "description": "Entitlements operations" }, "memberships": { "description": "Memberships operations" } } }, "turnstile": { "description": "CAPTCHA-free bot verification widgets that protect forms and APIs without degrading user experience", "groups": { "widgets": { "description": "Turnstile widget configurations — site keys, secret rotation, and challenge mode settings" } } }, "url-scanner": { "description": "Scan URLs for phishing, malware, and other threats — submit scans and retrieve detailed results", "groups": { "response": { "description": "Response operations" }, "responses": { "description": "Raw HTTP response data captured during URL scans" }, "scan": { "description": "Scan operations" }, "scans": { "description": "URL scan requests and results — submit URLs for analysis and retrieve threat verdicts" } } }, "user": { "description": "Your Cloudflare user profile, invitations, organizations, billing, and personal API tokens", "groups": { "billing": { "description": "View billing history and payment profile for your user (deprecated — prefer account-level billing)" }, "firewall": { "description": "Firewall operations" }, "load-balancers.monitors": { "description": "Load Balancers operations" }, "load-balancers.monitors.preview": { "description": "Load Balancers operations" }, "load-balancers.monitors.references": { "description": "Load Balancers operations" }, "load-balancers.pools": { "description": "Load Balancers operations" }, "load-balancers.pools.edit.pools": { "description": "Load Balancers operations" }, "load-balancers.pools.health": { "description": "Load Balancers operations" }, "load-balancers.pools.preview": { "description": "Load Balancers operations" }, "load-balancers.pools.references": { "description": "Load Balancers operations" }, "load-balancers.preview": { "description": "Load Balancers operations" }, "load-balancing-analytics.events": { "description": "Load Balancing Analytics operations" }, "subscriptions": { "description": "View and manage zone-level plan subscriptions owned by your user" }, "tenants": { "description": "Tenants operations" }, "tokens": { "description": "Create and manage personal API tokens scoped to your user for programmatic API access" } } }, "user.analytics": { "description": "User-level traffic analytics — aggregated totals and timeseries across all zones" }, "waiting-rooms": { "description": "Virtual queues that throttle traffic to your site during peak demand with customizable waiting pages", "groups": { "account-waiting-rooms": { "description": "Account-scoped waiting room listing" }, "events": { "description": "Scheduled events that temporarily override waiting room settings for sales, launches, etc." }, "page": { "description": "Custom HTML waiting page templates and preview rendering" }, "rules": { "description": "Rules that bypass or modify waiting room behavior for specific request patterns" }, "settings": { "description": "Zone-level waiting room defaults and cookie configuration" }, "statuses": { "description": "Real-time queue status showing active users, queued users, and estimated wait times" } } }, "workflows": { "description": "Durable, multi-step workflows that run on Workers with automatic retries and state persistence", "groups": { "instances": { "description": "Workflow instance operations" }, "versions": { "description": "Workflow version operations" } } }, "zaraz": { "description": "Server-side tag manager — load third-party tools (analytics, pixels, etc.) from Cloudflare's edge without client-side JS", "groups": { "config": { "description": "Full Zaraz configuration including tools, triggers, and variables for the zone" }, "default": { "description": "Default Zaraz configuration template used as a starting point for new zones" }, "export": { "description": "Export the current Zaraz configuration as a portable JSON document" }, "history": { "description": "Configuration version history — browse and restore previous Zaraz configurations" }, "publish": { "description": "Publish pending Zaraz configuration changes to make them live on the zone" }, "workflow": { "description": "Workflow state for Zaraz configuration changes (draft vs. published)" } } }, "zero-trust": { "description": "Cloudflare's SASE platform — secure access, device posture, DLP, tunnels, gateway policies, and network segmentation", "groups": { "dex": { "description": "Digital Experience Monitoring — synthetic tests, fleet-wide device metrics, and network path diagnostics" }, "dlp.custom-prompt-topics": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.data-classes": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.data-tag-categories": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.data-tag-category-templates": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.data-tags": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.datasets": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.datasets.upload": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.datasets.versions": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.datasets.versions.entries": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.email.account-mapping": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.email.rules": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.entries": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.entries.custom": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.entries.integration": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.entries.predefined": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.limits": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.patterns": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.payload-logs": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.profiles": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.profiles.custom": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.profiles.predefined": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.sensitivity-group-templates": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.sensitivity-groups": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "dlp.sensitivity-levels": { "description": "Data Loss Prevention — detection profiles, custom patterns, datasets, and entry scanning rules" }, "document-fingerprints": { "description": "Document Fingerprints operations" }, "document-fingerprints.create": { "description": "Document Fingerprints operations" }, "document-fingerprints.create.document": { "description": "Document Fingerprints operations" }, "document-fingerprints.get.document": { "description": "Document Fingerprints operations" }, "document-fingerprints.get.fingerprints": { "description": "Document Fingerprints operations" }, "profiles.custom": { "description": "Profiles operations" }, "profiles.predefined": { "description": "Profiles operations" }, "risk-scoring": { "description": "User and entity risk scores derived from behavior signals, used to trigger adaptive access policies" }, "risk-scoring.behaviours": { "description": "User and entity risk scores derived from behavior signals, used to trigger adaptive access policies" }, "risk-scoring.integrations": { "description": "User and entity risk scores derived from behavior signals, used to trigger adaptive access policies" }, "risk-scoring.integrations.references": { "description": "User and entity risk scores derived from behavior signals, used to trigger adaptive access policies" }, "risk-scoring.summary": { "description": "User and entity risk scores derived from behavior signals, used to trigger adaptive access policies" }, "settings": { "description": "Settings operations" } } }, "zones": { "description": "Zones are domains on Cloudflare — list, create, and configure domain settings", "groups": { "fonts": { "description": "Fonts operations" }, "rum": { "description": "Rum operations" }, "speed-brain": { "description": "Speed Brain operations" } } } }, "x-forge-group-info": { "mcp": { "portals": { "description": "Manage MCP portals, attached servers, and Code Mode settings" }, "servers": { "description": "Manage upstream MCP servers, credentials, capabilities, and sync state" } } } }